واجهة برمجة تطبيقات تقارير SonarQube#

تصف هذه المقالة كيفية الوصول برمجيًا إلى تقارير أمان SonarQube المخزنة في منصة Procurize. تغطي واجهة REST لسرد التقارير وتنزيلها بصيغ HTML وPDF وZIP.

نظرة عامة#

يتيح الوحدة الفرعية لتقارير SonarQube للمنظمات تخزين وإدارة تقارير الأمان وجودة الشيفرة التي يولدها SonarQube مركزيًا. تُظهر منصة Procurize هذه البيانات عبر واجهة REST عامة تسمح لك بـ:

سرد بيانات تعريف التقرير لمنظمة أو مجموعة مشاريع أو مشروع
تنزيل تقرير واحد بصيغة HTML أو PDF أو ZIP
تنزيل تقارير مختارة كأرشيف ZIP
تنزيل جميع تقارير مشروع أو مجموعة مشاريع كأرشيف ZIP
جلب أحدث تقارير OWASP Top 10 وCWE Top 25 مباشرة من خدمة SonarQube

تُتيح هذه الإمكانات دمجها مع خطوط أنابيب CI/CD، أنظمة GRC، لوحات التحكم الداخلية، وأدوات إدارة المخاطر الطرفية.

نقاط النهاية#

نقطة النهاية	طريقة	الغرض
`/security/report/list`	GET	سرد بيانات تعريف التقرير للنطاق والإصدار المحددين.
`/security/report/files`	GET	تنزيل التقارير المختارة كأرشيف ZIP.
`/security/report/html`	GET	الحصول على تقرير واحد بصيغة HTML.
`/security/report/pdf`	GET	الحصول على تقرير واحد بصيغة PDF.
`/security/report/zip`	GET	الحصول على تقرير واحد كأرشيف ZIP.
`/security/report/project-files`	GET	تنزيل جميع تقارير مشروع كأرشيف ZIP.
`/security/report/directory-files`	GET	تنزيل جميع تقارير مجموعة مشاريع (دليل) كأرشيف ZIP.
`/security/reports/fetch`	POST	جلب أحدث التقارير من خدمة SonarQube.

المصادقة والتفويض#

نقاط النهاية لسرد التقارير وتنزيلها الموضحة في هذه المقالة لا تتطلب مصادقة.

نقطة النهاية POST /security/reports/fetch تتطلب مصادقة باستخدام رمز API — انظر رموز API.

معرف المنظمة#

يتطلب معظم الطلبات المذكورة هنا معرف المنظمة. يمكنك تمرير إما معرف المنظمة (UUID) أو اسمها المستعار — انظر المعرفات والأسماء المستعارة. يمكنك العثور عليه في لوحة إعدادات المنظمة على https://dashboard.procurize.ai. يرجى ملاحظة أن الوصول إلى لوحة الإعدادات يتطلب تفويضًا، وأن الوصول إلى لوحة إعدادات المنظمة يتطلب دور مستخدم على الأقل مسؤولًا في تلك المنظمة.

المعرفات والأسماء المستعارة#

تقبل معلمات النطاق إما معرف الكيان (UUID) أو اسمًا مستعارًا قابلًا للقراءة البشرية. تجعل الأسماء المستعارة الطلبات أسهل للقراءة وتظل ثابتة عبر البيئات.

المعلمة	القبول	أمثلة على الأسماء المستعارة
`org`	معرف المنظمة أو الاسم المستعار	`aspose`, `groupdocs`
`directory`	معرف الدليل (مجموعة المشاريع) أو الاسم المستعار	`aspose-imaging`, `groupdocs-annotation`
`project`	معرف المشروع أو الاسم المستعار	`aspose-imaging-net`, `groupdocs-annotation-java`

على سبيل المثال، الطلبان التاليان متكافئان:

curl "https://api.procurize.com/security/report/list?org=00000000-0000-0000-0000-000000000001&version=1.0"
curl "https://api.procurize.com/security/report/list?org=aspose&version=1.0"

ملاحظة: لا تُدعم الأسماء المستعارة لمعلمة id في نقاط النهاية الخاصة بالتنزيل الجماعي. مرّر UUID الدليل أو المشروع إلى GET /security/report/project-files وGET /security/report/directory-files.

عنوان URL الأساسي#

جميع نقاط النهاية لواجهة REST تُخدم تحت عنوان URL الأساسي التالي:

https://api.procurize.com

واجهة برمجة تطبيقات تقارير SonarQube REST#

سرد التقارير#

تُعيد التقارير الأمنية المتاحة للنطاق والإصدار المحددين، دون محتوى الملفات. استخدم هذه النقطة لاكتشاف معرفات التقارير التي يمكن تمريرها إلى نقاط تنزيل التقارير.

نقطة النهاية

GET /security/report/list

معلمات الاستعلام

org (اختياري): معرف المنظمة أو الاسم المستعار (مثال: aspose أو groupdocs). أوسع نطاق.
directory (اختياري): معرف الدليل (مجموعة المشاريع) أو الاسم المستعار (مثال: aspose-imaging أو groupdocs-annotation). نطاق أضيق.
project (اختياري): معرف المشروع أو الاسم المستعار (مثال: aspose-imaging-net أو groupdocs-annotation-java). أضيق نطاق.
version (اختياري): نسخة المشروع الدقيقة.
minver (اختياري): الحد الأدنى لنسخة المشروع.
maxver (اختياري): الحد الأقصى لنسخة المشروع.

يجب توفير أحد معلمات النطاق org أو directory أو project. تُعطى الأولويات كالتالي: إذا تم تحديد project يُبحث فقط في ذلك المشروع؛ وإلا إذا تم تحديد directory يُبحث في مجموعة المشاريع بأكملها؛ وإلا يُبحث في المنظمة بأكملها (org). عندما يُحدد org مع project أو directory، يتم التحقق من أن الهدف ينتمي إلى تلك المنظمة.

يجب توفير أحد version أو minver أو maxver. إذا تم تحديد version، تُهمل minver وmaxver.

مثال طلب

curl "https://api.procurize.com/security/report/list?org=aspose&version=1.0"

النطاق إلى مجموعة مشاريع أو مشروع باستخدام الاسم المستعار:

curl "https://api.procurize.com/security/report/list?directory=aspose-imaging&minver=1.0&maxver=2.0"

curl "https://api.procurize.com/security/report/list?project=aspose-imaging-net&version=1.0"

مثال استجابة

{
  "organizationId": "00000000-0000-0000-0000-000000000001",
  "reports": [
    {
      "projectName": "Test product",
      "id": "00000000-0000-0000-0000-000000000002",
      "reportType": "CWE Top 25",
      "reportVersion": 2024,
      "projectVersion": "1.0",
      "date": "2025-12-17T09:05:48.5946432+00:00",
      "uploadDate": "2025-12-17T09:05:48.5946432+00:00",
      "vulnerabilitiesCount": 0,
      "securityRating": "A"
    }
  ]
}

حقول الاستجابة

organizationId: المنظمة التي تنتمي إليها التقارير.
reports[].id: معرف التقرير الفريد. مرّر هذه القيمة إلى نقاط تنزيل التقارير.
reports[].projectName: اسم المنتج الظاهر.
reports[].projectVersion: نسخة المنتج.
reports[].reportType: نوع التقرير (OWASP Top 10 أو CWE Top 25).
reports[].reportVersion: نسخة (سنة) معيار التقرير.
reports[].date: تاريخ إنشاء التقرير.
reports[].uploadDate: تاريخ رفع التقرير إلى Procurize.
reports[].vulnerabilitiesCount: عدد الثغرات المكتشفة.
reports[].securityRating: تقييم الأمان العام (A–E، حيث A هو الأفضل).

تنزيل التقارير حسب المعرف#

ينزل أرشيف ZIP يحتوي على التقارير المختارة. يُضمّن كل تقرير بصيغتي HTML وPDF.

نقطة النهاية

GET /security/report/files

معلمات الاستعلام

org (مطلوب): معرف المنظمة أو الاسم المستعار (مثال: aspose أو groupdocs).
reports (مطلوب): معرفات التقارير المراد تضمينها. كرّر المعلمة لتضمين تقارير متعددة.

مثال طلب

curl "https://api.procurize.com/security/report/files?org=aspose&reports=00000000-0000-0000-0000-000000000002&reports=00000000-0000-0000-0000-000000000003" -o reports.zip

الاستجابة

نوع المحتوى: application/zip
يحتوي جسم الاستجابة على ملف ZIP ثنائي.

يجب على العملاء تدفق الاستجابة وحفظها إلى القرص.

العمل مع تقرير واحد#

نقاط النهاية /security/report/html، /security/report/pdf، و/security/report/zip تُعيد تقريرًا محددًا وتشارك نفس قواعد الاختيار.

اختيار التقرير#

دائمًا ما تكون نوعية الإصدار مطلوبة:

rt (مطلوب): نوع التقرير. القيم المدعومة هي OWASP Top 10 وCWE Top 25.
rv (مطلوب): نسخة التقرير — سنة الإصدار، مثال 2025 لـ OWASP Top 10 أو 2024 لـ CWE Top 25.

يُحدَّد التقرير الفعلي بإحدى طريقتين:

حسب معرف التقرير — مرّر id (معرف التقرير) مع إما project (معرف أو اسم مستعار للمشروع) أو org (معرف أو اسم مستعار للمنظمة). لا تُمرّر version في هذا الوضع.
حسب نسخة المشروع — مرّر project (معرف أو اسم مستعار للمشروع، مثال aspose-imaging-net أو groupdocs-annotation-java) وversion (نسخة المشروع). لا يُستعمل معلمة org في هذا الوضع.

عند تحديد كل من project وorg، تُهمل org.

الحصول على التقرير كـ HTML#

يُظهر تقريرًا واحدًا كصفحة HTML، أو يُعيده كملف HTML قابل للتنزيل.

نقطة النهاية

GET /security/report/html

معلمات الاستعلام

rt (مطلوب): نوع التقرير.
rv (مطلوب): نسخة التقرير.
معلمات اختيار التقرير: راجع اختيار التقرير.
download (اختياري): ضع القيمة true لإرجاع HTML كملف تنزيل (Content-Disposition: attachment). إذا تُركت أو كانت false، يُعاد التقرير مدمجًا داخل المتصفح.

مثال طلب

curl "https://api.procurize.com/security/report/html?rt=OWASP+Top+10&rv=2025&id=00000000-0000-0000-0000-000000000004&project=aspose-imaging-net"

لتنزيل ملف HTML بدلاً من عرضه مدمجًا:

curl "https://api.procurize.com/security/report/html?rt=OWASP+Top+10&rv=2025&project=aspose-imaging-net&version=1.0&download=true" -o report.html

الاستجابة

نوع المحتوى: text/html

الحصول على التقرير كـ PDF#

يرجع تقريرًا واحدًا كملف PDF.

نقطة النهاية

GET /security/report/pdf

معلمات الاستعلام

rt (مطلوب): نوع التقرير.
rv (مطلوب): نسخة التقرير.
معلمات اختيار التقرير: راجع اختيار التقرير.

مثال طلب

curl "https://api.procurize.com/security/report/pdf?rt=CWE+Top+25&rv=2024&project=aspose-imaging-net&version=1.0" -o report.pdf

الاستجابة

نوع المحتوى: application/pdf

الحصول على التقرير كـ ZIP#

يرجع تقريرًا واحدًا كأرشيف ZIP يحتوي على صيغتي HTML وPDF.

نقطة النهاية

GET /security/report/zip

معلمات الاستعلام

rt (مطلوب): نوع التقرير.
rv (مطلوب): نسخة التقرير.
معلمات اختيار التقرير: راجع اختيار التقرير.

مثال طلب

curl "https://api.procurize.com/security/report/zip?rt=CWE+Top+25&rv=2024&id=00000000-0000-0000-0000-000000000004&org=groupdocs" -o report.zip

الاستجابة

نوع المحتوى: application/zip

تنزيل جميع تقارير مشروع#

ينزل أرشيف ZIP يحتوي على جميع تقارير المشروع المحدد، بصرف النظر عن الصيغ (HTML وPDF).

نقطة النهاية

GET /security/report/project-files

معلمات الاستعلام

id (مطلوب): معرف المشروع. لا تُدعم الأسماء المستعارة؛ يجب تمرير UUID المشروع.
rt (اختياري): تصفية حسب نوع التقرير. القيم المدعومة هي OWASP Top 10 وCWE Top 25.
rv (اختياري): تصفية حسب نسخة التقرير (السنة).
version (اختياري): تصفية حسب نسخة المشروع.

إذا لم تُحدَّد أي فلاتر، تُضمّن جميع تقارير المشروع. يمكن دمج الفلاتر وتُطبق بشكل مستقل.

مثال طلب

curl "https://api.procurize.com/security/report/project-files?id=00000000-0000-0000-0000-000000000005" -o project-reports.zip

الاستجابة

نوع المحتوى: application/zip

تنزيل جميع تقارير مجموعة مشاريع#

ينزل أرشيف ZIP يحتوي على تقارير جميع المشاريع داخل الدليل (مجموعة المشاريع) المحدد، بصرف النظر عن الصيغ (HTML وPDF).

نقطة النهاية

GET /security/report/directory-files

معلمات الاستعلام

id (مطلوب): معرف الدليل (مجموعة المشاريع). لا تُدعم الأسماء المستعارة؛ يجب تمرير UUID الدليل.
rt (اختياري): تصفية حسب نوع التقرير. القيم المدعومة هي OWASP Top 10 وCWE Top 25.
rv (اختياري): تصفية حسب نسخة التقرير (السنة).
version (اختياري): تصفية حسب نسخة المشروع.

إذا لم تُحدَّد أي فلاتر، تُضمّن تقارير جميع المشاريع داخل الدليل. يمكن دمج الفلاتر وتُطبق بشكل مستقل.

مثال طلب

curl "https://api.procurize.com/security/report/directory-files?id=00000000-0000-0000-0000-000000000006" -o directory-reports.zip

الاستجابة

نوع المحتوى: application/zip

جلب التقارير من SonarQube#

يرفع أحدث بيانات تقرير الأمان لمنتج من خدمة SonarQube إلى Procurize. تستخرج الخدمة أحدث بيانات القضايا من SonarQube، وتحولها إلى تمثيلات JSON لأحدث إصدارات تقارير OWASP Top 10 وCWE Top 25، وتُعيدها في الاستجابة.

نقطة النهاية

POST /security/reports/fetch

المصادقة

تتطلب هذه النقطة رمز API يُمرَّر في رأس X-API-Key. للحصول على تفاصيل حول إنشاء واستخدام الرموز، انظر رموز API.

معلمات الاستعلام

يُحدَّد مصدر SonarQube بإحدى طريقتين:

حسب المشروع — مرّر project (معرف أو اسم مستعار للمشروع — انظر المعرفات والأسماء المستعارة). لا تُمرّر url أو key.
حسب خدمة SonarQube — مرّر url (عنوان خدمة SonarQube) وkey (مفتاح مشروع SonarQube) معًا. لا تُمرّر project.

مثال طلب

جلب التقرير لمشروع عبر اسمه المستعار:

curl -X POST "https://api.procurize.com/security/reports/fetch?project=aspose-imaging-net" \
  -H "X-API-Key: YOUR_API_TOKEN"

جلب التقرير مباشرة من خدمة SonarQube:

curl -X POST "https://api.procurize.com/security/reports/fetch?url=https://sonarqube.example.com&key=my-project-key" \
  -H "X-API-Key: YOUR_API_TOKEN"

مثال استجابة

{
  "Owasp10_2025": {
    "TOTAL_SECURITY_RATING": "A",
    "TOTAL_COUNT": 0,
    ...
  },
  "Cwe25_2025": {
    "TOTAL_SECURITY_RATING": "A",
    "TOTAL_COUNT": 0,
    ...
  }
}

تُفيد الاستجابة في خطوط أنابيب بناء الإصدارات لتحديد ما إذا كان يجب إيقاف البناء عند اكتشاف ثغرات في صيغ تقارير الأمان العامة.

ملاحظات

يتطلب رفع تقرير إذنًا شخصيًا للمنتج الذي تنتمي إليه التقارير. إذا لم يكن لديك هذا الإذن، أرسل الطلب على أي حال: ستُعيد المنصة 403 Forbidden وتُخطر مديري المنصة تلقائيًا، الذين سيُراجعون الطلب ويُبلغونك بالقرار.
قد لا تكون كل خدمات SonarQube مُسجَّلة على منصة Procurize. لتسجيل خدمة جديدة، تواصل مع مدير المنصة؛ يتطلب ذلك رمز مدير لتلك الخدمة.

معالجة الأخطاء#

تستخدم الواجهة رموز حالة HTTP القياسية.

200 OK: الطلب نجح
204 No Content: التقرير غير موجود
400 Bad Request: معلمات غير صالحة أو طلب غير مُشكل
401 Unauthorized: رمز API مفقود أو غير صالح
403 Forbidden: تم رفض الوصول (مثال: عدم وجود إذن للمنتج)
500 Internal Server Error: خطأ غير متوقع في الخادم

تتضمن استجابات الأخطاء رمز خطأ قابل للقراءة آليًا ورسالة قابلة للقراءة بشريًا.

واجهة برمجة تطبيقات تقارير SonarQube#

نظرة عامة#

نقاط النهاية#

المصادقة والتفويض#

معرف المنظمة#

المعرفات والأسماء المستعارة#

عنوان URL الأساسي#

واجهة برمجة تطبيقات تقارير SonarQube REST#

سرد التقارير#

تنزيل التقارير حسب المعرف#

العمل مع تقرير واحد#

اختيار التقرير#

الحصول على التقرير كـ HTML#

الحصول على التقرير كـ PDF#

الحصول على التقرير كـ ZIP#

تنزيل جميع تقارير مشروع#

تنزيل جميع تقارير مجموعة مشاريع#

جلب التقارير من SonarQube#

معالجة الأخطاء#

انظر أيضًا:#

مقالات ذات صلة#