مفاتيح API

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

إنشاء مفتاح API

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

1. انتقل إلى Settings > API Keys
2. انقر على Create Key
3. أدخل اسماً للمفتاح (مثلاً، "Training Server")
4. انقر على Create Key

اسم المفتاح

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

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

عرض المفتاح

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

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

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

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

أمان المفتاح

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

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

متغير البيئة

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

export ULTRALYTICS_API_KEY="YOUR_API_KEY"

YOLO CLI

قم بتعيين المفتاح باستخدام YOLO CLI:

yolo settings api_key="YOUR_API_KEY"

في الكود

استخدم المفتاح في سكربتات Python الخاصة بك:

import os

# From environment (recommended)
api_key = os.environ.get("ULTRALYTICS_API_KEY")

# Or directly (not recommended for production)
api_key = "YOUR_API_KEY"

رؤوس HTTP

قم بتضمين المفتاح في طلبات API:

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

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

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

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

pip install "ultralytics>=8.4.35"

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

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

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

عرض المفاتيح

يتم إدراج جميع المفاتيح في تبويب Settings > API Keys:

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

إبطال المفتاح

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

1. ابحث عن المفتاح في قسم API Keys
2. انقر فوق زر إبطال (سلة المهملات)
3. تأكيد الإبطال

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

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

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

مفاتيح API الخاصة بمساحة العمل

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

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

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

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

افعل

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

لا تفعل

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

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

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

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

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

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

الحلول:

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

تم رفض الإذن

الحلول:

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

معدل محدود

الحلول:

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

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

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

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

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

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

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

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

هل المفاتيح مرتبطة بمنطقة جغرافية محددة؟

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

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

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