واجهة API
ما تستطيع استدعاءه برمجيا اليوم: فحص بوابة الإصدار لخطوط CI بمفتاح API لمساحة العمل، والمفاتيح العامة لحزم الأدلة. والواجهة محدودة في مرحلة بيتا.
يستخدم AI CodeOps في المتصفح. وخلال مرحلة بيتا المفتوحة، واجهة API البرمجية صغيرة عن قصد: نقطة نهاية واحدة لخطوط CI، مع المفاتيح العامة التي تتيح لأي شخص فحص حزمة أدلة. وكل ما عدا ذلك في لوحة التحكم يحتاج إلى جلسة متصفح مسجل الدخول فيها وليس واجهة API مدعومة.
مفاتيح API لمساحة العمل
أنشئ مفتاحا من Configure → API Keys. أعطه اسما؛ ويعرض السر (يبدأ بـ sk-) مرة واحدة، فانسخه عندها. ولا يخزن AI CodeOps إلا تجزئة له.
- يتصرف المفتاح بصفة العضو الذي أنشأه، بدور ذلك العضو الحالي. وإذا أزيل العضو أو فقد دوره صلاحية، يفقدها المفتاح أيضا.
- يستطيع المالكون والمسؤولون والمطورون والأعضاء إنشاء المفاتيح. ولا يستطيع ذلك المشاهدون.
- يرى المسؤولون كل مفتاح في مساحة العمل؛ ويرى الآخرون مفاتيحهم.
- الزر Delete يلغي المفتاح فورا. وتتوقف التكاملات التي تستخدمه عن العمل حالا.
حيث تتضمن خطتك تحديد نطاق المفاتيح، يستطيع مسؤول اختيار Scope لقصر المفتاح على قائمة سماح لعناوين IP (نطاقات CIDR)، وحد للمعدل في الدقيقة، وتاريخ انتهاء، وما يجوز استخدامه فيه: استدعاءات بوابة النماذج، أو فحص بوابة الإصدار، أو كليهما (وهو الافتراضي).
أرسل المفتاح في صورة Bearer token، هكذا:
Authorization: Bearer sk-...
فحص بوابة الإصدار
تجيب نقطة النهاية POST /api/release/check عن سؤال واحد لخط CI لديك: هل يجوز إطلاق طلب السحب هذا أو هذا الإيداع؟ وتطبق الفحوص نفسها المطبقة في بوابات الجودة عبر كل جلسة مست التغيير. ويحتاج المفتاح إلى الصلاحية workspace:read.
curl -sf -X POST "https://console.aicodeops.dev/api/release/check" \
-H "Authorization: Bearer $WORKSPACE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"pullRequestURL":"https://github.com/acme/api/pull/42"}'
استخدم العنوان نفسه الذي تفتح عليه لوحة التحكم. وفي بوابة الإصدار في CI مهام جاهزة للنسخ لكل من GitHub Actions و GitLab CI و Bitbucket Pipelines و Forgejo and Gitea Actions.
حقول الطلب
| الحقل | النوع | الافتراضي |
|---|---|---|
pullRequestURL | عنوان URL | أحد هذين الحقلين مطلوب |
commitSHA | سلسلة نصية، 7 أحرف أو أكثر | |
blockingSeverity | critical, high, medium, low, info | high |
blockOnTestFailure | قيمة منطقية: الاختبارات الفاشلة تمنع، وكذلك تغيير الكود الذي لا نتيجة اختبار له | true |
blockOnBuildFailure | قيمة منطقية: عملية بناء للمستودع لم تنجح تمنع | true |
minCoveragePct | رقم من 0 إلى 100: حد أدنى للتغطية؛ ويرفض إذا لم تذكر أي تغطية | بلا شرط |
requiredWorkflows | مصفوفة سلاسل نصية | لا شيء |
disallowedLicenses | مصفوفة سلاسل نصية، تفحص على قائمة SBOM الخاصة بالمشروع | لا شيء |
requireDeployedTo | اسم بيئة، مثل staging | لا شيء |
blockOnInFlight | قيمة منطقية: الرفض ما دام تشغيل لا يزال جاريا | false |
lookbackMs | المدى الزمني الذي ينظر فيه إلى الخلف، بالمللي ثانية | 14 يوما |
workspaceID | معرف مساحة العمل: فقط حين تستدعي بجلسة لوحة التحكم | مساحة عمل مفتاح API |
تقبل نقطة النهاية GET /api/release/check الأسماء نفسها بوصفها معاملات استعلام (والقوائم مفصولة بفواصل).
دليل الاختبار. مع تفعيل blockOnTestFailure، وهو الافتراضي، تحتاج كل جلسة غيّرت كودا في مشروع إلى نتيجة اختبار فيها أعداد. وإذا لم يعمل لها أي اختبار، أو عمل أمر الاختبار دون أن يذكر أعداد اختبارات، يرفض الفحص برسالة: "The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command". فغياب الدليل ليس نجاحا. وللمشروع الذي لا مجموعة اختبارات له، فعّل Don't run tests for this project في إعدادات المشروع من Plan → Projects؛ وعندها لا يطلب الفحص نتيجة اختبار. ولا تسري القاعدة أيضا على جلسة لم تغير كودا، ولا حين ترسل "blockOnTestFailure": false.
الحد الأدنى للتغطية. مع ضبط minCoveragePct، يجب أن يستوفيه أحدث تشغيل اختبار ذكر التغطية. وإذا لم يذكر أي تشغيل اختبار على التغيير التغطية، يرفض الفحص برسالة: "Coverage wasn't reported, so the 80% floor can't be checked". فالحد الذي لا يمكن فحصه لا ينجح. اجعل أمر الاختبار في المشروع يطبع ملخص تغطية قبل أن تضبط حدا. واترك minCoveragePct خارج الطلب فلا تكون التغطية شرطا.
الاستدعاء بجلسة لوحة التحكم. مفتاح API يحمل مساحة عمله، فلا يرسل CI الحقل workspaceID. وتستطيع جلسة لوحة تحكم مسجل الدخول فيها استدعاء نقطة النهاية أيضا، ويجب أن تسمي مساحة العمل: أضف ?workspaceID=<id> إلى العنوان، أو ضع workspaceID في جسم JSON لطلب POST. ومن دونه يكون الجواب 400. والمعرف هو الجزء الذي بعد /workspace/ في عنوان لوحة التحكم.
الرد
تعيد نقطة النهاية 200 في النتيجتين كلتيهما. فاقرأ الحقل allowed، وهذه حقول الرد:
- الحقل
allowed: القيمةtrueأوfalse - الحقلان
summaryوreasons: شروح بإنجليزية بسيطة - الحقول
blockingFindingsوtestFailuresوtestEvidenceMissingوcoverageShortfallوcoverageNotReportedوlicenseViolationsوlicenseEvidenceMissing: التفاصيل التي خلف الرفض (ويسردlicenseEvidenceMissingالمشاريع التي لا قائمة SBOM لها تفحص حين ترسلdisallowedLicenses) - الحقل
testEvidenceMissing: عنصر{ "workflowRunID", "reason" }لكل جلسة غيّرت كودا وليست لها نتيجة اختبار فيها أعداد؛ وقائمة فارغة حين لا ينقص شيء - الحقل
coverageNotReported: القيمة{ "required": 80 }حين تضبط حدا ولا يذكر أي تشغيل اختبار التغطية؛ والقيمةnullحين يوجد رقم تغطية أو لا يكون حد مضبوطا - الحقل
runsConsidered: الجلسات التي بني عليها الحكم
التغيير الذي لا جلسات مطابقة له يرفض ("No workflow runs found for …"). وكذلك تغيير الكود الذي لا نتيجة اختبار له، كما سبق في فقرة دليل الاختبار. وإذا فشل التقييم، تحصل على allowed: false مع الملخص "Evaluation failed"، فالفحص المعطل لا يجيز تغييرا أبدا.
الأخطاء
| الحالة | المعنى |
|---|---|
| 400 | صيغة JSON غير صالحة أو حقول غير صالحة. ومع جلسة لوحة التحكم: الحقل workspaceID مفقود، وتذكر الرسالة ذلك |
| 401 | لا مفتاح API ولا جلسة لوحة تحكم، أو المفتاح غير صالح |
| 403 | نطاق المفتاح أو دور منشئه لا يسمح بذلك، أو المفتاح يخص مساحة عمل أخرى. ومع جلسة: لست عضوا في مساحة العمل |
| 429 | أكثر من 60 فحصا في الدقيقة لمساحة العمل؛ انظر الترويسة Retry-After |
والفحص نفسه موجود في لوحة التحكم في Review & Gate → Release gate، مع مهمة CI جاهزة للنسخ.
مفاتيح حزم الأدلة
نقطة النهاية GET /api/evidence?action=keys عامة ولا تحتاج إلى مفتاح. وتعيد مفاتيح Ed25519 العامة التي توقّع حزم الأدلة، فتستطيع التحقق من حزمة دون اتصال بالشبكة. وتنزيل حزمة يحتاج إلى عضو مسجل الدخول له صلاحية التدقيق؛ وهو غير متاح بمفتاح API.
مرجع API
صفحة لكل نقطة نهاية، مولدة من مواصفة OpenAPI:
- التحقق مما إذا كان يجوز إطلاق طلب سحب أو إيداع
- المفاتيح التي توقّع حزم الأدلة
- التحقق من حزمة أدلة
- الحيوية والجاهزية
- حالة المكونات
الخطوات التالية
الأسئلة الشائعة
هل توجد واجهة REST API كاملة للجلسات والمشاريع؟
ليس بعد. خلال مرحلة بيتا المفتوحة، لوحة التحكم هي وسيلة تشغيل الجلسات وإدارة المشاريع. ونقاط النهاية في هذه الصفحة هي التي تقبل الوصول البرمجي.
هل تنتهي صلاحية مفاتيح API؟
ليس افتراضيا. يعمل المفتاح إلى أن يحذف، أو يغادر منشئه مساحة العمل، أو يمر تاريخ انتهاء مضبوط في نطاقه.