API รายงาน SonarQube#

บทความนี้อธิบายวิธีการเข้าถึงรายงานความปลอดภัยของ SonarQube ที่จัดเก็บในแพลตฟอร์ม Procurize อย่างโปรแกรมเมติก โดยครอบคลุม REST API สำหรับการแสดงรายการรายงานและการดาวน์โหลดในรูปแบบ HTML, PDF และ ZIP

ภาพรวม#

โมดูลย่อย SonarQube Reports ช่วยให้องค์กรสามารถจัดเก็บและจัดการรายงานความปลอดภัยและคุณภาพโค้ดที่สร้างโดย SonarQube อย่างเป็นศูนย์กลาง แพลตฟอร์ม Procurize เปิดเผยข้อมูลนี้ผ่าน REST API สาธารณะที่ให้คุณทำสิ่งต่อไปนี้ได้:

• แสดงเมตาดาต้ารายงานสำหรับองค์กร, กลุ่มโครงการ หรือโครงการ
• ดาวน์โหลดรายงานเดี่ยวในรูปแบบ HTML, PDF หรือ ZIP
• ดาวน์โหลดหลายรายงานเป็นไฟล์ ZIP
• ดาวน์โหลดรายงานทั้งหมดของโครงการหรือกลุ่มโครงการเป็นไฟล์ ZIP
• ดึงรายงาน OWASP Top 10 และ CWE Top 25 ล่าสุดโดยตรงจากบริการ SonarQube

ความสามารถเหล่านี้ทำให้สามารถผสานรวมกับ pipeline CI/CD, ระบบ GRC, แดชบอร์ดภายใน และเครื่องมือจัดการความเสี่ยงของบุคคลที่สามได้

จุดเชื่อมต่อ (Endpoints)#

การตรวจสอบสิทธิ์และการอนุญาต (Authentication and Authorization)#

จุดเชื่อมต่อสำหรับการแสดงรายการและดาวน์โหลดรายงานที่อธิบายในบทความนี้ไม่ต้องการการตรวจสอบสิทธิ์

จุดเชื่อมต่อ POST /security/reports/fetch ต้องการการตรวจสอบสิทธิ์ด้วย API token — ดูรายละเอียดที่ API Tokens

รหัสองค์กร (Organization ID)#

ส่วนใหญ่ของคำขอที่อธิบายไว้ที่นี่ต้องการระบุรหัสองค์กร คุณสามารถส่งได้ทั้งรหัสองค์กร (UUID) หรืออัลลิอัส — ดูที่ Identifiers and Aliases
คุณสามารถหาได้จาก แผงการตั้งค่าองค์กร ที่ https://dashboard.procurize.ai
โปรดทราบว่าการเข้าถึงแผงการตั้งค่าต้องได้รับการอนุญาต และต้องมีบทบาทผู้ใช้อย่างน้อยเป็นผู้ดูแลระบบในองค์กรนั้น

ตัวระบุและอัลลิอัส (Identifiers and Aliases)#

พารามิเตอร์สโคปรับรับได้ทั้ง ID ของเอนทิตี้ (UUID) หรืออัลลิอัสที่อ่านง่าย อัลลิอัสทำให้คำขออ่านง่ายขึ้นและคงที่ข้ามสภาพแวดล้อม

ตัวอย่างเช่น คำขอสองคำต่อไปนี้เทียบเท่ากัน:

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 ของจุดเชื่อมต่อดาวน์โหลดแบบ bulk. ให้ส่ง UUID ของไดเรกทอรีหรือโครงการไปยัง GET /security/report/project-files และ GET /security/report/directory-files

URL พื้นฐาน (Base URL)#

จุดเชื่อมต่อ REST API ทั้งหมดให้บริการภายใต้ URL พื้นฐานต่อไปนี้:

https://api.procurize.com

SonarQube Reports REST API#

แสดงรายการรายงาน (List Reports)#

คืนค่ารายงานความปลอดภัยที่มีสำหรับสโคปและเวอร์ชันที่เลือก โดยไม่รวมเนื้อหาไฟล์ ใช้จุดเชื่อมต่อนี้เพื่อค้นหา ID ของรายงานที่สามารถส่งต่อไปยังจุดเชื่อมต่อดาวน์โหลดได้

Endpoint

GET /security/report/list

พารามิเตอร์ Query

• org (optional): รหัสองค์กรหรืออัลลิอัส (เช่น aspose หรือ groupdocs). สโคปกว้างที่สุด
• directory (optional): รหัสไดเรกทอรี (กลุ่มโครงการ) หรืออัลลิอัส (เช่น aspose-imaging หรือ groupdocs-annotation). สโคปแคบลง
• project (optional): รหัสโครงการหรืออัลลิอัส (เช่น aspose-imaging-net หรือ groupdocs-annotation-java). สโคปแคบที่สุด
• version (optional): เวอร์ชันโครงการที่แน่นอน
• minver (optional): เวอร์ชันโครงการขั้นต่ำ
• maxver (optional): เวอร์ชันโครงการสูงสุด

ต้องระบุอย่างน้อยหนึ่งในพารามิเตอร์สโคป org, directory หรือ project. การจัดลำดับความสำคัญของสโคปคือ: หากระบุ 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: 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 คือดีที่สุด)

ดาวน์โหลดรายงานตาม ID (Download Reports by ID)#

ดาวน์โหลดไฟล์ ZIP ที่บรรจุรายงานที่เลือกไว้ แต่ละรายงานจะมีทั้งรูปแบบ HTML และ PDF

Endpoint

GET /security/report/files

พารามิเตอร์ Query

• org (required): รหัสองค์กรหรืออัลลิอัส (เช่น aspose หรือ groupdocs)
• reports (required): ID ของรายงานที่ต้องการรวมหลายค่าได้โดยทำซ้ำพารามิเตอร์

ตัวอย่างคำขอ

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

การตอบกลับ

• Content-Type: application/zip
• เนื้อหาตอบกลับเป็นไฟล์ ZIP ไบนารี

ควรสตรีมผลลัพธ์และบันทึกลงดิสก์

ทำงานกับรายงานเดี่ยว (Working with a Single Report)#

จุดเชื่อมต่อ /security/report/html, /security/report/pdf และ /security/report/zip คืนค่ารายงานเดียวและใช้กฎการเลือกเดียวกัน

การเลือกรายงาน (Report Selection)#

ประเภทและเวอร์ชันของรายงานต้องระบุเสมอ:

• rt (required): ประเภทรายงาน (OWASP Top 10 หรือ CWE Top 25)
• rv (required): เวอร์ชันของรายงาน — ปีของมาตรฐาน เช่น 2025 สำหรับ OWASP Top 10 หรือ 2024 สำหรับ CWE Top 25

จากนั้นเลือกรายงานด้วยวิธีใดวิธีหนึ่ง:

• โดย ID รายงาน — ส่ง id (ID รายงาน) พร้อมกับ project (ID หรืออัลลิอัสของโครงการ) หรือ org (ID หรืออัลลิอัสขององค์กร) ไม่ต้องส่ง version ในโหมดนี้
• โดยเวอร์ชันโครงการ — ส่ง project (ID หรืออัลลิอัสของโครงการ) และ version (เวอร์ชันของโครงการ) ไม่ใช้พารามิเตอร์ org ในโหมดนี้

หากระบุทั้ง project และ org จะละเว้น org

ดึงรายงานเป็น HTML (Get Report as HTML)#

เรนเดอร์รายงานเดี่ยวเป็นหน้า HTML หรือคืนเป็นไฟล์ HTML ที่ดาวน์โหลดได้

Endpoint

GET /security/report/html

พารามิเตอร์ Query

• rt (required): ประเภทรายงาน
• rv (required): เวอร์ชันรายงาน
• พารามิเตอร์การเลือกรายงาน: ดูที่ Report Selection
• download (optional): ตั้งค่าเป็น 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

การตอบกลับ

• Content-Type: text/html

ดึงรายงานเป็น PDF (Get Report as PDF)#

คืนค่ารายงานเดี่ยวเป็นเอกสาร PDF

Endpoint

GET /security/report/pdf

พารามิเตอร์ Query

• rt (required): ประเภทรายงาน
• rv (required): เวอร์ชันรายงาน
• พารามิเตอร์การเลือกรายงาน: ดูที่ Report Selection

ตัวอย่างคำขอ

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

การตอบกลับ

• Content-Type: application/pdf

ดึงรายงานเป็น ZIP (Get Report as ZIP)#

คืนค่ารายงานเดี่ยวเป็นไฟล์ ZIP ที่บรรจุทั้งเวอร์ชัน HTML และ PDF

Endpoint

GET /security/report/zip

พารามิเตอร์ Query

• rt (required): ประเภทรายงาน
• rv (required): เวอร์ชันรายงาน
• พารามิเตอร์การเลือกรายงาน: ดูที่ Report Selection

ตัวอย่างคำขอ

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

การตอบกลับ

• Content-Type: application/zip

ดาวน์โหลดรายงานทั้งหมดของโครงการ (Download All Reports of a Project)#

ดาวน์โหลดไฟล์ ZIP ที่บรรจุรายงานทั้งหมดของโครงการที่ระบุ ทั้งในรูปแบบ HTML และ PDF

Endpoint

GET /security/report/project-files

พารามิเตอร์ Query

• id (required): ID ของโครงการ (ไม่รองรับอัลลิอัส; ต้องส่ง UUID)
• rt (optional): กรองตามประเภทรายงาน (OWASP Top 10 หรือ CWE Top 25)
• rv (optional): กรองตามเวอร์ชันรายงาน (ปี)
• version (optional): กรองตามเวอร์ชันของโครงการ

หากไม่ระบุตัวกรองใด ๆ จะรวมรายงานทั้งหมดของโครงการ ตัวกรองสามารถรวมกันและทำงานแยกจากกันได้

ตัวอย่างคำขอ

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

การตอบกลับ

• Content-Type: application/zip

ดาวน์โหลดรายงานทั้งหมดของกลุ่มโครงการ (Download All Reports of a Project Group)#

ดาวน์โหลดไฟล์ ZIP ที่บรรจุรายงานของทุกโครงการในไดเรกทอรี (กลุ่มโครงการ) ที่ระบุ ทั้งในรูปแบบ HTML และ PDF

Endpoint

GET /security/report/directory-files

พารามิเตอร์ Query

• id (required): ID ของไดเรกทอรี (ไม่รองรับอัลลิอัส; ต้องส่ง UUID)
• rt (optional): กรองตามประเภทรายงาน (OWASP Top 10 หรือ CWE Top 25)
• rv (optional): กรองตามเวอร์ชันรายงาน (ปี)
• version (optional): กรองตามเวอร์ชันของโครงการ

หากไม่ระบุตัวกรองใด ๆ จะรวมรายงานของทุกโครงการในไดเรกทอรี ตัวกรองสามารถรวมกันและทำงานแยกจากกันได้

ตัวอย่างคำขอ

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

การตอบกลับ

• Content-Type: application/zip

ดึงรายงานจาก SonarQube (Fetch Reports from SonarQube)#

อัปโหลดข้อมูลรายงานความปลอดภัยล่าสุดของผลิตภัณฑ์จากบริการ SonarQube ไปยัง Procurize บริการจะดึงข้อมูลปัญหาล่าสุดจาก SonarQube, แปลงเป็น JSON ของเวอร์ชันล่าสุดของ OWASP Top 10 และ CWE Top 25 แล้วส่งกลับในคำตอบ

Endpoint

POST /security/reports/fetch

การตรวจสอบสิทธิ์

จุดเชื่อมต่อนี้ต้องการ API token ที่ส่งในหัว X-API-Key ดูวิธีสร้างและใช้ token ที่ API Tokens

พารามิเตอร์ Query

แหล่งข้อมูล SonarQube จะเลือกได้หนึ่งในสองวิธี:

• โดยโครงการ — ส่ง project (ID หรืออัลลิอัสของโครงการ — ดูที่ Identifiers and Aliases). ไม่ต้องส่ง url หรือ key
• โดยบริการ SonarQube — ส่ง url (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,
    ...
  }
}

การตอบกลับนี้มีประโยชน์ใน pipeline การสร้างเวอร์ชันเพื่อพิจารณาว่าจะหยุดการสร้างหรือไม่เมื่อพบช่องโหว่ในรูปแบบรายงานความปลอดภัยสาธารณะ

หมายเหตุ

• การอัปโหลดรายงานต้องมีสิทธิ์ส่วนบุคคลสำหรับผลิตภัณฑ์ที่เป็นเจ้าของรายงาน หากคุณไม่มีสิทธิ์นี้ ให้ส่งคำขอได้เลย: แพลตฟอร์มจะคืนค่า 403 Forbidden และแจ้งผู้ดูแลระบบโดยอัตโนมัติ ผู้ดูแลระบบจะตรวจสอบและแจ้งผลการตัดสินใจให้คุณทราบ
• ไม่ใช่ทุกบริการ SonarQube จะลงทะเบียนบนแพลตฟอร์ม Procurize หากต้องการลงทะเบียนบริการใหม่ ติดต่อผู้ดูแลระบบของแพลตฟอร์ม; จำเป็นต้องมี token ของผู้ดูแลระบบสำหรับบริการนั้น

การจัดการข้อผิดพลาด (Error Handling)#

API ใช้รหัสสถานะ HTTP มาตรฐาน

• 200 OK: คำขอสำเร็จ
• 204 No Content: รายงานไม่มีอยู่
• 400 Bad Request: พารามิเตอร์ไม่ถูกต้องหรือรูปแบบคำขอผิด
• 401 Unauthorized: ไม่มีหรือ token ไม่ถูกต้อง
• 403 Forbidden: ปฏิเสธการเข้าถึง (เช่น ขาดสิทธิ์สำหรับผลิตภัณฑ์)
• 500 Internal Server Error: ข้อผิดพลาดเซิร์ฟเวอร์ที่ไม่คาดคิด

การตอบกลับข้อผิดพลาดจะมีโค้ดข้อผิดพลาดที่อ่านได้โดยเครื่องและข้อความที่อ่านได้โดยมนุษย์

ดูเพิ่มเติม (See also)#

• SonarQube Reports Webhooks
• API Tokens – Generation & Management

บทความที่เกี่ยวข้อง#

What are Security Reports?

Security reports repository

How to Configure Security Reports