البدء السريع

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

لا يمكن لمفتاح API القياسي استدعاء نقاط نهاية إدارة المفاتيح أو الحراس. قد يتلقى مفتاح الإدارة الصالح استجابة 403 Forbidden حين لا يمتلك مالكه دور الحساب المطلوب بعد الآن.

استخدم GET /api/v1/keys للاطلاع على المفاتيح المرئية لحساب مفتاح الإدارة:

استخدم المعرّفات العامة المُعادة لطلبات الاسترجاع أو التحديث أو الإلغاء أو تعيين الحواجز لاحقًا. لا تستنتج صلاحية الوصول من اسم المفتاح أو الرمز المخفي.

أنشئ مفتاح تطبيق باستخدام POST /api/v1/keys. يُعاد السرّ الكامل في استجابة الإنشاء فحسب، لذا احفظه في مدير الأسرار قبل تجاهل تلك الاستجابة. يجب أن يُنشئ التدوير مفتاحاً بديلاً، وينشره في التطبيق، ويتحقق من حركة المرور، ثم يُلغي المفتاح القديم.

credit_limit_windows يقبل أي مجموعة من حدود الإنفاق المتجددة 1h و1d و7d. إذا استُنفدت أي نافذة مُهيَّأة، تُعيد الاستدعاءات ذات المفتاح المعني 429 Too Many Requests حتى يخرج الاستخدام من تلك النافذة. أرسل كائنًا فارغًا عند تحديث مفتاح لمسح جميع الحدود المتجددة.

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

يقبل الإنشاء والتحديث tags، وهي مصفوفة من سلاسل key:value الكاملة. تعيد استجابات القائمة والاسترجاع والإنشاء والتحديث المصفوفة كاملة. يستبدل PATCH المصفوفة، بينما يحافظ حذف tags من الطلب عليها. يجب أن يتكون المفتاح من 1–32 محرفاً والقيمة من 1–64، مع نقطتين رأسيتين واحدة ومن دون مسافات بيضاء. يُسمح بما يصل إلى 20 وسماً فريداً بما فيها الوسوم المسبقة. يعيد التنسيق غير الصحيح أو تضارب الوسوم المسبقة 422 مع أخطاء التحقق؛ وتعيد القيمة غير المصفوفة أو العنصر غير النصي 400.

يلزم وسم غرض واحد بالضبط: usage:developer أو usage:service. تضيف واجهة Management API عند الإنشاء usage:service إذا لم يُحدد الغرض، بما في ذلك tags: []. يستخدم الإنشاء في لوحة التحكم وتحديث الوسوم دون غرض usage:developer. تُرحّل المفاتيح الحالية بوصفها Developer. البيئة اختيارية وتقبل واحداً على الأكثر من env:production أو env:staging أو env:dev (لا تُقبل env:prod).

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

يضبط مسؤولو مساحة العمل الوسوم المطلوبة للعضو في الفريق، عبر نموذج ميزانية العضو. الوسوم المطلوبة وسوم مخصصة حساسة لحالة الأحرف مثل team:growth. نطاقا الأسماء usage: وenv: محجوزان. يمكن أن يكون للعضو 19 وسماً مطلوباً على الأكثر، ويظل الحد الإجمالي لكل مفتاح 20 وسماً.

يتضمن كل مفتاح قياسي جديد تلقائياً الوسوم المطلوبة لمالكه في مساحة العمل تلك. يجمع الإنشاء الوسوم المُرسلة مع الوسوم المطلوبة قبل التحقق. مثلاً، إذا كان العضو يتطلب team:growth، فإن طلب إنشاء عبر Management API مع tags: ["project:chatbot"] يعيد project:chatbot وteam:growth ووسم usage:service الافتراضي.

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

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

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

Guardrails هي سياسات حساب قابلة لإعادة الاستخدام لضبط النموذج والمزود والإنفاق. أدر السياسات عبر /api/v1/guardrails، ثم استخدم /api/v1/guardrail_assignments لإرفاقها أو إزالتها. عامل التخصيص المرفوض باعتباره إخفاقاً في السياسة أو الملكية بدلاً من الاستمرار بصمت دون guardrail.

أنشئ سياسة حماية بحد موجب في وضع block، ثم عيّن guardrail_id وtag حساسًا لحالة الأحرف مثل dept:ml. اختر هدفًا واحدًا بالضبط، api_token_id أو account_user_id أو tag. تتطلب ميزانيات الوسوم مسؤولًا. الميزانيات المعطلة لا تطبق حدودًا. طلبات الإدارة لا تستهلك الميزانية.

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

تعني القيمة null للحقل credit_limit_reset_interval حدًا مدى الحياة. تستخدم الفترات الأخرى UTC. عتبة التنبيه الافتراضية 80 وتقبل من 1 إلى 100. تؤثر التحديثات المباشرة في جميع التعيينات؛ تنسخ لوحة التحكم السياسة أولًا عند تعديل ميزانية وسم.

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