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

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

Vaadake, kuidas hallata EKM-i väliseid võtmeid haldus-API kaudu.

Värskendatud: 7 days ago

Kokkuvõte

Juurdepääs

  • EKM-i lõpp-punktidele pääseb ligi haldus-API kaudu, kasutades administraatori API-võtit. https://platform.openai.com/settings/organization/admin-keys (ärge kasutage tavalist API-võtit). Administraatori API-võtmed on saadaval organisatsiooni omanikele.

  • Väliste võtmete loomiseks või kustutamiseks kasutage õigust api.external_keys.write ning nende loetlemiseks või valideerimiseks õigust api.external_keys.read. Üks võti vajab mõlemat õigust ainult siis, kui sellega tuleb teha nii lugemis- kui ka kirjutamistoiminguid.

  • Praegu peame teie organisatsioonile nende lõpp-punktide kasutamise funktsioonilipuga lubama. Funktsioonilipp on lubatud, kui olemasolev projektide loetlemise lõpp-punkt https://api.openai.com/v1/organization/projects tagastab välja external_key_id.

Kasutamine

Piirangud

  • Kõigepealt peate EKM-i haldus-API kaudu uues projektis katsetama.

  • Soovitame EKM-i kasutavate töökoormuste jaoks luua uued projektid. Kui soovite siiski EKM-i olemasolevale projektile, saame teile vastava funktsioonilipu lubada. Enne EKM-i kasutuselevõttu olemasolevates tootmiskeskkonna projektides arvestage järgmiste soovitustega.

    • Katsetage esmalt kõiki tootmiskeskkonnas kasutatavaid API funktsioone oma EKM-i testimiseks loodud API-projektis.

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

Organisatsioonitaseme endpoints

Registreerige oma organisatsioonis väline võti

AWS

Näidispäring:

  • type: sõne – alati „aws“

  • name: sõne – konfiguratsiooni hõlpsasti äratuntav nimi

  • role_arn: sõne – selle rolli ARN, mille OpenAI teie pilves võtab

  • kms_arn: sõne – teie hallatava põhivõtme ARN võtmehaldussüsteemis

  • external_id: sõne – 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>"
}'

Näidisvastus:

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

Näidispäring:

  • type: sõne – alati „gcp“,

  • name: sõne – konfiguratsiooni hõlpsasti äratuntav nimi

  • workload_identity_project_number: sõne – selle GCP projekti number, milles registreerisite OpenAI töökoormuse identiteedi

  • workload_identity_pool_id: sõne – kogum, mis sisaldab OpenAI jaoks registreeritud Workload Identity pakkujat

  • workload_identity_provider_id: sõne – OpenAI jaoks registreeritud Workload Identity pakkuja

  • audience: sõne – sihtrühm, mille OpenAI peab tõendis edastama, kui võtame teie GCP STS-i kaudu rolli

  • kms_project_id: sõne – selle GCP projekti nimi, kus asub teie KMS

  • kms_key_ring_name: sõne – võtmehaldussüsteemi võtmekimp, mis sisaldab teie hallatavat põhivõtit

  • kms_key_name: sõne – võtmehaldussüsteemi põhivõtme nimi

  • kms_key_location: sõne – piirkond, kus asub teie võtmehaldussüsteemi põhivõti

Kui teie KMS asub teises GCP projektis kui see, milles registreerisite OpenAI Workload Identity, veenduge, et OpenAI Workload Identityt sisaldavas projektis oleks vähemalt KMS lubatud. Selleks avage 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"
}'

Näidisvastus:

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

Näidispäring:

  • type: sõne – alati „azure“,

  • name: sõne – konfiguratsiooni hõlpsasti äratuntav nimi

  • tenant_id: sõne – teie Azure’i rentniku UUID

  • vault_uri: sõne – teie hallatavat põhivõtit sisaldava Azure’i hoidla URI

  • key_name: sõne – teie hallatava Azure Key Vaulti põhivõ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"
}'

Näidisvastus:

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

Organisatsioonis registreeritud välise võtme kustutamine

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

Näidispäring

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

Näidisvastus

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

Organisatsioonis registreeritud väliste võtmete pärimine

Näidispäring

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

Näidisvastus

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

Välise võtme valideerimine

Selle lõpp-punkti abil saate kontrollida järgmist:

  • Teie välise pilve konfiguratsioon kehtib OpenAI jaoks ka pärast muudatuste tegemist (saate õnnestumist kinnitava vastuse).

  • Teie võtme tühistamine on tehtud õigesti, OpenAI töötleb seda ja see jõustub pärast vahemälu ühetunniste kehtivusaegade (TTL) möödumist (saate veavastuse).

Näidispäring

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

Näidisvastus

{
  "status": "success"
}

Või pilveteenuse pakkujalt saadud viga.

Projektitaseme endpoints

Uue projekti loomine välise võtme ID-ga

See on sama mis olemasolev projekti loomise lõpp-punkt, kuid päringusse ja vastusesse on lisatud parameeter external_key_id.

Näidispäring

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

Näidisvastus

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

[Piiratud juurdepääs] Olemasoleva projekti uuendamine välise võtme ID-ga

See on sama mis olemasolev projekti uuendamise lõpp-punkt, kuid päringusse ja vastusesse on lisatud parameeter external_key_id.

Soovitame EKM-i kasutavate töökoormuste jaoks luua uued API-projektid. Kui soovite EKM-i kõigile oma olemasolevatele API-projektidele, võtke ühendust oma kliendihalduriga ja lubame teile vastava funktsioonilipu. Enne EKM-i kasutuselevõttu olemasolevates tootmiskeskkonna projektides arvestage järgmiste soovitustega.

  • Katsetage esmalt kõiki tootmiskeskkonnas kasutatavaid API funktsioone oma EKM-i testimiseks loodud API-projektis.

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

Näidispäring

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

Organisatsiooni kõigi projektide loetlemine

See on sama mis olemasolev lõpp-punkt, kuid API vastusesse on lisatud external_key_id.

Näidispäring

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

Näidisvastus

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