OpenAI
Halaman ini diterjemah oleh mesin. Lihat artikel asal dalam bahasa Inggeris.

EKM (Kunci Luaran) dalam API Pengurusan

Urus kunci luaran untuk EKM menggunakan API Pengurusan

Dikemas kini: 7 days ago

Ringkasan

Akses

  • Titik akhir EKM boleh diakses dalam API Pengurusan melalui Kunci API Pentadbir. https://platform.openai.com/settings/organization/admin-keys (jangan gunakan kunci API biasa). Kunci API Pentadbir tersedia kepada pemilik organisasi.

  • Gunakan api.external_keys.write untuk mencipta atau memadam kunci luaran, dan api.external_keys.read untuk menyenaraikan atau mengesahkan kunci luaran. Satu kunci hanya memerlukan kedua-dua skop jika kunci itu perlu menjalankan operasi baca dan tulis.

  • Pada masa ini, kami perlu mendayakan bendera ciri untuk organisasi anda bagi titik akhir ini. Anda tahu bendera ciri sudah didayakan jika anda melihat external_key_id dikembalikan daripada titik akhir Senarai Projek sedia ada: https://api.openai.com/v1/organization/projects

Penggunaan

Sekatan

  • Anda mesti menguji EKM terlebih dahulu pada projek baharu melalui API Pengurusan.

  • Kami mengesyorkan anda menyediakan projek baharu untuk beban kerja EKM anda. Walau bagaimanapun, jika anda mahukan EKM pada projek sedia ada, kami boleh menambahkan anda pada bendera ciri. Sila ambil perhatian tentang amalan terbaik berikut sebelum anda melancarkan EKM kepada projek pengeluaran sedia ada anda.

    • Uji dahulu semua ciri API yang anda gunakan dalam pengeluaran dalam projek API EKM ujian anda

    • Gunakan pelancaran berperingkat dan bukannya mengisi EKM pada semua projek API pengeluaran sekali gus

Titik akhir peringkat organisasi

Daftarkan kunci luaran pada organisasi anda

AWS

Contoh Permintaan

  • type: string -  sentiasa “aws”

  • name: string -  Nama mesra untuk konfigurasi anda

  • role_arn: string - ARN Peranan yang akan diandaikan oleh OpenAI dalam awan anda

  • kms_arn: string - ARN Sistem Pengurusan Kunci untuk kunci induk yang anda urus

  • external_id: string - ID organisasi anda atau ID projek 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>
}'

Contoh Respons

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

Contoh Permintaan

  • type: string - sentiasa  "gcp",

  • name: string - Nama mesra untuk konfigurasi anda

  • workload_identity_project_number: string - Nombor projek GCP 12 digit tempat anda mendaftarkan identiti beban kerja OpenAI

  • workload_identity_pool_id: string - Kumpulan yang mengandungi penyedia Workload Identity yang anda daftarkan untuk OpenAI

  • workload_identity_provider_id: string - Penyedia Workload Identity yang anda daftarkan untuk OpenAI

  • audience: string - Khalayak yang perlu dihantar oleh OpenAI dalam token apabila kami mengambil alih peranan melalui GCP STS anda

  • kms_project_id: string - Nama projek GCP tempat KMS anda berada

  • kms_key_ring_name: string - Gelang kunci Sistem Pengurusan Kunci yang mengandungi kunci induk yang anda urus

  • kms_key_name: string - Nama kunci induk Sistem Pengurusan Kunci

  • kms_key_location: string - Wilayah tempat kunci induk Sistem Pengurusan Kunci anda berada

Jika KMS anda berada dalam projek GCP yang berbeza daripada projek tempat anda mendaftarkan Workload Identity OpenAI, pastikan projek yang mengandungi Workload Identity OpenAI sekurang-kurangnya telah mendayakan KMS dengan pergi ke 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"
}'

Contoh Respons

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

Contoh Permintaan

  • type: string - sentiasa  "azure",

  • name: string - Nama mesra untuk konfigurasi anda

  • tenant_id: string - UUID penyewa Azure anda

  • vault_uri: string - URI peti besi Azure yang mengandungi kunci induk yang anda urus

  • key_name: string - Nama kunci induk Azure Key Vault yang anda urus.

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

Contoh Respons

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

Padam kunci luaran yang didaftarkan pada organisasi anda

Nota: Anda hanya boleh memadam kunci luaran jika kunci itu tidak dikaitkan dengan mana-mana projek API atau ruang kerja yang aktif. Jika kunci itu dikaitkan dengan projek API yang aktif, arkibkan projek tersebut terlebih dahulu. Jika kunci itu dikaitkan dengan ruang kerja, kunci tersebut tidak boleh dipadam.

Contoh Permintaan

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

Contoh Respons

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

Dapatkan kunci luaran yang didaftarkan pada organisasi anda

Contoh Permintaan

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

Contoh Respons

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

Sahkan kunci luaran

Anda boleh menggunakan titik akhir ini untuk menyemak beberapa perkara

  • Konfigurasi awan luaran anda kekal sah dengan OpenAI selepas anda membuat perubahan (anda akan melihat respons berjaya)

  • Pembatalan kunci anda dilakukan dengan betul, sedang diproses oleh OpenAI, dan akan berkuat kuasa selepas TTL cache 1 jam tamat (anda akan melihat respons ralat)

Contoh Permintaan

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

Contoh Respons

{
 "status": "success"
}

Atau, ralat yang dikemukakan daripada penyedia awan.

Titik akhir peringkat projek

Cipta projek baharu dengan ID kunci luaran

Ini sama seperti titik akhir Cipta Projek sedia ada, dengan penambahan parameter external_key_id dalam permintaan dan respons.

Contoh Permintaan

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

Contoh Respons

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

[Terhad] Kemas kini projek sedia ada dengan ID kunci luaran

Ini sama seperti titik akhir Kemas Kini Projek sedia ada, dengan penambahan parameter external_key_id dalam permintaan dan respons.


Kami mengesyorkan anda menyediakan projek API baharu untuk beban kerja EKM anda. Jika anda mahukan EKM pada semua projek API sedia ada anda, minta pengarah akaun anda dan kami akan menambahkan anda pada bendera ciri. Sila ambil perhatian tentang amalan terbaik berikut sebelum anda melancarkan EKM kepada projek pengeluaran sedia ada anda.

  • Uji dahulu semua ciri API yang anda gunakan dalam pengeluaran dalam projek API EKM ujian anda

  • Gunakan pelancaran berperingkat dan bukannya mengisi EKM pada semua projek API pengeluaran sekali gus

Contoh Permintaan

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

Senaraikan semua projek pada organisasi anda

Ini sama seperti titik akhir sedia ada, tetapi dengan penambahan external_key_id dalam respons API

Contoh Permintaan

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

Contoh Respons

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

Adakah artikel ini membantu?