خزّن بيانات الاعتماد الخاصة بتطبيقك في سحابة Atoms → المفاتيح لإبقاء قيمها خارج Chat والشفرة المصدرية، ولإدارة قيم منفصلة للاختبار والإنتاج.

قبل استخدام المفاتيح، قم بربط المشروع بـ سحابة Atoms. إذا لم يكن مرتبطًا، فاطلب من Agent ربط سحابة Atoms أو اتبع سحابة Atoms.

استخدام مفتاح في سحابة Atoms

قبل أن تبدأ

قبل إضافة مفتاح، تأكد مما يلي:

• أنت تستخدم Atoms على الويب من جهاز سطح مكتب.
• المشروع مرتبط بـ سحابة Atoms.
• أنت مالك مساحة العمل. يمكن فقط لمالكي مساحة العمل إضافة مفاتيح جديدة.

إذا كان المفاتيح أو مفتاح جديد غير متاح، فتأكد من أنك فتحت المشروع المقصود وأنه مرتبط بـ سحابة Atoms. إذا ظل مفتاح جديد غير متاح، فتأكد من أنك مالك مساحة العمل. إذا عرض Atoms رسالة بشأن توفر الخطة أو الاستخدام، فاتبع مسار التوفر أو الترقية الظاهر على الشاشة، ثم حاول مرة أخرى.

إضافة مفتاح اختبار

1. افتح المشروع على جهاز سطح مكتب.
2. في شريط أدوات مساحة العمل نفسه حيث يوجد عارض التطبيقات ، حدد سحابة Atoms.
3. حدد المفاتيح في الشريط الجانبي لـ سحابة Atoms.
4. افتح مفاتيح الاختبار، ثم حدد في هذا المشروع.
5. حدد مفتاح جديد.
6. أكمل الحقول المطلوبة:
   • الاسم: أدخل اسمًا مرجعيًا واضحًا، مثل RESEND_API_KEY. استخدم الأحرف والأرقام والشرطات السفلية، وابدأ بحرف أو شرطة سفلية.
   • القيمة: أدخل بيانات الاعتماد تمامًا كما قدمها المزوّد.
   • الوصف: اشرح الغرض من المفتاح، مثل يُستخدم لإرسال رسائل البريد الإلكتروني الخاصة بالحساب. لا تُضمّن قيمة بيانات الاعتماد.
7. إذا كنت تريد إعادة استخدام المفتاح في مشاريع أخرى، فحدد حفظ في المكتبة.
8. حدد إضافة. عند حفظ المفتاح، يعرض Atoms الرسالة تمت إضافة المفتاح بنجاح.

إضافة مفتاح اختبار

يمكن فقط لمالكي مساحة العمل إضافة مفاتيح جديدة. إذا كنت بحاجة إلى إضافة مفتاح، فاطلب ذلك من مالك مساحة العمل.

استخدام مفتاح محفوظ في Chat

أشر إلى المفتاح المحفوظ بدلًا من إدخال قيمته في رسالة.

1. افتح Chat الخاص بالمشروع في إصدار سطح المكتب من Atoms واكتب #.
2. حدد المفاتيح.
3. ابحث عن المفتاح المحفوظ، ثم حدد اسمه.
4. أخبر Agent بالغرض من المفتاح وما الذي تريد من التكامل أن يفعله.

تضيف قائمة # مرجعًا إلى المفتاح المحفوظ دون إدراج قيمته في رسالتك.

الإشارة إلى مفتاح محفوظ في Chat

اختبار مفتاح محفوظ

1. في عارض التطبيقات، نفّذ إجراءً بسيطًا يستخدم المفتاح.
2. تأكد من أنه ينتج النتيجة المتوقعة، مثل إرسال رسالة بريد إلكتروني تجريبية أو إرجاع بيانات اختبار.
3. راجع أي أخطاء أو سجلات ظاهرة وتأكد من أنها لا تكشف قيمة المفتاح.

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

فهم كيفية عمل المفاتيح

قبل إضافة المفاتيح، من المفيد فهم ما الذي يخزّنه Atoms وكيفية حماية بيانات اعتمادك.

ما الذي يخزّنه Atoms

سحابة Atoms → المفاتيح تخزّن بيانات الاعتماد التي يستخدمها تطبيقك للاتصال بالخدمات الخارجية، مثل مفاتيح API وTokens الوصول.

لكل مفتاح محفوظ اسم ووصف وقيمة خاصة. يساعد الاسم والوصف Agent على فهم وقت استخدام المفتاح، بينما تظل القيمة الخاصة مخفية عن Chat.

مكان الحصول على مفتاح

لا ينشئ Atoms بيانات اعتماد للخدمات الخارجية ولا يوفّرها. يجب أن تحصل عليها من مزوّد الخدمة المعني. اتبع تعليمات المزوّد عند اختيار الأذونات، واختبار المفتاح، والتحقق مما إذا كان تنتهي صلاحيته.

الحفاظ على سرية بيانات الاعتماد الخاصة

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

إذا كانت قيمة خاصة قد انكشفت بالفعل، فاعتبرها مخترقة وألغِها أو بدّلها من خلال المزوّد.

بيانات الاعتماد الخاصة والآمنة للمتصفح

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

تحقق من وثائق المزوّد قبل أن تقرر مكان استخدام بيانات الاعتماد:

• استخدم قيمة في الشفرة المواجهة للمتصفح فقط عندما يذكر المزوّد صراحةً أنه من الآمن كشفها.
• احتفظ ببيانات الاعتماد الخاصة في منطق الخادم أو الواجهة الخلفية، حيث لا تتعرض لزوار التطبيق.

اختيار بيئة المفتاح ومكان تخزينه

عند إضافة مفتاح، تحتاج إلى اتخاذ قرارين منفصلين:

• أي بيئة ستستخدم المفتاح.
• ما إذا كان المفتاح سيبقى في هذا المشروع أو سيكون متاحًا لمشاريع أخرى.

اختيار بيئة

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

اختيار مكان حفظ المفتاح

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

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

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

استخدام قيمة إنتاج منفصلة

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

استخدم قيمة إنتاج منفصلة عندما:

• يوفر المزوّد بيانات اعتماد مختلفة للاختبار وللاستخدام الفعلي.
• لا تريد أن تستخدم بيانات الاعتماد المستخدمة أثناء التطوير بواسطة التطبيق المنشور.

يتم إنشاء قيم الإنتاج من خلال مسار النشر. لا يمكنك إنشاء واحدة عن طريق تحديد مفتاح جديد من علامة تبويب مفاتيح الإنتاج. بعد تهيئة قيمة إنتاج لتطبيق منشور، يمكنك عرضها ضمن سحابة Atoms → المفاتيح → مفاتيح الإنتاج.

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

تحديث بيانات اعتماد أو تدويرها

تحديث قيمة اختبار محفوظة

1. افتح سحابة Atoms → المفاتيح → مفاتيح الاختبار.
2. افتح في هذا المشروع أو مكتبة المفاتيح، حسب مكان حفظ الإدخال.
3. حدد القيمة أو الوصف الخاص بالمفتاح، وأدخل المعلومات المحدّثة، ثم حدد تحديث.
4. انتظر ظهور تم الحفظ بنجاح، ثم اختبر المسار المتأثر مرة أخرى.

تدوير المفتاح المخطط له

اتبع هذه الخطوات عندما تكون بيانات الاعتماد الحالية لا تزال آمنة وتريد استبدالها دون مقاطعة تطبيقك:

1. أنشئ بيانات اعتماد بديلة من خلال مزوّد الخدمة.
2. استبدل قيمة الاختبار في Atoms، ثم اختبر الميزة المتأثرة في عارض التطبيقات.
3. إذا كان التطبيق المنشور يستخدم قيمة إنتاج منفصلة، فاستبدلها وانشر التحديث.
4. اختبر الميزة نفسها على الموقع المنشور.
5. بعد التأكد من أن البديل يعمل بشكل صحيح، ألغِ بيانات الاعتماد القديمة من خلال المزوّد.

إذا كان من المحتمل أن تكون بيانات الاعتماد قد انكشفت

اعتبر بيانات الاعتماد مخترقة وتصرف فورًا:

1. ألغِها أو عطّلها من خلال مزوّد الخدمة.
2. أنشئ بيانات اعتماد بديلة.
3. حدّث قيم الاختبار والإنتاج ذات الصلة في Atoms.
4. اختبر الميزات المتأثرة مرة أخرى في كل من عارض التطبيقات والتطبيق المنشور.
5. أزل أي نسخ مكشوفة من الشفرة المصدرية و Chat ولقطات الشاشة والسجلات حيثما أمكن.

حذف مفتاح أو إزالة قيمته من Atoms لا يلغي بيانات الاعتماد الأصلية. يجب عليك إلغاؤها من خلال مزوّد الخدمة.

إزالة بيانات اعتماد

قبل حذف مفتاح محفوظ، تأكد من أن تطبيقك لم يعد يعتمد عليه:

1. أزل الميزة التي تستخدم المفتاح، أو استبدل مراجعها بمفتاح محفوظ آخر.
2. ألغِ بيانات الاعتماد الأصلية من خلال مزوّد الخدمة حتى لا يعود بالإمكان استخدامها.
3. افتح سحابة Atoms → المفاتيح، وابحث عن الإدخال غير النشط، وحدد حذف، ثم أكد.

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

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

مفتاح الاختبار الخاص بي يعمل في عارض التطبيقات ولكن ليس بعد النشر. لماذا؟

إذا كان مفتاح الاختبار الخاص بك يعمل في عارض التطبيقات ولكن التطبيق المنشور يفشل لأن مفتاحًا مفقود أو فارغ:

1. تحقق مما إذا كانت قيمة الاختبار أو الإنتاج ذات الصلة قد حُفظت قبل آخر عملية نشر أو بعدها. إذا كانت قد حُفظت بعد ذلك، فأعد النشر حتى يسري التغيير.
2. تحقق من أن المفتاح المحفوظ يحتوي على قيمة الاختبار أو الإنتاج الصحيحة. يستخدم التطبيق المنشور قيمة الاختبار ما لم يتم تهيئة قيمة إنتاج منفصلة.
3. راجع أخطاء الخدمة التابعة للحصول على مؤشرات. تشير رسالة “Unauthorized” عادةً إلى مفتاح فارغ أو غير صحيح لتلك البيئة.

إذا استمرت المشكلة، فاتصل بالدعم وضمّن ما يلي:

• رابط المشروع أو عنوان URL المباشر
• اسم المفتاح المتأثر وما إذا كانت المشكلة في قيمة الاختبار أو الإنتاج
• الخطأ الكامل من الخدمة التابعة
• لقطة شاشة منقحة لصفحة التهيئة
• ما إذا كانت تهيئة المفتاح قد حُفظت قبل النشر أو بعده

مهم: قدّم أسماء المفاتيح فقط. لا ترسل قيمًا سرية أو كلمات مرور أو Tokens.