رموز Kapsule Orbit API و REST API

تتيح رموز API لسكريبت أو خط أنابيب CI أو أدواتك الخاصة قيادة Kapsule Orbit بدون جلسة متصفح: تشغيل النشر وإبلاغ نتائج فحوصات CI وتنزيل القطع الأثرية للبناء وإدارة مهام cron والمزيد، جميعها مصرح بها برمز Bearer تحدد نطاقه بنفسك.

حيث توجد الرموز

افتح Kapsule Orbit واختر Tokens من التنقل من المستوى الأعلى. الصفحة بعنوان API Access Tokens وتنص على قاعدتها في البداية: تظهر الرموز مرة واحدة عند الإنشاء.

توثيق النقطة النهائية الكاملة على بعد نقرة واحدة. بطاقة API Reference بها زر View docs الذي يفتح المرجع داخل اللوحة لكل نقطة نهاية في Kapsule Orbit.

إنشاء رمز

1. انقر على New token.
2. أعطها Token name. سمّها باسم الشيء الذي سيستخدمها، على سبيل المثال سير العمل CI، بحيث يكون المخزون سهل القراءة لاحقًا.
3. اختر Scopes الخاص بها.
4. اختياريًا، عيّن Expiry. اتركه فارغًا للحصول على رمز لا ينتهي.
5. انقر على Create token.

يتم عرض الرمز الأولي مرة واحدة، تحت عنوان One-time reveal، بزر نسخ. الصقه مباشرة في مخزن CI السري الخاص بك. لا توجد طريقة لرؤيته مرة أخرى: يتم تخزين SHA-256 فقط من الرمز، لذا حتى KapsuleHost لا يمكنها استرجاعه لك.

يمكن للحساب أن يحتوي على ما يصل إلى 20 رمزًا نشطًا. رفض إنشاء الرمز الحادي والعشرين برسالة تخبرك بإلغاء رمز موجود أولاً.

النطاقات

النطاقات هي النقطة بأكملها للرموز: يحمل كل منها فقط الأذونات التي منحتها له.

الرمز الجديد يستخدم افتراضيًا deploy:write و project:read، وهو ما تحتاجه خط أنابيب النشر وليس أكثر.

امنح أصغر مجموعة تقوم بالعمل. رمز يحتاج فقط إلى الإبلاغ عن نتيجة CI لا يحتاج إلى project:write. سكريبت المراقبة للقراءة فقط لا يحتاج إلى أي نطاق كتابة. كل نقطة نهاية في المرجع تسرد الحد الأدنى من النطاق الذي تتطلبه.

استخدام رمز

المصادقة هي رأس Bearer مقابل قاعدة API، https://kapsulehost.com:

curl -X POST https://kapsulehost.com/api/orbit/$ORBIT_PROJECT_ID/deployments \
  -H "Authorization: Bearer $ORBIT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"branch":"main"}'

تحمل صفحة الرموز مقتطف CI/CD usage جاهز ومسار عمل GitHub Actions starter. يتم حفظ المبتدئ باسم .github/workflows/orbit-deploy.yml ويحتاج إلى سريين في المستودع، ORBIT_TOKEN و ORBIT_PROJECT_ID. انسخ كليهما من الصفحة بدلاً من نسخها يدويًا.

ما يغطيه API

يوثق المرجع داخل اللوحة كل منطقة مع معاملات وأقل نطاق مطلوب:

• Deployments: تشغيل النشر، اختياريًا على فرع مسمى، اختياريًا مجدول لوقت مستقبلي بين خمس دقائق وثلاثين يومًا مقدمًا، مع ملاحظة تصل إلى 500 حرف. يدعم القائمة البحث الغامض عبر الالتزام والرسالة والفرع والمؤلف، بالإضافة إلى عوامل تصفية على الفرع والحالة والبيئة، مع ترقيم المؤشر حتى 100 نتيجة لكل صفحة.
• Deployment checks: تسجيل بوابة جودة في بداية وظيفة CI الخاصة بك، ثم الإبلاغ عن النتيجة عند انتهائها. فشل الفحص required يحرك النشر إلى FAILED ويعيد البيئة إلى آخر نشر ناجح، وهذا كيفية جعل مجموعة الاختبارات الخاصة بك بوابة نشر حقيقية.
• Branch protection: قواعد نمط الكرة العالمية التي تحظر النشر التلقائي حتى تمر الفحوصات المطلوبة واختياريًا موافقة شخص ما. حتى عشر قواعد لكل مشروع.
• Build artifacts: احصل على عنوان URL لتنزيل موقع مؤقت لمخرجات النشر المترجمة الناجحة. عنوان URL صالح لمدة خمس عشرة دقيقة.
• Project transfer: بدء وإلغاء والتحقق من حالة النقل إلى حساب آخر. اطلع على Transferring an Orbit Project.
• Cron jobs: القائمة والإنشاء والتحديث والحذف والتشغيل وقراءة سجل التنفيذ. اطلع على Orbit Cron Jobs.
• Timeline annotations: إنشاء وإدارة الحادث والإصدار والمرحلة والملاحظة والعلم التعليقات التوضيحية. اطلع على Orbit Timeline Annotations.
• Status page: قراءة وكتابة تكوين صفحة الحالة العامة. اطلع على Orbit Status Page.
• Edge functions: القائمة والإنشاء والتحديث ونشر معالجات الحافة. اطلع على Orbit Edge Functions.

يعمل مصادقة الجلسة من اللوحة جنبًا إلى جنب مع رموز Bearer، لذا يمكن عمومًا استدعاء نقطة نهاية يمكنك استدعاؤها من المتصفح من سكريبت أيضًا.

ذاكرة التخزين المؤقت البعيدة Turbo

تحمل صفحة الرموز أيضًا بطاقة Remote Build Cache. إنها تطبق بروتوكول Turborepo Remote Cache، مما يتيح لـ monorepo مشاركة ذاكرة تخزين مؤقت البناء بين تشغيل CI وأجهزة المطورين.

قم بتفعيلها على البطاقة وانسخ الرمز الذي تنتجه وعيّنه إلى جانب معرف حسابك باسم TURBO_TEAM في بيئة CI الخاصة بك. يتم قبول القطع الأثرية حتى 150 ميجابايت لكل منها. تقدم البطاقة أيضًا Rotate token و Disable.

إذا كان CI في monorepo الخاص بك ينفق معظم وقته في إعادة بناء الحزم التي لم تتغير، فهذا هو الشيء ذو القيمة الأعلى الوحيد على الصفحة.

إدارة المخزون

تسرد Token inventory كل رمز نشط مع:

• متى تم Created.
• متى تم Last used، أو Never.
• متى Expires، مع شارة expired بمجرد انتهائها.

عمود Last used هو الذي يجب تدقيقه. رمز لم يستخدم أبدًا إما أنه خاطئ في الإعدادات أو منسي، وعلى أي حال فهو بيانات اعتماد تجلس حول لا تفعل شيئًا. تلميح الصفحة الخاص به يقول ذلك بوضوح: إلغاء أي شيء لا تعترف به.

إلغاء رمز

انقر على عنصر التحكم في الإلغاء على الصف. التأكيد صريح: كل شيء يوثق بهذا الرمز يفقد الوصول على الفور، وهذا لا يمكن التراجع عنه.

ألغِ عند إيقاف خط الأنابيب أو عندما يغادر شخص لديه وصول إلى أسرار CI أو في اللحظة التي تشك فيها في أن الرمز قد تسرب. لا يوجد إلغاء جزئي وبدون فترة سماح، وهو بالضبط ما تريده في حالة التسرب.

استكشاف الأخطاء والإصلاح

401 Unauthorized. الرأس خاطئ أو تم إلغاء الرمز أو انتهت صلاحيته. تحقق من أن الرأس هو Authorization: Bearer <token> بمسافة واحدة، وأن سر CI الخاص بك لا يحتوي على سطر جديد زائدة.

403 Forbidden. الرمز صالح لكنه يفتقر إلى النطاق لتلك النقطة النهاية. يسرد المرجع الحد الأدنى من النطاق لكل نقطة نهاية. النطاقات مثبتة عند الإنشاء، لذا أنشئ رمزًا جديدًا بالمجموعة الصحيحة.

429 on creation. أنت في حد الرمز العشرين. ألغِ شيئًا من المخزون.

The artifact URL stops working. عناوين URL الموقعة مؤقتًا تستمر خمس عشرة دقيقة. طلب واحد جديد بدلاً من تخزين عنوان URL.

A scheduled deployment is rejected. يجب أن يكون الوقت المجدول بين خمس دقائق وثلاثين يومًا في المستقبل.

أين تذهب بعد ذلك

• Deploying Your Project لمعرفة ما يفعله النشر الذي تم تشغيله بالفعل.
• Orbit Deployment Pipeline لمعرفة البوابات التي سيلبيها نشر API الخاص بك.
• Orbit Plan Limits لمعرفة ما يتضمنه خطتك.