الحساب
مفاتيح API وصلاحيات المطورين
Kapsule gives you two developer surfaces: scoped API keys for reading your account programmatically, and a remote build cache that speeds up Turborepo and Nx builds on your own machines and CI…
مفاتيح API والوصول للمطورين
Kapsule يوفر لك سطحي عمل للمطورين: مفاتيح API ذات نطاق محدود لقراءة حسابك برمجياً، وذاكرة تخزين مؤقت بناء بعيدة تسرع عمليات بناء Turborepo و Nx على أجهزتك الخاصة وعدائي CI.
لا يتم تفعيل أي منهما بشكل افتراضي. يتم إنشاء كليهما من الإعدادات، وكلاهما يعطيك سراً مرة واحدة فقط.
إنشاء مفتاح API
تقع مفاتيح API تحت الإعدادات، ثم الأمان، في بطاقة مفاتيح API.
- انتقل إلى الإعدادات، ثم الأمان.
- مرر لأسفل إلى مفاتيح API وانقر على مفتاح جديد.
- امنح المفتاح اسماً. يقترح الحقل "اسم المفتاح (على سبيل المثال My automation script)". الاسم موجود فقط لك، لذا اجعله يشير إلى المكان الذي سيتم استخدام المفتاح فيه.
- انقر على رموز النطاق لاختيار ما يمكن للمفتاح القيام به. يتم تحديد ثلاثة نطاقات قراءة مسبقاً:
read:sitesوread:emailوread:domains. انقر على رمز لإضافته أو إزالته. - انقر على إنشاء.
يظهر المفتاح الكامل مرة واحدة، في لوحة خضراء برأس "انسخ الآن". انسخه مباشرة إلى مخزن الأسرار الخاص بك. عند إغلاق اللوحة، يختفي المفتاح: يتم الاحتفاظ ببادئة قصيرة فقط، وهذا كل ما يمكن للقائمة إظهاره مرة أخرى.
لا يتم عرض المفتاح مرة ثانية ولا يمكن استعادته. إذا فقدته، ألغِ هذا المفتاح وأنشئ واحداً جديداً. لا تلصقه في وثيقة مشتركة أو تذكرة أو التزام أو رسالة دردشة.
فقط الأدوار المالك و المسؤول يمكنها إنشاء مفتاح. أي دور آخر يحصل على خطأ الأذونات. عند إنشاء مفتاح، يتم إرسال تنبيه أمان بالبريد الإلكتروني إلى عنوان من قام بإنشاؤه، لذا فإن واحداً غير متوقع منها يستحق التحقيق على الفور.
النطاقات
يتم تقديم سبعة نطاقات:
| النطاق | يمنح |
|---|---|
read:sites | قراءة مواقعك الإلكترونية |
write:sites | محجوز لعمليات الكتابة على المواقع الإلكترونية |
read:email | قراءة صناديق البريد الخاصة بك |
write:email | محجوز لعمليات الكتابة على صناديق البريد |
read:domains | قراءة النطاقات الخاصة بك |
write:domains | محجوز لعمليات الكتابة على النطاقات |
read:billing | محجوز لقراءة بيانات الفواتير |
API العميل للقراءة فقط حالياً. نطاقات write: و read:billing يمكن اختيارها على مفتاح، لكن لا يوجد حالياً أي نقطة نهاية عميل تستهلكها، لذا فإن منحها لا يغير شيئاً. امنح فقط نطاقات القراءة التي تحتاجها فعلاً وأعد النظر في المفتاح عند شحن نقاط النهاية الكتابية.
استخدام مفتاح
أرسل المفتاح كرمز حامل على رأس Authorization.
curl https://kpanel.kapsulehost.com/api/v1/sites \
-H "Authorization: Bearer YOUR_KEY_HERE"
تقبل ثلاث نقاط نهاية مفتاح API عميل:
| نقطة النهاية | النطاق المطلوب | الإرجاع |
|---|---|---|
GET /api/v1/sites | read:sites | مواقعك الإلكترونية، مع النطاق ونوع التطبيق والحالة |
GET /api/v1/domains | read:domains | النطاقات الخاصة بك، مع الحالة وانتهاء الصلاحية |
GET /api/v1/mailboxes | read:email | صناديق البريد الخاصة بك |
طلب بدون مفتاح أو مفتاح غير معروف أو مفتاح ملغى يرجع 401. مفتاح صالح بدون النطاق الصحيح يرجع 403 برسالة تسمي النطاق المطلوب. كل استدعاء ناجح يحدّث طابع زمني آخر استخدام للمفتاح.
استجوب بلطف. تقرأ نقاط النهاية هذه بيانات الحساب المباشرة، والحلقة الضيقة ضدها لا تختلف عن الإساءة. مرة واحدة في الدقيقة سخية لأي شيء تحتاجه لوحة التحكم؛ مرة واحدة في الساعة عادة ما تكون كافية.
مراجعة وإلغاء المفاتيح
يسرد جدول مفاتيح API كل مفتاح نشط حسب الاسم و البادئة (بداية المفتاح المرئية) و النطاقات. انقر على إلغاء في نهاية الصف لحذفه.
يأخذ الإلغاء مفعوله على الفور وليس هناك حوار تأكيد. الطلب التالي باستخدام هذا المفتاح يفشل مع 401. لا يمكن استعادة مفتاح ملغى، لذا تأكد من معرفتك ما يستخدمه قبل النقر.
تنتمي المفاتيح إلى الحساب، وليس إلى الشخص الذي أنشأها. إزالة زميل من صفحة الفريق لا تلغي المفاتيح التي أنشأها. قم ببناء مراجعة مفاتيح في الإبعاد: أزل الشخص، ثم تعال هنا وأبطل أي شيء أنشأه.
يتم تسجيل إنشاء وإلغاء المفاتيح في سجل التدقيق تحت إجراءات api_key.*، مع الفاعل وعنوان IP الأصلي.
ذاكرة التخزين المؤقت للبناء البعيد
تقدم صفحة المطور، في مجموعة متقدمة من سكة الإعدادات، ذاكرة تخزين مؤقت بناء بعيدة. تصف اللوحة بأنها طريقة "تسريع عمليات بناء Turborepo و Nx بمشاركة ذاكرة تخزين مؤقت موزعة عبر الآلات وخطوط أنابيب CI".
- انتقل إلى الإعدادات، ثم المطور.
- انقر على تفعيل ذاكرة التخزين المؤقت البعيدة.
- انسخ الرمز من اللوحة برأس "تم إنشاء رمز جديد. انسخه الآن، لن يتم عرضه مرة أخرى".
ثم عيّن متغيري البيئة في تكوين CI أو .env.local المحلي:
TURBO_TOKEN=<your-token>
TURBO_TEAM=<your-account-id>
معرّف الفريق هو معرّف حساب Kapsule الخاص بك، المعروض في تعليمات الإعداد على نفس الصفحة.
تنص الصفحة على توافقيتها الخاصة: Turborepo 1.x وما بعده، Nx 16 وما بعده، وأي أداة تطبق نفس بروتوكول ذاكرة التخزين المؤقت البعيد. يتم تخزين القطع الأثرية لكل حساب ولا يتم مشاركتها بين الحسابات.
يوجد عنصرا تحكم إضافيان على البطاقة:
- تدوير الرمز يصدر رمزاً جديداً ويلغي الرمز القديم. أي عمل CI لا يزال يحتفظ بالرمز القديم يتوقف عن استخدام ذاكرة التخزين المؤقت، لذا قم بالتدوير وتحديث أسرارك معاً.
- تعطيل يوقف ذاكرة التخزين المؤقت تماماً.
الاختيار بين الاثنين
يحلان مشاكل غير مرتبطة وليسا قابلين للتبديل.
استخدم مفتاح API عندما يحتاج شيء خارج Kapsule إلى معرفة حالة حسابك: لوحة حالة تسرد مواقعك، سكريبت يحذرك من النطاقات التي تنتهي صلاحيتها قريباً، تصدير الجرد.
استخدم ذاكرة التخزين المؤقت للبناء البعيد عندما تكون عمليات البناء بطيئة لأن كل آلة وكل تشغيل CI يعيد بناء نفس الحزم دون تغيير. لا علاقة لها بمواقعك المستضافة ولا تقرأ بيانات حسابك.
إذا كنت تنتشر من Git بدلاً من استدعاء API، ابحث عن Kapsule Orbit بدلاً من ذلك. يبني ويشحن من مستودعك مباشرة، مع التعامل مع التخزين المؤقت للبناء لك.
استكشاف الأخطاء
كل طلب يرجع 401. تأكد من إرسال الرأس كـ Authorization: Bearer <key> بمسافة واحدة، والمفتاح لم يتم قطعه عند نسخه، وأنه لم يتم إلغاؤه. قارن بداية مفتاحك مع عمود البادئة للتأكد من أنك تستخدم المفتاح الذي تعتقد أنك تستخدمه.
طلب يرجع 403 يسمي نطاقاً. المفتاح لا يحمل هذا النطاق. النطاقات محددة عند إنشاء المفتاح، لذا أنشئ استبدالاً بالنطاقات الصحيحة وأبطل القديم.
لا أستطيع رؤية بطاقة مفاتيح API. إنها على صفحة الأمان، وليس صفحة المطور. تحتفظ صفحة المطور فقط بذاكرة التخزين المؤقت للبناء.
زر المفتاح الجديد لا يفعل أي شيء. دورك أقل من المسؤول. اطلب من المالك أو مسؤول.
عمليات البناء لا تضرب ذاكرة التخزين المؤقت. تحقق من وجود كل من TURBO_TOKEN و TURBO_TEAM في بيئة البناء، أن الرمز لم يتم تدويره منذ قيامك بتعيينه، وأن الصفحة لا تزال تعرض شارة نشط.
ظهر مفتاح لم أنشئه. تعامل معه كخطر. أبطله، ثم انتقل عبر أمان الحساب وتحقق من سجل التدقيق لمعرفة ما تغير آخر.