Santrauka
Prieiga
EKM prieigos taškai pasiekiami per valdymo API, naudojant administratoriaus API raktą. https://platform.openai.com/settings/organization/admin-keys (nenaudokite įprasto API rakto). Administratoriaus API raktai prieinami organizacijos savininkams.
Naudokite
api.external_keys.writeišoriniams raktams kurti arba ištrinti, oapi.external_keys.read– jų sąrašui gauti arba galiojimui patikrinti. Vienam raktui abiejų leidimų reikia tik tada, jei juo turi būti atliekamos ir skaitymo, ir rašymo operacijos.Šiuo metu prieigą prie šių prieigos taškų jūsų organizacijai turime įjungti funkcijos vėliavėle. Funkcijos vėliavėlė įjungta, jei esamas projektų sąrašo prieigos taškas https://api.openai.com/v1/organization/projects atsakyme grąžina external_key_id.
Naudojimas
Jūsų EKM konfigūracija registruojama organizacijos lygmeniu per naują prieigos tašką https://api.openai.com/v1/organization/external_keys.
Užregistravus EKM konfigūraciją, grąžinamas external_key_id, kurio formatas yra extkey_xxxx.
EKM konfigūracijos aktyvinamos projekto lygmeniu, perduodant external_key_id užklausos turinyje į esamą projekto kūrimo prieigos tašką https://api.openai.com/v1/organization/projects.
Apribojimai
Pirmiausia turite išbandyti EKM naujame projekte naudodami valdymo API.
Užduotims, kurioms naudojamas EKM, rekomenduojame kurti naujus projektus. Tačiau jei norite naudoti EKM esamame projekte, galime įjungti jums funkcijos vėliavėlę. Prieš diegdami EKM esamuose gamybinės aplinkos projektuose, atsižvelkite į toliau pateiktas gerosios praktikos rekomendacijas.
Pirmiausia bandomajame EKM API projekte išbandykite visas API funkcijas, kurias naudojate gamybinėje aplinkoje.
EKM diekite palaipsniui, o ne visuose gamybinės aplinkos API projektuose iš karto.
Organizacijos lygmens endpoints
Užregistruokite išorinį raktą savo organizacijoje
AWS
Užklausos pavyzdys:
type: eilutė – visada „aws“
name: eilutė – lengvai atpažįstamas konfigūracijos pavadinimas
role_arn: eilutė – vaidmens, kurį OpenAI perims jūsų debesijos aplinkoje, ARN
kms_arn: eilutė – jūsų valdomo pagrindinio rakto ARN raktų valdymo sistemoje
external_id: eilutė – jūsų organizacijos identifikatorius arba API projekto identifikatorius
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>"
}'Atsakymo pavyzdys:
{
"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
Užklausos pavyzdys:
type: eilutė – visada „gcp“,
name: eilutė – lengvai atpažįstamas konfigūracijos pavadinimas
workload_identity_project_number: eilutė – GCP projekto, kuriame užregistravote OpenAI darbo krūvio tapatybę, skaitinis numeris
workload_identity_pool_id: eilutė – telkinys, kuriame yra OpenAI užregistruotas „Workload Identity“ teikėjas
workload_identity_provider_id: eilutė – „Workload Identity“ teikėjas, kurį užregistravote OpenAI
audience: eilutė – auditorija, kurią OpenAI turi perduoti prieigos rakte, kai perimame vaidmenį per jūsų GCP STS
kms_project_id: eilutė – GCP projekto, kuriame veikia jūsų KMS, pavadinimas
kms_key_ring_name: eilutė – raktų valdymo sistemos raktų rinkinys, kuriame yra jūsų valdomas pagrindinis raktas
kms_key_name: eilutė – raktų valdymo sistemos pagrindinio rakto pavadinimas
kms_key_location: eilutė – regionas, kuriame yra jūsų raktų valdymo sistemos pagrindinis raktas
Jei jūsų KMS veikia kitame GCP projekte nei tas, kuriame užregistravote OpenAI „Workload Identity“, atverkite https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview ir įsitikinkite, kad projekte su OpenAI „Workload Identity“ bent jau įjungta 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"
}'Atsakymo pavyzdys:
{
"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
Užklausos pavyzdys:
type: eilutė – visada „azure“,
name: eilutė – lengvai atpažįstamas konfigūracijos pavadinimas
tenant_id: eilutė – jūsų „Azure“ nuomotojo UUID
vault_uri: eilutė – „Azure“ saugyklos, kurioje yra jūsų valdomas pagrindinis raktas, URI
key_name: eilutė – jūsų valdomo „Azure Key Vault“ pagrindinio rakto pavadinimas.
Jo formatas turi būti <org-xxx>--<any_name>
čia org-xxx yra jūsų OpenAI organizacijos identifikatorius, kurį rasite adresu 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"
}'Atsakymo pavyzdys:
{
"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"
}Ištrinti organizacijoje užregistruotą išorinį raktą
Pastaba: išorinį raktą galite ištrinti tik tada, jei jis nesusietas su jokiu aktyviu API projektu ar darbo erdve. Jei jis susietas su aktyviu API projektu, pirmiausia suarchyvuokite tą projektą. Jei raktas susietas su darbo erdve, jo ištrinti negalima.
Užklausos pavyzdys
curl -X DELETE \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxxx"Atsakymo pavyzdys
{
"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>"
}Gauti organizacijoje užregistruotus išorinius raktus
Užklausos pavyzdys
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys"Atsakymo pavyzdys
{
"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"
}Patikrinti išorinio rakto galiojimą
Šiuo prieigos tašku galite patikrinti kelis dalykus:
Ar atlikus pakeitimus jūsų išorinės debesijos konfigūracija tebėra tinkama naudoti su OpenAI (gausite sėkmingą atsakymą).
Ar jūsų raktas atšauktas tinkamai, ar OpenAI apdoroja jo atšaukimą ir ar jis įsigalios pasibaigus 1 valandos podėlio galiojimo laikams (TTL) (gausite klaidos atsakymą).
Užklausos pavyzdys
curl -X POST -H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/external_keys/extkey_xxx/validate"Atsakymo pavyzdys
{
"status": "success"
}Arba iš debesijos paslaugų teikėjo gauta klaida.
Projekto lygmens endpoints
Sukurti naują projektą nurodant išorinio rakto identifikatorių
Tai tas pats esamas projekto kūrimo prieigos taškas, tik užklausa ir atsakymas papildyti parametru external_key_id.
Užklausos pavyzdys
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"
}'Atsakymo pavyzdys
{
"object": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[Ribota prieiga] Atnaujinti esamą projektą nurodant išorinio rakto identifikatorių
Tai tas pats esamas projekto atnaujinimo prieigos taškas, tik užklausa ir atsakymas papildyti parametru external_key_id.
Užduotims, kurioms naudojamas EKM, rekomenduojame kurti naujus API projektus. Jei norite naudoti EKM visuose esamuose API projektuose, kreipkitės į savo klientų aptarnavimo vadovą ir įjungsime jums funkcijos vėliavėlę. Prieš diegdami EKM esamuose gamybinės aplinkos projektuose, atsižvelkite į toliau pateiktas gerosios praktikos rekomendacijas.
Pirmiausia bandomajame EKM API projekte išbandykite visas API funkcijas, kurias naudojate gamybinėje aplinkoje.
EKM diekite palaipsniui, o ne visuose gamybinės aplinkos API projektuose iš karto.
Užklausos pavyzdys
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"
}'Gauti visų organizacijos projektų sąrašą
Tai tas pats esamas prieigos taškas, tik API atsakymas papildytas lauku external_key_id.
Užklausos pavyzdys
curl -X GET \
-H "Authorization: Bearer $TOKEN" \
"https://api.openai.com/v1/organization/projects"Atsakymo pavyzdys
{
"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
}