KapsuleHost توفر لك سطحي تطوير: مفاتيح API محدودة النطاق لقراءة حسابك برمجيًا، وذاكرة تخزين مؤقت بعيدة للبناء تسرع عمليات Turborepo و Nx على أجهزتك الخاصة وأجهزة تشغيل CI.
لا يتم تفعيل أي منهما بشكل افتراضي. يتم إنشاء كليهما من الإعدادات، وكلاهما يمنحك سرًا مرة واحدة بالضبط.
إنشاء مفتاح API
تعيش مفاتيح API تحت الإعدادات، ثم الأمان، في بطاقة مفاتيح API.
- انتقل إلى الإعدادات، ثم الأمان.
- قم بالتمرير إلى مفاتيح API وانقر على مفتاح جديد.
- أعط المفتاح اسمًا. يقترح الحقل "اسم المفتاح (على سبيل المثال: سكريبت أتمتتي)". الاسم لك فقط، لذا اجعله يقول أين سيتم استخدام المفتاح.
- انقر على شرائح النطاق لتحديد ما قد يفعله المفتاح. تم تحديد ثلاثة نطاقات قراءة مسبقًا:
read:sitesوread:emailوread:domains. انقر على شريحة لإضافتها أو إزالتها. - انقر على إنشاء.
يظهر المفتاح الكامل مرة واحدة، في لوحة خضراء برأس "انسخ الآن". انسخه مباشرة في مخزن السرار الخاص بك. عندما تُغلق تلك اللوحة، يختفي المفتاح: يتم الاحتفاظ ببادئة قصيرة فقط، وهي كل ما يمكن لقائمة العرض أن تظهره لك مرة أخرى.
لن يتم عرض المفتاح مرة ثانية ولا يمكن استرجاعه. إذا فقدته، قم بإلغاء هذا المفتاح وإنشاء واحد جديد. لا تلصقه في وثيقة مشتركة أو تذكرة أو التزام أو رسالة دردشة.
فقط الأدوار المالك و المسؤول يمكنها إنشاء مفتاح. أي دور آخر يحصل على خطأ في الأذونات. عند إنشاء مفتاح، تذهب رسالة تنبيه أمني إلى عنوان من أنشأها، لذا فإن رسالة غير متوقعة تستحق التحقيق على الفور.
النطاقات
يتم تقديم سبعة نطاقات:
| النطاق | يمنح |
|---|---|
read:sites | قراءة مواقعك الإلكترونية |
write:sites | محفوظ لعمليات الكتابة على المواقع الإلكترونية |
read:email | قراءة صناديق بريدك |
write:email | محفوظ لعمليات الكتابة على صناديق البريد |
read:domains | قراءة نطاقاتك |
write:domains | محفوظ لعمليات الكتابة على النطاقات |
read:billing | محفوظ لقراءة بيانات الفواتير |
واجهة برمجة تطبيقات العميل للقراءة فقط اليوم. يمكن تحديد نطاقات 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>
معرّف الفريق هو معرّف حساب KapsuleHost الخاص بك، الموضح في تعليمات الإعداد على نفس الصفحة.
تذكر الصفحة توافقها الخاص: Turborepo 1.x والإصدارات اللاحقة، و Nx 16 والإصدارات اللاحقة، وأي أداة تطبق بروتوكول ذاكرة التخزين المؤقت البعيدة نفسه. يتم تخزين القطع الأثرية لكل حساب ولا تتم مشاركتها أبدًا عبر الحسابات.
يجلس عنصرا تحكم إضافيان على البطاقة:
- تدوير الرمز يصدر رمزًا جديدًا ويلغي القديم. أي مهمة CI لا تزال تحتفظ بالرمز القديم تتوقف عن استخدام الذاكرة المؤقتة، لذا قم بالتدوير وحدّث أسرارك معًا.
- تعطيل يوقف الذاكرة المؤقتة تمامًا.
الاختيار بين الاثنين
يحلان مشاكل غير ذات صلة وليسا قابلين للتبديل.
استخدم مفتاح API عندما يحتاج شيء ما خارج KapsuleHost إلى معرفة حالة حسابك: لوحة حالة تسرد مواقعك، سكريبت يحذرك من انتهاء صلاحية النطاقات قريبًا، تصدير مخزون.
استخدم ذاكرة التخزين المؤقت البعيدة للبناء عندما تكون عمليات البناء الخاصة بك بطيئة لأن كل جهاز وكل عملية CI تعيد بناء نفس الحزم دون تغيير. ليس لها أي علاقة بمواقعك المستضافة ولا تقرأ بيانات حسابك.
استكشاف الأخطاء
كل طلب يُرجع 401. تأكد من إرسال الرأس كـ Authorization: Bearer <key> بمسافة واحدة، وأن المفتاح لم يتم قطعه عند نسخه، وأنه لم يتم إلغاؤه. قارن بداية مفتاحك مع عمود البادئة للتأكد من استخدام المفتاح الذي تعتقد أنك تستخدمه.
يرجع الطلب 403 يسمي نطاقًا. المفتاح لا يحمل هذا النطاق. النطاقات ثابتة عند إنشاء المفتاح، لذا أنشئ بديلاً بالنطاقات الصحيحة والغ القديم.
لا أستطيع رؤية بطاقة مفاتيح API. إنها على صفحة الأمان، وليس صفحة المطور. صفحة المطور تحتفظ فقط بذاكرة التخزين المؤقت للبناء.
زر المفتاح الجديد لا يفعل شيئًا. دورك أقل من مسؤول. اطلب من المالك أو مسؤول.
عمليات البناء لا تصل إلى الذاكرة المؤقتة. تحقق من وجود كل من TURBO_TOKEN و TURBO_TEAM في بيئة البناء، وأن الرمز لم يتم تدويره منذ قمت بتعيينه، وأن الصفحة لا تزال تظهر شارة نشط.
ظهر مفتاح لم أنشئه. تعامل معه كما لو كان مخترقًا. الغه، ثم اعمل من خلال أمان الحساب وتحقق من سجل التدقيق لترى ما الذي تغيّر أيضًا.