OpenAI
Šo lapu tulkoja mašīntulks. Skatīt oriģinālo rakstu angļu valodā.

EKM (ārējās atslēgas) pārvaldības API

Uzziniet, kā pārvaldīt EKM ārējās atslēgas, izmantojot pārvaldības API.

Atjaunināts: 13 days ago

Kopsavilkums

Piekļuve

  • EKM galapunkti ir pieejami pārvaldības API, izmantojot administratora API atslēgu. https://platform.openai.com/settings/organization/admin-keys (neizmantojiet parasto API atslēgu). Administratora API atslēgas ir pieejamas organizācijas īpašniekiem.

  • Izmantojiet api.external_keys.write, lai izveidotu vai dzēstu ārējās atslēgas, un api.external_keys.read, lai iegūtu ārējo atslēgu sarakstu vai pārbaudītu to derīgumu. Vienai atslēgai abas atļauju tvēruma vērtības ir nepieciešamas tikai tad, ja ar to jāveic gan lasīšanas, gan rakstīšanas darbības.

  • Pašlaik mums ir jāiespējo jūsu organizācijai piekļuve šiem galapunktiem, izmantojot funkcijas karodziņu. Funkcijas karodziņš ir iespējots, ja esošā projektu saraksta iegūšanas galapunkta https://api.openai.com/v1/organization/projects atbildē ir redzams external_key_id.

Lietošana

Ierobežojumi

  • Vispirms EKM ir jāizmēģina jaunā projektā, izmantojot pārvaldības API.

  • Iesakām izveidot jaunus projektus darba slodzēm, kurām izmantosiet EKM. Tomēr, ja vēlaties izmantot EKM esošā projektā, varam iespējot jums funkcijas karodziņu. Pirms EKM ieviešanas esošajos produkcijas vides projektos ņemiet vērā tālāk sniegtos labās prakses ieteikumus.

    • Vispirms savā EKM testa API projektā pārbaudiet visas API funkcijas, ko izmantojat produkcijas vidē.

    • Ieviesiet EKM pakāpeniski, nevis iespējojiet to visos produkcijas vides API projektos vienlaikus.

Organizācijas līmeņa endpoints

Reģistrēt ārējo atslēgu jūsu organizācijā

AWS

Pieprasījuma piemērs:

  • type: virkne — vienmēr “aws”

  • name: virkne — viegli atpazīstams konfigurācijas nosaukums

  • role_arn: virkne — tās lomas ARN, kuru OpenAI uzņemsies jūsu mākoņvidē

  • kms_arn: virkne — jūsu pārvaldītās galvenās atslēgas ARN atslēgu pārvaldības sistēmā

  • external_id: virkne — jūsu organizācijas ID vai API projekta 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>"
}'

Atbildes piemērs:

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

Pieprasījuma piemērs:

  • type: virkne — vienmēr “gcp”,

  • name: virkne — viegli atpazīstams konfigurācijas nosaukums

  • workload_identity_project_number: virkne — tā GCP projekta skaitliskais numurs, kurā reģistrējāt OpenAI darba slodzes identitāti

  • workload_identity_pool_id: virkne — pūls, kurā ietilpst OpenAI vajadzībām reģistrētais Workload Identity nodrošinātājs

  • workload_identity_provider_id: virkne — Workload Identity nodrošinātājs, kuru reģistrējāt OpenAI vajadzībām

  • audience: virkne — auditorija, kas OpenAI jānorāda pilnvarā, uzņemoties lomu ar jūsu GCP STS starpniecību

  • kms_project_id: virkne — tā GCP projekta nosaukums, kurā atrodas jūsu KMS

  • kms_key_ring_name: virkne — atslēgu pārvaldības sistēmas atslēgu kopa, kurā ir jūsu pārvaldītā galvenā atslēga

  • kms_key_name: virkne — atslēgu pārvaldības sistēmas galvenās atslēgas nosaukums

  • kms_key_location: virkne — reģions, kurā atrodas jūsu atslēgu pārvaldības sistēmas galvenā atslēga

Ja jūsu KMS atrodas citā GCP projektā, nevis tajā, kurā reģistrējāt OpenAI Workload Identity, atveriet https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview un pārliecinieties, ka projektā ar OpenAI Workload Identity ir vismaz iespējota 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"
}'

Atbildes piemērs:

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

Pieprasījuma piemērs:

  • type: virkne — vienmēr “azure”,

  • name: virkne — viegli atpazīstams konfigurācijas nosaukums

  • tenant_id: virkne — jūsu Azure nomnieka UUID

  • vault_uri: virkne — tās Azure glabātuves URI, kurā ir jūsu pārvaldītā galvenā atslēga

  • key_name: virkne — jūsu pārvaldītās Azure Key Vault galvenās atslēgas nosaukums.

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

Atbildes piemērs:

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

Jūsu organizācijā reģistrētas ārējās atslēgas dzēšana

Piezīme: ārējo atslēgu var dzēst tikai tad, ja tā nav saistīta ne ar vienu aktīvu API projektu vai darbvietu. Ja tā ir saistīta ar aktīvu API projektu, vispirms arhivējiet šo projektu. Ja atslēga ir saistīta ar darbvietu, to nevar dzēst.

Pieprasījuma piemērs

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

Atbildes piemērs

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

Jūsu organizācijā reģistrēto ārējo atslēgu iegūšana

Pieprasījuma piemērs

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

Atbildes piemērs

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

Ārējās atslēgas derīguma pārbaude

Ar šo galapunktu var pārbaudīt vairākas lietas:

  • Vai pēc izmaiņu veikšanas jūsu ārējās mākoņvides konfigurācija joprojām ir derīga lietošanai ar OpenAI (saņemsiet atbildi par sekmīgu pārbaudi).

  • Vai atslēgas atsaukšana ir veikta pareizi, OpenAI to apstrādā un tā stāsies spēkā pēc kešatmiņas 1 stundas derīguma termiņu (TTL) beigām (saņemsiet kļūdas atbildi).

Pieprasījuma piemērs

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

Atbildes piemērs

{
  "status": "success"
}

Vai arī kļūda, ko atgriezis mākoņpakalpojumu sniedzējs.

Projekta līmeņa endpoints

Jauna projekta izveide ar ārējās atslēgas ID

Tas ir tas pats esošais projekta izveides galapunkts, taču pieprasījums un atbilde ir papildināti ar parametru external_key_id.

Pieprasījuma piemērs

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

Atbildes piemērs

{
  "object": "organization.project",
  "id": "proj_xxxxx",
  "name": "Some Project",
  "external_key_id": "extkey_xxxx",
  "created_at": 1740012721,
  "archived_at": null,
  "status": "active"
}

[Ierobežota piekļuve] Esoša projekta atjaunināšana ar ārējās atslēgas ID

Tas ir tas pats esošais projekta atjaunināšanas galapunkts, taču pieprasījums un atbilde ir papildināti ar parametru external_key_id.

Iesakām izveidot jaunus API projektus darba slodzēm, kurām izmantosiet EKM. Ja vēlaties izmantot EKM visos esošajos API projektos, sazinieties ar savu klientu attiecību vadītāju, un mēs iespējosim jums funkcijas karodziņu. Pirms EKM ieviešanas esošajos produkcijas vides projektos ņemiet vērā tālāk sniegtos labās prakses ieteikumus.

  • Vispirms savā EKM testa API projektā pārbaudiet visas API funkcijas, ko izmantojat produkcijas vidē.

  • Ieviesiet EKM pakāpeniski, nevis iespējojiet to visos produkcijas vides API projektos vienlaikus.

Pieprasījuma piemērs

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

Visu organizācijas projektu saraksta iegūšana

Tas ir tas pats esošais galapunkts, taču API atbilde ir papildināta ar external_key_id.

Pieprasījuma piemērs

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

Atbildes piemērs

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

Vai šis raksts bija noderīgs?