OpenAI
Tämä sivu on konekäännetty. Katso alkuperäinen englanninkielinen artikkeli.

EKM (External Keys) Management APIssa

Lue, miten hallitset EKM:n ulkoisia avaimia hallinta-API:lla.

Päivitetty: 13 days ago

Yhteenveto

Käyttöoikeudet

  • EKM-endpointit ovat käytettävissä hallinta-API:ssa ylläpitäjän API-avaimella. https://platform.openai.com/settings/organization/admin-keys (älä käytä tavallista API-avainta). Ylläpitäjän API-avaimet ovat organisaation omistajien käytettävissä.

  • Käytä käyttöoikeutta api.external_keys.write ulkoisten avainten luomiseen tai poistamiseen ja käyttöoikeutta api.external_keys.read ulkoisten avainten listaamiseen tai validointiin. Yksittäinen avain tarvitsee molemmat käyttöoikeudet vain, jos sillä on suoritettava sekä luku- että kirjoitustoimintoja.

  • Tällä hetkellä meidän on otettava nämä endpointit käyttöön organisaatiollesi ominaisuuslipulla. Tiedät ominaisuuslipun olevan käytössä, jos nykyinen projektien listausendpoint palauttaa kentän external_key_id: https://api.openai.com/v1/organization/projects.

Käyttö

Rajoitukset

  • Sinun on ensin testattava EKM:ää uudessa projektissa hallinta-API:n kautta.

  • Suosittelemme luomaan uudet projektit EKM-työkuormia varten. Jos kuitenkin haluat EKM:n käyttöön olemassa olevassa projektissa, voimme ottaa tarvittavan ominaisuuslipun käyttöön. Huomioi seuraavat parhaat käytännöt ennen EKM:n käyttöönottoa nykyisissä tuotantoprojekteissasi.

    • Testaa ensin kaikki tuotannossa käyttämäsi API-ominaisuudet EKM:ää käyttävässä API-testiprojektissasi.

    • Ota EKM käyttöön vaiheittain sen sijaan, että ottaisit sen käyttöön kaikissa tuotannon API-projekteissa kerralla.

Organisaatiotason endpointit

Rekisteröi ulkoinen avain organisaatioosi

AWS

Esimerkkipyyntö:

  • type: merkkijono – aina ”aws”

  • name: merkkijono – määrityksen selkokielinen nimi

  • role_arn: merkkijono – sen roolin ARN, jonka OpenAI ottaa käyttöön pilviympäristössäsi

  • kms_arn: merkkijono – hallinnoimasi pääavaimen ARN avaintenhallintajärjestelmässä

  • external_id: merkkijono – organisaation tunnus tai API-projektin tunnus

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

Esimerkkivastaus:

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

Esimerkkipyyntö:

  • type: merkkijono – aina ”gcp”,

  • name: merkkijono – määrityksen selkokielinen nimi

  • workload_identity_project_number: merkkijono – sen GCP-projektin numeerinen projektinumero, johon rekisteröit OpenAI:n työkuormaidentiteetin

  • workload_identity_pool_id: merkkijono – pooli, joka sisältää OpenAI:lle rekisteröimäsi Workload Identity -tarjoajan

  • workload_identity_provider_id: merkkijono – OpenAI:lle rekisteröimäsi Workload Identity -tarjoaja

  • audience: merkkijono – kohdeyleisö, joka OpenAI:n tulee välittää tunnisteessa ottaessaan roolin käyttöön GCP STS -palvelusi kautta

  • kms_project_id: merkkijono – sen GCP-projektin nimi, jossa KMS sijaitsee

  • kms_key_ring_name: merkkijono – avaintenhallintajärjestelmän avainrengas, joka sisältää hallinnoimasi pääavaimen

  • kms_key_name: merkkijono – avaintenhallintajärjestelmän pääavaimen nimi

  • kms_key_location: merkkijono – alue, jolla avaintenhallintajärjestelmän pääavain sijaitsee

Jos KMS sijaitsee eri GCP-projektissa kuin se, johon rekisteröit OpenAI:n Workload Identityn, varmista, että OpenAI:n Workload Identityn sisältävässä projektissa on vähintään KMS käytössä. Voit tarkistaa tämän osoitteessa 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"
}'

Esimerkkivastaus:

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

Esimerkkipyyntö:

  • type: merkkijono – aina ”azure”,

  • name: merkkijono – määrityksen selkokielinen nimi

  • tenant_id: merkkijono – Azure-vuokraajasi UUID

  • vault_uri: merkkijono – sen Azure-avainsäilön URI, joka sisältää hallinnoimasi pääavaimen

  • key_name: merkkijono – hallinnoimasi Azure Key Vault -pääavaimen 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"
}'

Esimerkkivastaus:

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

Poista organisaatiollesi rekisteröity ulkoinen avain

Huomautus: Voit poistaa ulkoisen avaimen vain, jos sitä ei ole liitetty mihinkään aktiiviseen API-projektiin tai työtilaan. Jos avain on liitetty aktiiviseen API-projektiin, arkistoi projekti ensin. Jos avain on liitetty työtilaan, sitä ei voi poistaa.

Esimerkkipyyntö

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

Esimerkkivastaus

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

Hae organisaatiollesi rekisteröidyt ulkoiset avaimet

Esimerkkipyyntö

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

Esimerkkivastaus

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

Validoi ulkoinen avain

Tällä endpointilla voit tarkistaa useita asioita:

  • Ulkoisen pilviympäristösi määritys toimii edelleen OpenAI:n kanssa tekemiesi muutosten jälkeen (saat onnistumisvastauksen).

  • Avaimen peruutus on tehty oikein, OpenAI käsittelee sitä, ja se tulee voimaan välimuistien yhden tunnin TTL-aikojen umpeuduttua (saat virhevastauksen).

Esimerkkipyyntö

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

Esimerkkivastaus

{
  "status": "success"
}

Tai pilvipalveluntarjoajan palauttama virhe.

Projektitason endpointit

Luo uusi projekti ulkoisen avaimen tunnuksella

Tämä vastaa nykyistä projektin luontiendpointia, mutta pyyntöön ja vastaukseen on lisätty external_key_id-parametri.

Esimerkkipyyntö

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

Esimerkkivastaus

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

[Rajoitettu] Päivitä olemassa oleva projekti ulkoisen avaimen tunnuksella

Tämä vastaa nykyistä projektin päivitysendpointia, mutta pyyntöön ja vastaukseen on lisätty external_key_id-parametri.

Suosittelemme luomaan uudet API-projektit EKM-työkuormia varten. Jos haluat EKM:n käyttöön kaikissa olemassa olevissa API-projekteissasi, ota yhteyttä asiakkuusjohtajaasi, niin otamme tarvittavan ominaisuuslipun käyttöön. Huomioi seuraavat parhaat käytännöt ennen EKM:n käyttöönottoa nykyisissä tuotantoprojekteissasi.

  • Testaa ensin kaikki tuotannossa käyttämäsi API-ominaisuudet EKM:ää käyttävässä API-testiprojektissasi.

  • Ota EKM käyttöön vaiheittain sen sijaan, että ottaisit sen käyttöön kaikissa tuotannon API-projekteissa kerralla.

Esimerkkipyyntö

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

Listaa organisaatiosi kaikki projektit

Tämä vastaa nykyistä endpointia, mutta API-vastaukseen on lisätty external_key_id.

Esimerkkipyyntö

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

Esimerkkivastaus

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

Oliko tästä artikkelista apua?