با نحوهٔ مدیریت کلیدهای خارجی EKM از طریق API مدیریت آشنا شوید.

خلاصه

دسترسی

نقاط پایان EKM در API مدیریت با استفاده از کلید 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 را از طریق API مدیریت در یک پروژهٔ جدید آزمایش کنید.
توصیه می‌کنیم برای بارهای کاری EKM خود پروژه‌های جدید ایجاد کنید. با این حال، اگر می‌خواهید EKM را در پروژه‌ای موجود فعال کنید، می‌توانیم پرچم قابلیت را برای شما فعال کنیم. پیش از فعال‌سازی EKM در پروژه‌های موجودِ محیط عملیاتی، توصیه‌های زیر را در نظر بگیرید.
- ابتدا همهٔ قابلیت‌های API را که در محیط عملیاتی استفاده می‌کنید، در پروژهٔ آزمایشی API با EKM فعال آزمایش کنید.
- به‌جای فعال‌سازی هم‌زمان EKM در همهٔ پروژه‌های API محیط عملیاتی، آن را به‌تدریج فعال کنید.

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

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

AWS

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

type: رشته - همیشه «aws»
name: رشته - نامی خوانا برای پیکربندی شما
role_arn: رشته - ARN نقشی که OpenAI در محیط ابری شما بر عهده می‌گیرد
kms_arn: رشته - ARN سامانهٔ مدیریت کلید برای کلید اصلی‌ای که مدیریت می‌کنید
external_id: رشته - شناسهٔ سازمان یا شناسهٔ پروژهٔ 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: رشته - همیشه «gcp»،
name: رشته - نامی خوانا برای پیکربندی شما
workload_identity_project_number: رشته - شمارهٔ عددی پروژهٔ GCP که هویت بار کاری 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 را در آن ثبت کرده‌اید، با مراجعه به https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview مطمئن شوید که دست‌کم KMS در پروژهٔ حاوی هویت بار کاری OpenAI فعال است.

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 مستأجر Azure شما
vault_uri: رشته - URI خزانهٔ Azure که کلید اصلیِ تحت مدیریت شما در آن قرار دارد
key_name: رشته - نام کلید اصلی Azure Key Vault که مدیریت می‌کنید.
- این نام باید به شکل <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 است و پس از انقضای زمان اعتبار یک‌ساعتهٔ حافظه‌های نهان (TTL) اعمال می‌شود (پاسخ خطا دریافت خواهید کرد).

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

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

نمونهٔ پاسخ

{
  "status": "success"
}

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

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

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

این نقطه پایان همان نقطه پایان فعلیِ ایجاد پروژه است، با این تفاوت که پارامتر 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": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

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

این نقطه پایان همان نقطه پایان فعلیِ به‌روزرسانی پروژه است، با این تفاوت که پارامتر external_key_id به درخواست و پاسخ اضافه شده است.

توصیه می‌کنیم برای بارهای کاری EKM خود پروژه‌های API جدید ایجاد کنید. اگر می‌خواهید EKM را در همهٔ پروژه‌های API موجود خود فعال کنید، از مدیر حساب خود درخواست کنید تا پرچم قابلیت را برای شما فعال کنیم. پیش از فعال‌سازی EKM در پروژه‌های موجودِ محیط عملیاتی، توصیه‌های زیر را در نظر بگیرید.

ابتدا همهٔ قابلیت‌های API را که در محیط عملیاتی استفاده می‌کنید، در پروژهٔ آزمایشی API با EKM فعال آزمایش کنید.
به‌جای فعال‌سازی هم‌زمان 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 (کلیدهای خارجی) در Management API

خلاصه

دسترسی

نحوهٔ استفاده

محدودیت‌ها

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

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

AWS

GCP

Azure

حذف کلید خارجی ثبت‌شده در سازمان شما

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

نمونهٔ پاسخ

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

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

نمونهٔ پاسخ

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

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

نمونهٔ پاسخ

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

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

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

نمونهٔ پاسخ

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

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

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

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

نمونهٔ پاسخ

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