OpenAI
Ez az oldal gépi fordítással készült. Tekintsd meg az eredeti angol nyelvű cikket.

EKM (External Keys) a Management API-ban

Külső kulcsok kezelése EKM-hez a Management API használatával

Frissítve: 6 hours ago

Összefoglaló

Hozzáférés

  • Az EKM endpoints a Management API-ban érhetők el Admin API Key használatával. https://platform.openai.com/settings/organization/admin-keys (ne használjon normál API-kulcsot). Az Admin API-kulcsok szervezettulajdonosok számára érhetők el.

  • Külső kulcsok létrehozásához vagy törléséhez használja a api.external_keys.write jogosultságkört, külső kulcsok listázásához vagy érvényesítéséhez pedig a api.external_keys.read jogosultságkört. Egy kulcsnak csak akkor van szüksége mindkét hatókörre, ha olvasási és írási műveleteket is kell végeznie.

  • Jelenleg funkciójelzővel kell engedélyeznünk a szervezetét ezekhez az endpoints-hez. Akkor tudhatja, hogy rendelkezik a funkciójelzővel, ha a meglévő List Projects endpoint válaszában látja visszaadva az external_key_id értéket: https://api.openai.com/v1/organization/projects

Használat

Korlátozások

  • Először egy új projekten kell tesztelnie az EKM-et a Management API-n keresztül.

  • Javasoljuk, hogy az EKM-munkaterhelésekhez hozzon létre új projekteket. Ha azonban meglévő projekten szeretne EKM-et használni, hozzáadhatjuk a funkciójelzőhöz. Kérjük, vegye figyelembe az alábbi bevált gyakorlatokat, mielőtt bevezeti az EKM-et a meglévő éles projektjeiben.

    • Először tesztelje az éles környezetben használt összes API-funkciót a teszt EKM API-projektjében

    • Fokozatos bevezetést alkalmazzon ahelyett, hogy egyszerre engedélyezné az EKM-et az összes éles API-projekten

Szervezetszintű endpoints

Külső kulcs regisztrálása a szervezetében

AWS

Mintakérés

  • type: string - mindig „aws”

  • name: string - a konfiguráció könnyen felismerhető neve

  • role_arn: string - az a Role ARN, amelyet az OpenAI felvesz az Ön felhőkörnyezetében

  • kms_arn: string - az Ön által kezelt főkulcs Key Management System ARN-je

  • external_id: string - az Ön szervezetazonosítója vagy API-projektazonosítója

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

Mintaválasz

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

Mintakérés

  • type: string - mindig "gcp",

  • name: string - a konfiguráció könnyen felismerhető neve

  • workload_identity_project_number: string - az a 12 jegyű GCP-projektszám, amelyben regisztrálta az OpenAI Workload Identity-jét

  • workload_identity_pool_id: string - az OpenAI számára regisztrált Workload Identity provider szolgáltatót tartalmazó pool

  • workload_identity_provider_id: string - az OpenAI számára regisztrált Workload Identity provider

  • audience: string - az a célközönség, amelyet az OpenAI-nak át kell adnia a tokenben, amikor szerepet veszünk fel az Ön GCP STS-én keresztül

  • kms_project_id: string - annak a GCP-projektnek a neve, ahol a KMS található

  • kms_key_ring_name: string - az Ön által kezelt főkulcsot tartalmazó Key Management System-kulcskarika

  • kms_key_name: string - a Key Management System-főkulcs neve

  • kms_key_location: string - az a régió, ahol a Key Management System-főkulcsa található

Ha a KMS-e más GCP-projektben található, mint ahol az OpenAI Workload Identity-jét regisztrálta, győződjön meg arról, hogy az OpenAI Workload Identity-jét tartalmazó projekten legalább engedélyezve van a KMS; ehhez nyissa meg: 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"
}'

Mintaválasz

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

Mintakérés

  • type: string - mindig "azure",

  • name: string - a konfiguráció könnyen felismerhető neve

  • tenant_id: string - az Ön Azure tenant UUID-je

  • vault_uri: string - az Ön által kezelt főkulcsot tartalmazó Azure-vault URI-ja

  • key_name: string - az Ön által kezelt Azure Key Vault-főkulcs neve.

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

Mintaválasz

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

A szervezetében regisztrált külső kulcs törlése

Megjegyzés: Külső kulcsot csak akkor törölhet, ha nincs társítva aktív API-projekthez vagy munkaterülethez. Ha aktív API-projekthez van társítva, először archiválja azt a projektet. Ha munkaterülethez van társítva, a kulcs nem törölhető.

Mintakérés

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

Mintaválasz

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

A szervezetében regisztrált külső kulcsok lekérése

Mintakérés

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

Mintaválasz

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

Külső kulcs érvényesítése

Ezzel az endpointtal több dolgot is ellenőrizhet

  • Az OpenAI-nál továbbra is érvényes-e a külső felhőkonfigurációja a módosítások után (sikeres választ fog látni)

  • A kulcs visszavonása megfelelően megtörtént-e, az OpenAI feldolgozza-e, és életbe lép-e az 1 órás gyorsítótári TTL-ek lejárta után (hibaválaszt fog látni)

Mintakérés

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

Mintaválasz

{
 "status": "success"
}

Vagy a felhőszolgáltató által jelzett hiba.

Projektszintű endpoints

Új projekt létrehozása külsőkulcs-azonosítóval

Ez megegyezik a meglévő Create Project endpointtal, azzal a kiegészítéssel, hogy a kérésben és a válaszban szerepel az external_key_id paraméter.

Mintakérés

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

Mintaválasz

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

[Korlátozott] Meglévő projekt frissítése külsőkulcs-azonosítóval

Ez megegyezik a meglévő Update Project endpointtal, azzal a kiegészítéssel, hogy a kérésben és a válaszban szerepel az external_key_id paraméter.


Javasoljuk, hogy az EKM-munkaterhelésekhez hozzon létre új API-projekteket. Ha EKM-et szeretne az összes meglévő API-projektjén, kérje az ügyfélkapcsolati vezetőjét, és hozzáadjuk a funkciójelzőhöz. Kérjük, vegye figyelembe az alábbi bevált gyakorlatokat, mielőtt bevezeti az EKM-et a meglévő éles projektjeiben.

  • Először tesztelje az éles környezetben használt összes API-funkciót a teszt EKM API-projektjében

  • Fokozatos bevezetést alkalmazzon ahelyett, hogy egyszerre engedélyezné az EKM-et az összes éles API-projekten

Mintakérés

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

A szervezetéhez tartozó összes projekt listázása

Ez megegyezik a meglévő endpointtal, de az API-válaszban szerepel még az external_key_id is

Mintakérés

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

Mintaválasz

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

Hasznos volt ez a cikk?