OpenAI
اس صفحے کا مشینی ترجمہ کیا گیا تھا. اصل انگریزی مضمون دیکھیں.

مینجمنٹ API میں EKM (بیرونی کلیدیں)

مینجمنٹ API کے ذریعے EKM کے لیے بیرونی کلیدوں کا نظم کریں

آخری اپ ڈیٹ: 7 days ago

خلاصہ

رسائی

  • EKM endpoints تک مینجمنٹ API میں ایڈمن API کلید کے ذریعے رسائی حاصل کی جا سکتی ہے. https://platform.openai.com/settings/organization/admin-keys (عام API کلید استعمال نہ کریں). ایڈمن API کلیدیں تنظیم کے مالکان کے لیے دستیاب ہیں.

  • بیرونی کلیدیں بنانے یا حذف کرنے کے لیے api.external_keys.write استعمال کریں، اور بیرونی کلیدیں درج کرنے یا توثیق کرنے کے لیے api.external_keys.read استعمال کریں. کسی ایک کلید کو دونوں scopes صرف اسی صورت میں درکار ہوتے ہیں جب اسے پڑھنے اور لکھنے، دونوں طرح کی کارروائیاں انجام دینی ہوں.

  • فی الحال ہمیں آپ کی تنظیم کے لیے ان endpoints کو فیچر فلیگ کے ذریعے فعال کرنا ہوگا. اگر موجودہ List Projects endpoint سے external_key_id واپس آتا دکھائی دے، تو سمجھ لیں کہ آپ کے پاس فیچر فلیگ ہے: https://api.openai.com/v1/organization/projects

استعمال

  • آپ کی EKM تشکیل تنظیم کی سطح پر ایک نئے endpoint https://api.openai.com/v1/organization/external_keys کے ذریعے رجسٹر کی جاتی ہے.

  • آپ کی EKM تشکیل رجسٹر کرنے پر extkey_xxxx کی شکل میں external_key_id واپس ملتا ہے.

  • EKM تشکیلات کو پروجیکٹ سطح پر موجودہ Create Project https://api.openai.com/v1/organization/projects endpoint کے body میں external_key_id پاس کر کے فعال کیا جاتا ہے.

پابندیاں

  • آپ کو پہلے مینجمنٹ API کے ذریعے نئے پروجیکٹ پر EKM کی جانچ کرنی ہوگی.

  • ہم آپ کے EKM workloads کے لیے نئے پروجیکٹس شروع کرنے کی تجویز دیتے ہیں. تاہم، اگر آپ کسی موجودہ پروجیکٹ پر EKM چاہتے ہیں، تو ہم آپ کو فیچر فلیگ میں شامل کر سکتے ہیں. اپنے موجودہ production پروجیکٹس پر EKM نافذ کرنے سے پہلے درج ذیل بہترین طریقوں کا خیال رکھیں.

    • آپ production میں جو بھی API خصوصیات استعمال کرتے ہیں، پہلے اپنے ٹیسٹ EKM API پروجیکٹ میں ان سب کی جانچ کریں.

    • تمام production API پروجیکٹس پر EKM ایک ساتھ لاگو کرنے کے بجائے تدریجی rollout اپنائیں.

تنظیم سطح کے endpoints

اپنی تنظیم میں بیرونی کلید رجسٹر کریں

AWS

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

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

  • name: string - آپ کی تشکیل کے لیے ایک آسان فہم نام

  • role_arn: string - وہ Role ARN جسے OpenAI آپ کے کلاؤڈ میں assume کرے گا

  • kms_arn: string - آپ کے زیر انتظام ماسٹر کلید کے لیے Key Management System ARN

  • external_id: string - آپ کی تنظیم کی id یا API پروجیکٹ کی 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: string - ہمیشہ "gcp",

  • name: string - آپ کی تشکیل کے لیے ایک آسان فہم نام

  • workload_identity_project_number: string - وہ 12 ہندسوں کا GCP پروجیکٹ نمبر جہاں آپ نے OpenAI کی workload identity رجسٹر کی ہے

  • workload_identity_pool_id: string - وہ pool جس میں Workload Identity provider موجود ہے جسے آپ نے OpenAI کے لیے رجسٹر کیا ہے

  • workload_identity_provider_id: string - وہ Workload Identity provider جسے آپ نے OpenAI کے لیے رجسٹر کیا ہے

  • audience: string - وہ audience جسے آپ کے GCP STS کے ذریعے role assume کرتے وقت OpenAI کو ٹوکن میں پاس کرنا چاہیے

  • kms_project_id: string - اس GCP پروجیکٹ کا نام جہاں آپ کا KMS موجود ہے

  • kms_key_ring_name: string - وہ Key Management System key ring جس میں آپ کے زیر انتظام ماسٹر کلید موجود ہے

  • kms_key_name: string - Key Management System ماسٹر کلید کا نام

  • kms_key_location: string - وہ region جہاں آپ کی Key Management System ماسٹر کلید واقع ہے

اگر آپ کا KMS اس GCP پروجیکٹ سے مختلف پروجیکٹ میں موجود ہے جہاں آپ نے OpenAI کی Workload Identity رجسٹر کی ہے، تو https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview پر جا کر یقینی بنائیں کہ جس پروجیکٹ میں OpenAI کی Workload Identity موجود ہے، اس میں کم از کم KMS فعال ہو.

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 - آپ کا Azure tenant UUID

  • vault_uri: string - اس Azure vault کا URI جس میں آپ کے زیر انتظام ماسٹر کلید موجود ہے

  • 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 اسے پروسیس کر رہا ہے، اور 1 گھنٹے کے cache TTLs ختم ہونے کے بعد یہ مؤثر ہوگی (آپ کو خرابی کا جواب دکھائی دے گا).

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

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

نمونہ جواب

{
 "status": "success"
}

یا، کلاؤڈ فراہم کنندہ کی طرف سے کوئی خامی ظاہر ہوئی.

پروجیکٹ سطح کے endpoints

بیرونی کلید ID کے ساتھ نیا پروجیکٹ بنائیں

یہ موجودہ Create Project endpoint جیسا ہی ہے، لیکن درخواست اور جواب میں external_key_id parameter شامل ہے.

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

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

[محدود] موجودہ پروجیکٹ کو بیرونی کلید ID کے ساتھ اپ ڈیٹ کریں

یہ موجودہ Update Project endpoint جیسا ہی ہے، لیکن درخواست اور جواب میں external_key_id parameter شامل ہے.


ہم آپ کے EKM workloads کے لیے نئے API پروجیکٹس شروع کرنے کی تجویز دیتے ہیں. اگر آپ اپنے تمام موجودہ API پروجیکٹس پر EKM چاہتے ہیں، تو اپنے account director سے کہیں، اور ہم آپ کو فیچر فلیگ میں شامل کر دیں گے. اپنے موجودہ production پروجیکٹس پر EKM نافذ کرنے سے پہلے درج ذیل بہترین طریقوں کا خیال رکھیں.

  • آپ production میں جو بھی API خصوصیات استعمال کرتے ہیں، پہلے اپنے ٹیسٹ EKM API پروجیکٹ میں ان سب کی جانچ کریں.

  • تمام production API پروجیکٹس پر EKM ایک ساتھ لاگو کرنے کے بجائے تدریجی 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 جیسا ہی ہے، لیکن API جواب میں external_key_id کا اضافہ کیا گیا ہے.

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

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
}

کیا یہ آرٹیکل مددگار تھا؟