OpenAI
See leht on masintõlgitud. Vaadake algset ingliskeelset artiklit.

EKM (välised võtmed) Management API-s

Hallake EKM-i väliseid võtmeid Management API abil

Värskendatud: last month

Kokkuvõte

Juurdepääs

  • EKM-i endpoints on saadaval Management APIs Admin API Key kaudu. https://platform.openai.com/settings/organization/admin-keys (ärge kasutage tavalist API-võtit). Admin API võtmed on saadaval organisatsiooni omanikele.

  • Kasutage api.external_keys.write väliste võtmete loomiseks või kustutamiseks ning api.external_keys.read väliste võtmete loetlemiseks või valideerimiseks. Ühel võtmel on mõlemat ulatust vaja ainult siis, kui see peab tegema nii lugemis- kui ka kirjutamistoiminguid.

  • Praegu peame teie organisatsioonile nende endpoints jaoks funktsioonilipu lubama. Funktsioonilipp on teil olemas, kui näete olemasoleva List Projects endpoint vastuses väärtust external_key_id : https://api.openai.com/v1/organization/projects

Kasutamine

Piirangud

  • Peate esmalt testima EKM-i Management API kaudu uues projektis.

  • Soovitame luua EKM-i töökoormuste jaoks uued projektid. Kui soovite siiski EKM-i olemasolevas projektis, saame lisada teile funktsioonilipu. Enne EKM-i kasutuselevõttu olemasolevates tootmisprojektides pange tähele järgmisi parimaid tavasid.

    • Testige esmalt oma EKM-i API-testprojektis kõiki API-funktsioone, mida tootmises kasutate

    • Võtke EKM kasutusele järk-järgult, mitte korraga kõigis tootmise API-projektides

Organisatsioonitaseme endpoints

Registreerige oma organisatsioonis väline võti

AWS

Päringu näide

  • type: string -  alati „aws“

  • name: string -  teie konfiguratsiooni hõlpsasti loetav nimi

  • role_arn: string - rolli ARN, mille OpenAI teie pilves eeldab

  • kms_arn: string - teie hallatava peavõtme võtmehaldussüsteemi ARN

  • external_id: string - teie organisatsiooni ID või API-projekti 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>
}'

Vastuse näide

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

Päringu näide

  • type: string - alati  "gcp",

  • name: string - teie konfiguratsiooni hõlpsasti loetav nimi

  • workload_identity_project_number: string - 12-kohaline GCP projekti number, kus registreerisite OpenAI töökoormuse identiteedi

  • workload_identity_pool_id: string - kogum, mis sisaldab Workload Identity pakkujat, mille registreerisite OpenAI jaoks

  • workload_identity_provider_id: string - Workload Identity pakkuja, mille registreerisite OpenAI jaoks

  • audience: string - sihtrühm, mille OpenAI peaks tokenis edastama, kui eeldame rolli teie GCP STS-i kaudu

  • kms_project_id: string - GCP projekti nimi, kus teie KMS asub

  • kms_key_ring_name: string - võtmehaldussüsteemi võtmerõngas, mis sisaldab teie hallatavat peavõtit

  • kms_key_name: string - võtmehaldussüsteemi peavõtme nimi

  • kms_key_location: string - piirkond, kus asub teie võtmehaldussüsteemi peavõti

Kui teie KMS asub teises GCP projektis kui see, kus registreerisite OpenAI Workload Identity, veenduge aadressil https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview, et projektis, mis sisaldab OpenAI Workload Identityt, oleks vähemalt KMS lubatud

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

Vastuse näide

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

Päringu näide

  • type: string - alati  "azure",

  • name: string - teie konfiguratsiooni hõlpsasti loetav nimi

  • tenant_id: string - teie Azure’i rentniku UUID

  • vault_uri: string - Azure’i varamu URI, mis sisaldab teie hallatavat peavõtit

  • key_name: string - teie hallatava Azure Key Vaulti peavõtme nimi.

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

Vastuse näide

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

Kustutage oma organisatsioonis registreeritud väline võti

Märkus. Välise võtme saate kustutada ainult siis, kui see pole seotud ühegi aktiivse API-projekti ega tööjaamaga. Kui see on seotud aktiivse API-projektiga, arhiivige esmalt see projekt. Kui see on seotud tööjaamaga, ei saa võtit kustutada.

Päringu näide

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

Vastuse näide

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

Hankige oma organisatsioonis registreeritud välised võtmed

Päringu näide

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

Vastuse näide

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

Valideerige väline võti

Selle endpoint abil saate kontrollida mitut asja

  • Teie väline pilvekonfiguratsioon on pärast muudatusi OpenAI jaoks endiselt kehtiv (näete õnnestumise vastust)

  • Teie võtme tühistamine on tehtud õigesti, OpenAI töötleb seda ja see jõustub pärast 1-tunniste vahemälu TTL-ide aegumist (näete veavastust)

Päringu näide

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

Vastuse näide

{
 "status": "success"
}

Või pilveteenuse pakkujalt saadud viga.

Projektitaseme endpoints

Looge uus projekt välise võtme ID-ga

See on sama mis olemasolev Create Project endpoint, kuid päringusse ja vastusesse on lisatud parameeter external_key_id.

Päringu näide

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

Vastuse näide

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

[Piiratud] Värskendage olemasolevat projekti välise võtme ID-ga

See on sama mis olemasolev Update Project endpoint, kuid päringusse ja vastusesse on lisatud parameeter external_key_id.


Soovitame luua EKM-i töökoormuste jaoks uued API-projektid. Kui soovite EKM-i kõigis olemasolevates API-projektides, küsige oma kontohaldurilt ja lisame teile funktsioonilipu. Enne EKM-i kasutuselevõttu olemasolevates tootmisprojektides pange tähele järgmisi parimaid tavasid.

  • Testige esmalt oma EKM-i API-testprojektis kõiki API-funktsioone, mida tootmises kasutate

  • Võtke EKM kasutusele järk-järgult, mitte korraga kõigis tootmise API-projektides

Päringu näide

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

Loetlege kõik oma organisatsiooni projektid

See on sama mis olemasolev endpoint, kuid API vastusesse on lisatud external_key_id

Päringu näide

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

Vastuse näide

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

Kas sellest artiklist oli abi?