إدارة المفاتيح الخارجية لنظام EKM باستخدام واجهة برمجة تطبيقات الإدارة

الملخص

إمكانية الوصول

يمكن الوصول إلى نقطة النهاية الخاصة بنظام EKM في واجهة برمجة تطبيقات الإدارة عبر مفتاح API للمسؤول. https://platform.openai.com/settings/organization/admin-keys (لا تستخدم مفتاح API عادي). مفاتيح API للمسؤول متاحة لمالكي المنظمات.
استخدم api.external_keys.write لإنشاء المفاتيح الخارجية أو حذفها، وapi.external_keys.read لعرض المفاتيح الخارجية أو التحقق من صحتها. ولا يحتاج المفتاح الواحد إلى كلا النطاقين إلا إذا كان يجب عليه تنفيذ عمليتي القراءة والكتابة.
نحتاج حاليًا إلى تفعيل منظمتك باستخدام علامة ميزة لنقطة النهاية. ستعرف أن لديك علامة الميزة إذا رأيت external_key_id يتم إرجاعه من نقطة النهاية الحالية لقائمة المشاريع: https://api.openai.com/v1/organization/projects

الاستخدام

يتم تسجيل تكوين نظام EKM الخاص بك على مستوى المنظمة عبر نقطة نهاية جديدة https://api.openai.com/v1/organization/external_keys
يؤدي تسجيل إعدادات نظام EKM إلى إرجاع external_key_id بالشكل extkey_xxxx
يتم تفعيل إعدادات نظام EKM على مستوى المشروع من خلال تمرير external_key_id في نص نقطة نهاية "إنشاء مشروع" https://api.openai.com/v1/organization/projects الحالية

القيود

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

نقطة النهاية على مستوى المنظمة

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

AWS

مثال على طلب

type: سلسلة نصية - دائمًا "aws"
name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك
role_arn: سلسلة نصية - معرّف ARN للدور الذي ستتولاه OpenAI في الخدمة السحابية لديك
kms_arn: سلسلة نصية - نظام إدارة المفاتيح ARN للمفتاح الرئيسي الذي تقوم بإدارته
external_id: سلسلة نصية - معرّف منظمتك أو معرّف مشروع واجهة برمجة التطبيقات

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
  "type": "aws",
  "name": "AWS EKM Config",
  "role_arn": "arn:aws:iam::<12_DIGIT_ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <your org id or project id>
}'

مثال على الرد

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746175499,
  "api_project_ids": [],
  "type": "aws",
  "name": "AWS EKM Config",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "external_id": <your org id or project id>
}

GCP

مثال على طلب

type: سلسلة نصية - دائمًا "gcp"،
name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك
workload_identity_project_number: سلسلة نصية - رقم مشروع GCP المكوّن من 12 رقمًا الذي سجّلتَ فيه هوية عبء العمل الخاصة بـ OpenAI
workload_identity_pool_id: سلسلة نصية - المجموعة التي تضم موفّر هوية عبء العمل الذي قمت بتسجيله لـ OpenAI
workload_identity_provider_id: سلسلة نصية - موفّر هوية عبء العمل الذي قمت بتسجيله لـ OpenAI
audience: سلسلة نصية - الجمهور الذي يجب على OpenAI تمريره في الرمز عند تولي دور من خلال GCP STS الخاص بك
kms_project_id: سلسلة نصية - اسم مشروع GCP الذي يوجد فيه نظام KMS الخاص بك
kms_key_ring_name: سلسلة نصية - حلقة مفاتيح نظام إدارة المفاتيح التي تحتوي على المفتاح الرئيسي الذي تقوم بإدارته
kms_key_name: سلسلة نصية - اسم المفتاح الرئيسي لنظام إدارة المفاتيح
kms_key_location: سلسلة نصية - المنطقة التي يوجد فيها المفتاح الرئيسي لنظام إدارة المفاتيح الخاص بك

إذا كان نظام KMS لديك موجود في مشروع GCP مختلف عن المشروع الذي سجّلت فيه هوية عبء العمل الخاصة بـ OpenAI، فتأكد من أن المشروع الذي يحتوي على هوية عبء العمل الخاصة بـ OpenAI مفعّل فيه نظام KMS على الأقل، وذلك بالانتقال إلى https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
   "type": "gcp",
   "name": "GCP EKM Config",
   "workload_identity_project_number": "123456789012",
   "workload_identity_pool_id": "openai-azure",
   "workload_identity_provider_id": "openai-ekm-service-role",
   "audience": <your org id or project id>,
   "kms_project_id": "adjective-noun-12345",
   "kms_key_name": "openai-kms-key",
   "kms_key_ring_name": "openai-kms-key-ring",
   "kms_key_location": "us-east1"
}'

مثال على الرد

{
  "id": "extkey_xxxxxx",
  "object": "organization.external_key",
  "created_at": 1746174349,
  "api_project_ids": [],
  "type": "gcp",
  "name": "GCP EKM Config",
  "workload_identity_project_number": "123456789012",
  "kms_key_ring_name": "openai-kms-key-ring",
  "kms_key_name": "openai-kms-key",
  "kms_key_location": "us-east1",
  "audience": <your org id or project id>,
  "kms_project_id": "adjective-noun-12345",
  "workload_identity_pool_id": "openai-azure",
  "workload_identity_provider_id": "openai-ekm-service-role"
}

Azure

مثال على طلب

type: سلسلة نصية - دائمًا "azure"،
name: سلسلة نصية - اسم سهل الاستخدام للتكوين الخاص بك
tenant_id: سلسلة نصية - معرّف UUID لوحدة Tenant الخاصة بـ Azure.
vault_uri: سلسلة نصية - معرّف URI لمخزن Azure الذي يحتوي على المفتاح الرئيسي الذي تديره
key_name: سلسلة نصية - اسم المفتاح الرئيسي في مخزن مفاتيح Azure الذي تديره
- يجب أن يكون بالتنسيق <org-xxx>--<any_name>
- حيث إن org-xxx هو معرّف منظمة OpenAI الخاص بك، والذي يمكنك العثور عليه على الرابط https://platform.openai.com/settings/organization/general

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys" \
-d '{
  "type": "azure",
  "name": "Azure EKM Config",
  "tenant_id": "<UUID>",
  "vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
  "key_name": "org-xxx--some-key"
}'

مثال على الرد

{
  "id": "extkey_xxxx",
  "object": "organization.external_key",
  "created_at": 1746174377,
  "api_project_ids": [],
  "type": "azure",
  "name": "Azure EKM Config",
  "tenant_id": "<UUID>",
  "vault_uri": "https://<VAULT_NAME>.vault.azure.net/",
  "key_name": "org-xxx--some-key"
}

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

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

مثال على طلب

curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"

مثال على الرد

{
  "id": "extkey_xxxxx",
  "object": "organization.external_key.deleted",
  "created_at": 1746127808,
  "api_project_ids": [],
  "type": "aws",
  "account_number": "123456789012",
  "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  "name": "AWS EKM Config",
  "role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
}

الحصول على المفاتيح الخارجية المسجّلة في منظمتك

مثال على طلب

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"

مثال على الرد

{
  "object": "list",
  "data": [
    {
      "id": "extkey_xxxx",
      "object": "organization.external_key",
      "created_at": 1746127808,
      "api_project_ids": [],
      "type": "aws",
      "name": "AWS EKM Config",
      "account_number": "123456789012",
      "kms_arn": "arn:aws:kms:<REGION>:<ACCOUNT_NUMBER>:key/<UUID>",
  	role_arn": "arn:aws:iam::<ACCOUNT_NUMBER>:role/<ROLE>"
    }
  ],
  "first_id": "extkey_xxxx",
  "has_more": false,
  "last_id": "extkey_xxxx"
}

التحقق من صحة مفتاح خارجي

يمكنك استخدام نقطة النهاية هذه للتحقق من عدة أمور

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

مثال على طلب

curl -X POST -H "Authorization: Bearer $TOKEN"
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"

مثال على الرد

{
 "status": "success"
}

أو ظهر خطأ من مزود الخدمة السحابية.

نقطة النهاية على مستوى المشروع

إنشاء مشروع جديد باستخدام معرّف مفتاح خارجي

هذا مماثل لنقطة نهاية إنشاء مشروع الحالية، مع إضافة المعلمة external_key_id إلى الطلب والرد.

مثال على طلب

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects" \
-d '{
   "name": "Some Project",
   "external_key_id": "extkey_xxxx"
}'

مثال على الرد

{
  "object": "project",
  "id": "proj_xxxxx",
  "title": "Some Project",
  "external_key_id": "extkey_xxxxx",
  "created": 1740012721,
  "organization_id": "org-xxxxx",
  "is_initial": false,
  "geography": null,
  "scale_tier_enabled": false,
  "disable_user_api_keys": false,
  "zdr_type": null,
}

[مقيّد] تحديث مشروع حالي باستخدام معرّف مفتاح خارجي

هذا مماثل لنقطة نهاية تحديث المشروع الحالية، مع إضافة المعلمة external_key_id إلى الطلب والرد.

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

اختبر أولاً جميع ميزات واجهة API التي تستخدمها في بيئة الإنتاج في مشروع EKM API التجريبي
قم بتطبيق طرح تدريجي بدلاً من تعبئة نظام EKM في جميع مشاريع واجهة API في بيئة الإنتاج دفعة واحدة

مثال على طلب

curl -X POST \
-H "Content-type: application/json" \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects/proj_xxx" \
-d '{
   "external_key_id": "extkey_xxxx"
}'

اسرد جميع المشاريع في منظمتك

هذا مماثل لنقطة النهاية الحالية ولكن مع إضافة external_key_id في استجابة API

مثال على طلب

curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"

مثال على الرد

{
  "object": "list",
  "data": [
    {
      "object": "organization.project",
      "id": "proj_xxxx",
      "name": "Project Name",
      "external_key_id": "extkey_xxxx",
      "created_at": 1717798982,
      "archived_at": null,
      "status": "active"
    }
  ],
  "first_id": "proj_xxxx",
  "last_id": "proj_xxxx",
  "has_more": true
}

نظام EKM (المفاتيح الخارجية) في واجهة برمجة تطبيقات الإدارة

الملخص

إمكانية الوصول

الاستخدام

القيود

نقطة النهاية على مستوى المنظمة

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

AWS

مثال على طلب

مثال على الرد

GCP

مثال على طلب

مثال على الرد

Azure

مثال على طلب

مثال على الرد

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

مثال على طلب

مثال على الرد

الحصول على المفاتيح الخارجية المسجّلة في منظمتك

مثال على طلب

مثال على الرد

التحقق من صحة مفتاح خارجي

مثال على طلب

مثال على الرد

نقطة النهاية على مستوى المشروع

إنشاء مشروع جديد باستخدام معرّف مفتاح خارجي

مثال على طلب

مثال على الرد

[مقيّد] تحديث مشروع حالي باستخدام معرّف مفتاح خارجي

مثال على طلب

اسرد جميع المشاريع في منظمتك

مثال على طلب

مثال على الرد

هل كانت هذه المقالة مفيدة؟