مفاتيح API
في هذه الصفحة
تتيح مفاتيح API لبرامجك الخاصة، أو لأي نظام تابع لجهة خارجية يدعم BYOK (Bring Your Own Key)، استخدام النماذج التي ينشرها Performance Hub. تُدار المفاتيح ضمن الإعدادات (رمز الترس) ← Service Access & API Keys. يجب أن تكون Organisation Administrator لإدارتها.
"Provision API keys so third-party software and systems that support BYOK (Bring Your Own Key) can connect to models published by Performance Hub."
الشكل 1: قائمة مفاتيح API: التسمية، والمفتاح المخفي جزئيًا، والحالة، والإنفاق والحدود، والنماذج، وآخر استخدام، وإجراءات الصفوف
قائمة المفاتيح
| العمود | المعنى |
|---|---|
| Label | الاسم الاختياري الذي منحته للمفتاح. |
| Key | المفتاح المخفي جزئيًا (مثل phk_7Qm2…Xa9LkP)، ولا يُعرض السر الكامل مرة أخرى أبدًا بعد الإنشاء. |
| Status | Active، أو Provisioning… (لفترة وجيزة أثناء إعداد مفتاح جديد)، أو Disabled (مُبطَل؛ ويظهر الصف باهتًا). |
| Spend / limits | الإنفاق مدى الحياة، ومدى التقدم نحو أي حدود إنفاق مضبوطة على المفتاح. |
| Models | all، أو عدد النماذج المقيّد بها المفتاح. |
| Last used | آخر مرة أجرى فيها المفتاح طلبًا. |
| Actions | Edit وRotate وRevoke (أو Re-activate) وDelete. |
إذا كنت تستخدم Workflows، فيعرض صف Workflows عبارة Managed service بدلًا من مفتاح مخفي جزئيًا. وإذا لم تكن هناك أي مفاتيح على الإطلاق، تعرض القائمة "No API keys yet."
إنشاء مفتاح
انقر على Create key. يُفتح درج Create API key:
الشكل 2: درج Create API key: التسمية، ونوع الاتصال، وحدود الإنفاق، وحدود المعدل، وتقييد النماذج، وتجاوز إعدادات Guardrails
| الإعداد | السلوك |
|---|---|
| Label (optional) | اسم للمفتاح، وعادةً ما يكون اسم النظام المخصص له (مثل Hotel Concierge App أو Clinic Intake Assistant أو Booking Website). يوصى به بشدة، فالتسميات هي الطريقة التي يُنسب بها الاستخدام في Activity وLogs. |
| Connection type | API key: "Generic API keys remain in the API Keys list." External agent: "External agents appear under Connected Services and use this key to authenticate." يُحدَّد عند إنشاء المفتاح، ولا يمكن تغييره لاحقًا. |
| Set spend limits for this key | "Set any combination of daily, monthly and lifetime caps for this key.": Daily limit ("Resets at the start of each day (facility timezone).")، وMonthly limit ("Resets on the 1st of each month (facility timezone).")، وLifetime cap ("Total spend over the lifetime of this key. Never resets."). |
| Rate limits (optional) | "Cap requests and tokens per minute for this key. Leave blank for unlimited.": Requests / min وTokens / min. |
| Restrict models for this key | "Only the selected models will be usable with this key." اختر من النماذج المفعّلة في المنشأة. |
| Override facility guardrails for this key | "Select none to explicitly disable guardrails for this key." عند تشغيله، يستخدم هذا المفتاح اختياره الخاص من Guardrails بدلًا من اختيار المنشأة، بما في ذلك "none". راجع Guardrails. |
انقر على Create key.
السر المعروض لمرة واحدة
يُعرض المفتاح الجديد مرة واحدة فقط، في مربع الحوار Copy your API key:
الشكل 3: يُعرض المفتاح الجديد مرة واحدة: انسخه قبل إغلاق مربع الحوار
"This is the only time the full key is shown. Store it somewhere safe."
انسخه إلى مدير الأسرار لديك قبل النقر على Done. بعد إغلاق مربع الحوار هذا، لا يُعرض إلا الشكل المخفي جزئيًا. إذا فقدت السر، فاستخدم Rotate على المفتاح للحصول على سر جديد.
تعديل مفتاح
انقر على صف المفتاح (أو على رمز القلم Edit) لفتح درج Configure API key، وفيه الإعدادات نفسها المتاحة عند الإنشاء (التسمية، وحدود الإنفاق، وحدود المعدل، وتقييد النماذج، وتجاوز إعدادات Guardrails):
الشكل 4: درج Configure API key
تسري التغييرات خلال لحظات من الحفظ. عندما تكون للمفتاح حدود يومية أو شهرية، يعرض صفه الاستخدام مقارنة بها (Today وThis month وLifetime) وشارة Limit reached عند بلوغ أحدها.
دورة حياة المفتاح: التدوير والإبطال والحذف
لكل إجراء مربع حوار للتأكيد يوضّح بالضبط ما سيحدث:
| الإجراء | التأثير | نص التأكيد |
|---|---|---|
| Rotate | يُصدر سرًا جديدًا (يُعرض مرة واحدة) بالإعدادات نفسها؛ ويتوقف السر القديم عن العمل فورًا. | "A new key will be issued and the current key will stop working immediately." "You will need to reconfigure any services still using the old key. This cannot be undone." |
| Revoke | يعطّل المفتاح فورًا، مع إمكانية التراجع. | "This key will be disabled immediately and any services using it will stop working. You can re-activate it again later." |
| Re-activate | يستعيد مفتاحًا مُبطَلًا (بالسر نفسه). | لا يوجد، إذ يُنفَّذ فورًا. |
| Delete | يزيل المفتاح نهائيًا. | "This permanently deletes the key and any services using it will stop working. This cannot be undone." |
الشكل 5: تأكيد Delete API key
أيها تستخدم: دوّر المفتاح عند الاشتباه في تسريبه (تحتفظ الخدمة بإعداداتها وسجلها، وما عليك سوى تحديث السر)؛ وأبطله لإيقاف نظام مؤقتًا؛ ولا تحذفه إلا عند الاستغناء عن التكامل نهائيًا.
الاتصال باستخدام مفتاح
تعرض بطاقة Connecting to the API أسفل قائمة المفاتيح عنوان URL الأساسي ومثالًا على طلب جاهزًا للنسخ واللصق لبيئتك. راجع ربط تطبيقك للاطلاع على دليل البدء السريع الكامل مع أمثلة SDK ومعالجة الأخطاء.