مفاتيح API#

تتيح مفاتيح API الخاصة بـ Ultralytics Platform وصولاً برمجياً آمناً للتدريب عن بُعد، والاستنتاج، والأتمتة. يمكنك إنشاء مفاتيح مسمّاة بتشفير AES-256-GCM لحالات استخدام مختلفة.

إنشاء مفتاح API#

إنشاء مفتاح API جديد:

1. اذهب إلى الإعدادات > مفاتيح API
2. انقر على إنشاء مفتاح (Create Key)
3. أدخل اسماً للمفتاح (على سبيل المثال، "خادم التدريب")
4. انقر على إنشاء مفتاح (Create Key)

اسم المفتاح#

امنح مفتاحك اسماً وصفياً:

• training-server - لأجهزة التدريب عن بُعد
• ci-pipeline - لتكامل CI/CD
• local-dev - للتطوير المحلي

عرض المفتاح#

بعد الإنشاء، يتم عرض المفتاح في مربع حوار التأكيد:

تنسيق المفتاح#

تتبع مفاتيح API هذا التنسيق:

ul_a1b2c3d4e5f60718293a4b5c6d7e8f90a1b2c3d4

• البادئة (Prefix): ul_ تُحدد مفاتيح Ultralytics
• الجسم (Body): 40 حرفاً ست عشرياً عشوائياً
• الإجمالي: 43 حرفاً

أمان المفتاح#

• يتم تخزين المفاتيح باستخدام تشفير AES-256-GCM
• تستخدم عملية المصادقة تجزئة SHA-256 للبحث السريع والمفهرس
• لا يتم تخزين قيم المفاتيح الكاملة كنص عادي أبداً

استخدام مفاتيح API#

متغير البيئة#

قم بتعيين مفتاحك كمتغير بيئة:

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI#

التحقق من المفتاح وحفظه باستخدام YOLO CLI:

yolo login YOUR_API_KEY

قم بإزالة المفتاح المحفوظ باستخدام yolo logout.

رؤوس HTTP#

أدرج المفتاح في طلبات API:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://platform.ultralytics.com/api/...

راجع مرجع REST API للحصول على كافة نقاط النهاية المتاحة.

التدريب عن بُعد#

قم بتمكين بث المقاييس باستخدام مفتاحك.

قم بتثبيت أو تحديث حزمة Ultralytics قبل البدء:

pip install -U ultralytics

export ULTRALYTICS_API_KEY="YOUR_API_KEY"
yolo train model=yolo26n.pt data=coco.yaml project=username/project name=exp1

راجع التدريب السحابي للحصول على دليل التدريب عن بُعد الكامل.

إدارة المفاتيح#

عرض المفاتيح#

يتم سرد كافة المفاتيح في علامة التبويب Settings > API Keys:

تعرض كل بطاقة مفتاح اسم المفتاح، وقيمة المفتاح القابلة للنسخ، ووقتاً نسبياً للإنشاء، وعدد مرات الاستخدام، وزراً للإلغاء.

إلغاء المفتاح#

إلغاء مفتاح تم اختراقه أو لم تعد بحاجة إليه:

1. اعثر على المفتاح في قسم مفاتيح API
2. انقر على زر إلغاء (Revoke) (سلة المهملات)
3. تأكيد الإلغاء

إعادة إنشاء المفتاح#

إذا تم اختراق مفتاح ما:

1. أنشئ مفتاحاً جديداً بنفس الاسم
2. قم بتحديث تطبيقاتك
3. ألغِ المفتاح القديم

مفاتيح API لمساحة العمل#

ترتبط مفاتيح API بمساحة العمل النشطة حالياً:

• مساحة العمل الشخصية: تعمل المفاتيح للمصادقة كحسابك الشخصي
• مساحة عمل الفريق: تعمل المفاتيح للمصادقة ضمن سياق الفريق

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

أفضل ممارسات الأمان#

افعل#

• قم بتخزين المفاتيح في متغيرات البيئة
• استخدم مفاتيح منفصلة لبيئات مختلفة
• قم بإلغاء المفاتيح غير المستخدمة على الفور
• قم بتدوير المفاتيح بشكل دوري
• استخدم أسماء وصفية لتحديد أغراض المفاتيح

لا تفعل#

• لا تقم برفع المفاتيح إلى نظام التحكم في الإصدار
• لا تشارك المفاتيح بين التطبيقات
• لا تسجل المفاتيح في مخرجات التطبيق
• لا تضمن المفاتيح في كود جانب العميل

تدوير المفتاح#

قم بتدوير المفاتيح بشكل دوري لأغراض أمنية:

1. أنشئ مفتاحاً جديداً بنفس الاسم
2. حدث التطبيقات لاستخدام المفتاح الجديد
3. تحقق من عمل التطبيقات بشكل صحيح
4. ألغِ المفتاح القديم

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

خطأ مفتاح غير صالح#

Error: Invalid API key

الحلول:

1. تحقق من نسخ المفتاح بشكل صحيح (بما في ذلك البادئة ul_)
2. تأكد من أن المفتاح لم يتم إلغاؤه
3. تأكد من تعيين متغير البيئة
4. تأكد من استخدام ultralytics>=8.4.104

تم رفض الإذن#

Error: Permission denied for this operation

الحلول:

1. تحقق من أنك مالك المورد أو لديك صلاحية وصول مناسبة لمساحة العمل
2. تأكد من أن المفتاح ينتمي إلى مساحة العمل الصحيحة
3. أنشئ مفتاحاً جديداً إذا لزم الأمر

معدل الاستخدام محدود#

Error: Rate limit exceeded

الحلول:

1. قلل من تكرار الطلبات — راجع جدول حدود المعدل لمعرفة الحدود الخاصة بكل نقطة نهاية
2. قم بتنفيذ التراجع الأسي (exponential backoff) باستخدام رأس Retry-After
3. استخدم نقطة نهاية مخصصة عندما تحتاج إلى سعة استدلال معزولة

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

كم عدد المفاتيح التي يمكنني إنشاؤها؟#

لا يوجد حد صارم لعدد مفاتيح API. يمكنك إنشاء العدد الذي تحتاجه للتطبيقات والبيئات المختلفة.

هل تنتهي صلاحية المفاتيح؟#

لا تنتهي صلاحية المفاتيح تلقائياً. تظل صالحة حتى يتم إلغاؤها. فكر في تنفيذ التدوير لأغراض أمنية.

هل يمكنني رؤية مفتاحي بعد الإنشاء؟#

نعم، قيم المفاتيح الكاملة مرئية في قائمة المفاتيح ضمن Settings > API Keys. تقوم المنصة بفك تشفير مفاتيحك وعرضها بحيث يمكنك نسخها في أي وقت.

هل المفاتيح خاصة بمنطقة جغرافية معينة؟#

تعمل المفاتيح عبر المناطق الجغرافية، لكنها تصل فقط إلى البيانات الموجودة في منطقة حسابك.

هل يمكنني مشاركة مفاتيح API مع أعضاء الفريق؟#

الممارسة الأفضل: اجعل كل عضو في الفريق ينشئ مفتاحه الخاص. بالنسبة لمساحات عمل الفريق، يمكن لكل عضو لديه دور محرر (Editor) أو أعلى إنشاء مفاتيح مخصصة لنطاق مساحة العمل تلك.