OpenAI
این صفحه به‌صورت ماشینی ترجمه شده است. مقاله اصلی انگلیسی را مشاهده کنید.

EKM (کلیدهای خارجی) در Management API

مدیریت کلیدهای خارجی برای EKM با استفاده از Management API

به‌روزرسانی: 2 days ago

خلاصه

دسترسی

  • endpointهای EKM در Management API از طریق یک کلید Admin API قابل دسترسی هستند. https://platform.openai.com/settings/organization/admin-keys (از کلید API عادی استفاده نکنید). کلیدهای Admin API برای مالکان سازمان در دسترس هستند.

  • برای ایجاد یا حذف کلیدهای خارجی از api.external_keys.write و برای فهرست‌کردن یا اعتبارسنجی کلیدهای خارجی از api.external_keys.read استفاده کنید. یک کلید تنها زمانی به هر دو scope نیاز دارد که لازم باشد هم عملیات خواندن و هم عملیات نوشتن را انجام دهد.

  • در حال حاضر باید سازمان شما را برای این endpointها با feature flag فعال کنیم. اگر external_key_id را در خروجی endpoint موجود List Projects ببینید، یعنی feature flag برای شما فعال است: https://api.openai.com/v1/organization/projects

استفاده

محدودیت‌ها

  • ابتدا باید EKM را روی یک پروژه جدید از طریق Management API آزمایش کنید.

  • توصیه می‌کنیم برای workloadهای EKM خود پروژه‌های جدید ایجاد کنید. بااین‌حال، اگر EKM را روی پروژه‌ای موجود می‌خواهید، می‌توانیم شما را به feature flag اضافه کنیم. لطفاً پیش از rollout کردن EKM به پروژه‌های production موجودتان، بهترین رویه‌های زیر را در نظر داشته باشید.

    • ابتدا همه قابلیت‌های API را که در production استفاده می‌کنید در پروژه API آزمایشی EKM خود تست کنید

    • به‌جای افزودن EKM به همه پروژه‌های API production به‌صورت یکجا، rollout تدریجی انجام دهید

endpointهای سطح سازمان

ثبت یک کلید خارجی در سازمان شما

AWS

نمونه درخواست

  • type: string - همیشه “aws”

  • name: string - نامی خوانا برای پیکربندی شما

  • role_arn: string - Role ARN که OpenAI در ابر شما assume می‌کند

  • kms_arn: string - ARN سامانه مدیریت کلید برای کلید اصلی‌ای که مدیریت می‌کنید

  • external_id: string - شناسه سازمان شما یا شناسه پروژه API

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: string - همیشه "gcp"،

  • name: string - نامی خوانا برای پیکربندی شما

  • workload_identity_project_number: string - شماره ۱۲رقمی پروژه GCP که در آن Workload Identity متعلق به OpenAI را ثبت کرده‌اید

  • workload_identity_pool_id: string - pool حاوی ارائه‌دهنده Workload Identity که برای OpenAI ثبت کرده‌اید

  • workload_identity_provider_id: string - ارائه‌دهنده Workload Identity که برای OpenAI ثبت کرده‌اید

  • audience: string - مخاطبی که OpenAI هنگام assume کردن نقش از طریق GCP STS شما باید در توکن ارسال کند

  • kms_project_id: string - نام پروژه GCP که KMS شما در آن قرار دارد

  • kms_key_ring_name: string - key ring سامانه مدیریت کلید که حاوی کلید اصلی تحت مدیریت شماست

  • kms_key_name: string - نام کلید اصلی سامانه مدیریت کلید

  • kms_key_location: string - منطقه‌ای که کلید اصلی سامانه مدیریت کلید شما در آن قرار دارد

اگر KMS شما در پروژه GCP متفاوتی از پروژه‌ای قرار دارد که Workload Identity متعلق به OpenAI را در آن ثبت کرده‌اید، مطمئن شوید پروژه‌ای که Workload Identity متعلق به 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: string - همیشه "azure"،

  • name: string - نامی خوانا برای پیکربندی شما

  • tenant_id: string - UUID مستأجر Azure شما

  • vault_uri: string - URI خزانه Azure که حاوی کلید اصلی تحت مدیریت شماست

  • key_name: string - نام کلید اصلی Azure Key Vault که مدیریت می‌کنید.

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"
}

اعتبارسنجی یک کلید خارجی

می‌توانید از این endpoint برای بررسی چند مورد استفاده کنید

  • اینکه پیکربندی ابر خارجی شما پس از اعمال تغییرات، همچنان برای OpenAI معتبر است (پاسخ موفقیت‌آمیز خواهید دید)

  • اینکه ابطال کلید شما به‌درستی انجام شده، توسط OpenAI در حال پردازش است و پس از پایان TTLهای کش یک‌ساعته اعمال خواهد شد (پاسخ خطا خواهید دید)

نمونه درخواست

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

نمونه پاسخ

{
 "status": "success"
}

یا خطایی که از ارائه‌دهنده ابر نمایش داده شده است.

endpointهای سطح پروژه

ایجاد یک پروژه جدید با شناسه کلید خارجی

این همان endpoint موجود Create Project است، با این تفاوت که پارامتر 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,
}

[محدود] به‌روزرسانی یک پروژه موجود با شناسه کلید خارجی

این همان endpoint موجود Update Project است، با این تفاوت که پارامتر external_key_id به درخواست و پاسخ اضافه شده است.


توصیه می‌کنیم برای workloadهای EKM خود پروژه‌های API جدید ایجاد کنید. اگر می‌خواهید EKM روی همه پروژه‌های API موجودتان فعال باشد، از مدیر حساب خود بخواهید و ما شما را به feature flag اضافه می‌کنیم. لطفاً پیش از rollout کردن EKM به پروژه‌های production موجودتان، بهترین رویه‌های زیر را در نظر داشته باشید.

  • ابتدا همه قابلیت‌های API را که در production استفاده می‌کنید در پروژه API آزمایشی EKM خود تست کنید

  • به‌جای افزودن EKM به همه پروژه‌های API production به‌صورت یکجا، rollout تدریجی انجام دهید

نمونه درخواست

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"
}'

فهرست‌کردن همه پروژه‌های سازمان شما

این همان endpoint موجود است، با این تفاوت که 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
}

آیا این مقاله مفید بود؟