الأسرار في مساحة العمل

السر قيمة واحدة مسماة تملكها مساحة العمل، تُختم عند الحفظ، ويُشار إليها بالاسم من أداة. أنشئه مرة واحدة، ثم اختره من قائمة بعد ذلك، فيبقى مفتاح API في مكان واحد بدلاً من لصقه في كل أداة تحتاجه. ولا يصبح السر أبداً إلا header في استدعاء خارجي. أما اسم المستخدم وكلمة المرور، أو رمز bearer، أو OAuth2، فاستخدم بدلاً منها اتصال مصادقة.

ما تحتاج إليه

• عضوية في مساحة العمل. عناصر التحكم في الأسرار تطلب العضوية ولا تطلب صلاحية إضافية، لذلك يستطيع كل عضو إنشاء سر وحذفه.
• القيمة نفسها، في شكل تستطيع لصقه. لن تستطيع قراءتها مرة أخرى بعد ذلك.

الخطوات

الخطوة 1: افتح صفحة الإعدادات

انتقل إلى الإعدادات في قائمة الوكلاء. تفتح الصفحة على تبويب الأسرار، تحت السطر «قيم سرية قابلة لإعادة الاستخدام تستخدمها أدواتك.»

الخطوة 2: اضغط سر جديد

يفتح سر جديد نافذة من حقلين بعنوان سر جديد. ويظهر الزر نفسه داخل الحالة الفارغة عندما لا يكون في مساحة العمل أي سر بعد.

الخطوة 3: سمِّه

الاسم مطلوب، وهو الشيء الوحيد الذي تراه في القائمة بعد ذلك، لذا يجب أن يحمل المعنى وحده. الحقل بعرض ثابت للأحرف، والعنصر النائب فيه هو STRIPE_KEY. تُحذف المسافات في البداية والنهاية، ويجب أن يكون الاسم فريداً داخل مساحة العمل.

الخطوة 4: الصق القيمة

القيمة مطلوبة، ولا تُعاد عرضها أبداً. يكبر الصندوق مع المحتوى، فيتسع مفتاح طويل أو قيمة من عدة أسطر.

الخطوة 5: احفظ

يُنشئ حفظ السر ويعيدك إلى القائمة.

للحصول على أفضل نتيجة

لن ترى القيمة مرة أخرى، ولا يمكنك تعديلها، لذلك الاسم هو المقبض الوحيد الذي تملكه. سمِّ النظام والبيئة ونوع بيانات الاعتماد.

الموصى به

STRIPE_LIVE_SECRET_KEY
ORDERS_API_KEY_PROD

الأقل فاعلية

key
new_key_2

ماذا يحدث بعد ذلك

تُختم القيمة قبل تخزينها. تُشفَّر بـ AES-256-GCM بمفتاح تصدره AWS KMS لهذا السر وحده، ومرتبط بمساحة العمل الخاصة بك، فلا يمكن فتح قيمة سر في سياق سر آخر.

بعد الحفظ تحصل على المعرّف والاسم والتواريخ وتلميح مُقنّع بالشكل ••••AB12: أربع نقاط ثم آخر أربعة أحرف من القيمة. القيمة نفسها لا تُعاد أبداً.

يظهر السر الجديد في القائمة مع أيقونة قفل واسمه، وتحته شريحة استخدام تقول غير مستخدم أو مستخدم في أداة واحدة، أو السطر نفسه مع العدد عندما يكون أكثر من واحد. وعند فتح الشريحة تُسرد الأدوات بأسمائها تحت مستخدم بواسطة.

أين يمكن استخدام السر

السر دائماً header. وهناك موضعان يقبلانه.

يرفض الموضعان أي شيء آخر عند الحفظ. معامل Webhook في المسار أو الاستعلام أو مجموعة الجسم يُرفض بالرسالة Secret parameter "<name>" is only allowed in headers، وحقل OpenAPI يُرفض بالرسالة Secret values are only allowed on header parameters (operation "<name>", field "<name>").

يجب أن يكون السر الذي تشير إليه الأداة موجوداً عند حفظ الأداة. السر المفقود يُرفض بالرسالة Referenced secret not found لأداة Webhook، وبالرسالة Referenced secret not found for operation "<name>" لاستيراد OpenAPI.

عند إجراء الاستدعاء تُقرأ القيمة، وتوضع في الـ header المسمّى وتُرسل. لا تُحفظ على الأداة، ولا تُكتب في الطلب الذي يعرضه لك إيكونوڤا، ولا تُعطى للوكيل أبداً. وتبقى القيمة المفتوحة في الذاكرة خمس دقائق على الأكثر، ولا تُكتب في أي مكان.

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

تدوير القيمة

لا يوجد تعديل. يُنشأ السر مرة واحدة، ثم يُشار إليه أو يُحذف، لذلك القيمة الجديدة تعني سراً جديداً:

1. أنشئ سراً ثانياً بالقيمة الجديدة وباسم جديد.
2. أعِد توجيه كل أداة كانت تستخدم السر القديم.
3. احذف السر القديم.

افعل ذلك بهذا الترتيب. الحذف أولاً يكسر الأدوات التي ما زالت تشير إلى السر القديم، والخطوة 2 هي التي تفك قفل الحذف في الخطوة 3.

حذف سر

حذف في قائمة الصف يطلب التأكيد، ويذكر اسم السر ويحذّر من أن «الأدوات التي تشير إليه ستتوقف عن العمل.»

قبل إزالة السر يتحقق إيكونوڤا مما إذا كانت أي أداة Webhook في مساحة العمل ما زالت تشير إليه. إذا كانت هناك واحدة، يُرفض الحذف برمز 409 ورسالة Secret is in use by a tool، وتعرضها البوابة كـ«مستخدم بواسطة أداة. أزل المرجع أولاً.»

الحدود

حل المشكلات

"Duplicate value for name"

سر آخر في مساحة العمل هذه يستخدم الاسم نفسه. الأسماء فريدة لكل مساحة عمل، والفحص يطابق الاسم حرفياً. اختر اسماً آخر.

«مستخدم بواسطة أداة. أزل المرجع أولاً.»

ما زالت أداة Webhook تحمل معامل header يشير إلى هذا السر. افتح شريحة الاستخدام على الصف لترى الأدوات، وأزل المرجع من كل واحدة، ثم احذف مرة أخرى.

واجهة API ترد بـ 401 بعد تغيير في الأسرار

الـ header مفقود، وليس خاطئاً. السر الذي لا يمكن قراءته عند إجراء الاستدعاء يُترك خارج الطلب بدلاً من أن يفشل الاستدعاء كله، فيخرج الطلب بدونه. تحقق من أن السر ما زال موجوداً، وأن الأداة ما زالت تسميه.

السر الذي أنشأته للتو غير موجود في منتقي الأداة

المنتقي يحمّل القائمة مرة واحدة عند رسمه. أعد فتح نموذج الأداة ليجلب القائمة من جديد.

الأسئلة الشائعة

هل أستطيع رؤية السر مرة أخرى بعد إنشائه؟

لا. القيمة لا تُعاد في أي مكان، ولا توجد في البوابة أداة لكشفها. تحصل على تلميح مُقنّع بآخر أربعة أحرف، ولا شيء غير ذلك.

هل يستطيع الوكيل قراءة السر؟

لا. تُملأ معاملات السر بعد أن ينتج الوكيل وسائطه، وتُكتب القيمة مباشرة في الـ header الخارج.

هل أستطيع استخدام السر في عنوان URL أو في سلسلة الاستعلام أو في الجسم؟

لا. يقصر كل من منشئ Webhook ومحرر عمليات OpenAPI الأسرار على معاملات header، ويرفض أي شيء آخر عند الحفظ.

هل يُشارك السر بين الوكلاء؟

نعم. الأسرار تملكها مساحة العمل، لا الوكيل. وأي أداة في مساحة العمل تستطيع الإشارة إلى سر، وكل وكيل يستخدم تلك الأداة يحصل على القيمة نفسها.

ما الفرق بين السر واتصال المصادقة؟

السر قيمة واحدة مبهمة تصبح header تسميه أنت. أما اتصال المصادقة فهو بيانات اعتماد كاملة مع طريقة مصادقة مرفقة، ويُنتج دائماً header Authorization بنفسه. استخدم السر لـ header مفتاح API، واستخدم اتصال المصادقة لـ basic أو bearer أو OAuth2.

هل يحذف حذف الأداة الأسرار التي استخدمتها؟

لا. يبقى السر في مساحة العمل، وتنخفض شريحة الاستخدام إلى غير مستخدم بعد أن لا يشير إليه أي شيء.

صفحات ذات صلة

• اتصالات المصادقة: بيانات اعتماد basic وbearer وOAuth2
• أدوات Webhook: المكان الذي يصبح فيه السر header في الطلب
• عمليات أداة OpenAPI: ثبّت سراً على header عملية واحدة
• نظرة عامة على الأدوات: الفرق بين الأنواع الأربعة للأدوات