OpenAI
Kjo faqe u përkthye automatikisht. Shih artikullin origjinal në anglisht.

EKM (Çelësat e jashtëm) në Management API

Menaxhoni çelësat e jashtëm për EKM duke përdorur Management API

Përditësuar: 5 days ago

Përmbledhje

Qasja

  • endpoints e EKM-së janë të qasshme në Management API përmes një Admin API Key. https://platform.openai.com/settings/organization/admin-keys (mos përdorni një çelës API normal). Çelësat Admin API janë të disponueshëm për pronarët e organizatës.

  • Përdorni api.external_keys.write për të krijuar ose fshirë çelësa të jashtëm dhe api.external_keys.read për të listuar ose validuar çelësa të jashtëm. Një çelësi të vetëm i duhen të dyja fushëveprimet vetëm nëse duhet të kryejë operacione leximi dhe shkrimi.

  • Aktualisht duhet ta përfshijmë organizatën tuaj në këto endpoints përmes një feature flag. E dini se e keni feature flag-un nëse shihni external_key_id të kthyer nga endpoint ekzistues List Projects: https://api.openai.com/v1/organization/projects

Përdorimi

Kufizime

  • Fillimisht duhet ta testoni EKM-në në një projekt të ri përmes Management API.

  • Rekomandojmë të krijoni projekte të reja për ngarkesat tuaja EKM. Megjithatë, nëse dëshironi EKM në një projekt ekzistues, mund t'ju shtojmë në feature flag. Ju lutemi vini re praktikat më të mira të mëposhtme përpara se ta vendosni EKM-në në përdorim në projektet tuaja ekzistuese të prodhimit.

    • Testoni fillimisht të gjitha veçoritë e API-së që përdorni në prodhim në projektin tuaj testues EKM API

    • Zbatoni një hedhje graduale në përdorim, në vend që ta aktivizoni EKM-në në të gjitha projektet API të prodhimit njëherësh

endpoints të nivelit të organizatës

Regjistroni një çelës të jashtëm në organizatën tuaj

AWS

Kërkesë shembull

  • type: string - gjithmonë "aws"

  • name: string - Një emër i lehtë për konfigurimin tuaj

  • role_arn: string - Role ARN që OpenAI do të marrë në cloud-in tuaj

  • kms_arn: string - ARN i Key Management System për çelësin master që menaxhoni

  • external_id: string - ID-ja e organizatës suaj ose ID-ja e projektit API

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

Përgjigje shembull

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

Kërkesë shembull

  • type: string - gjithmonë "gcp",

  • name: string - Një emër i lehtë për konfigurimin tuaj

  • workload_identity_project_number: string - Numri 12-shifror i projektit GCP ku keni regjistruar Workload Identity të OpenAI

  • workload_identity_pool_id: string - Pool-i që përmban ofruesin e Workload Identity që keni regjistruar për OpenAI

  • workload_identity_provider_id: string - Ofruesi i Workload Identity që keni regjistruar për OpenAI

  • audience: string - Audienca që OpenAI duhet të kalojë në token kur marrim një rol përmes GCP STS tuaj

  • kms_project_id: string - Emri i projektit GCP ku ndodhet KMS-ja juaj

  • kms_key_ring_name: string - Unaza e çelësave e Key Management System që përmban çelësin master që menaxhoni

  • kms_key_name: string - Emri i çelësit master të Key Management System

  • kms_key_location: string - Rajoni ku ndodhet çelësi juaj master i Key Management System

Nëse KMS-ja juaj ndodhet në një projekt GCP të ndryshëm nga ai ku keni regjistruar Workload Identity të OpenAI, sigurohuni që projekti që përmban Workload Identity të OpenAI të paktën ta ketë KMS të aktivizuar duke shkuar te 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"
}'

Përgjigje shembull

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

Kërkesë shembull

  • type: string - gjithmonë "azure",

  • name: string - Një emër i lehtë për konfigurimin tuaj

  • tenant_id: string - UUID-ja e tenant-it tuaj Azure

  • vault_uri: string - URI-ja e vault-it Azure që përmban çelësin master që menaxhoni

  • key_name: string - Emri i çelësit master të Azure Key Vault që menaxhoni.

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

Përgjigje shembull

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

Fshini një çelës të jashtëm të regjistruar në organizatën tuaj

Shënim: Një çelës të jashtëm mund ta fshini vetëm nëse nuk është i lidhur me ndonjë projekt API aktiv ose hapësirë pune. Nëse është i lidhur me një projekt API aktiv, arkivojeni fillimisht atë projekt. Nëse është i lidhur me një hapësirë pune, çelësi nuk mund të fshihet.

Kërkesë shembull

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

Përgjigje shembull

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

Merrni çelësat e jashtëm të regjistruar në organizatën tuaj

Kërkesë shembull

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

Përgjigje shembull

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

Validoni një çelës të jashtëm

Mund ta përdorni këtë endpoint për të kontrolluar disa gjëra

  • Konfigurimi juaj i jashtëm në cloud mbetet i vlefshëm me OpenAI pasi të keni bërë ndryshime (do të shihni një përgjigje suksesi)

  • Revokimi i çelësit tuaj është bërë saktë, po përpunohet nga OpenAI dhe do të hyjë në fuqi pasi të skadojnë TTL-të e cache-it prej 1 ore (do të shihni një përgjigje gabimi)

Kërkesë shembull

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

Përgjigje shembull

{
 "status": "success"
}

Ose është shfaqur një gabim nga ofruesi i cloud-it.

endpoints të nivelit të projektit

Krijoni një projekt të ri me një ID çelësi të jashtëm

Ky është i njëjtë me endpoint ekzistues Create Project, me shtimin e parametrit external_key_id në kërkesë dhe përgjigje.

Kërkesë shembull

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

Përgjigje shembull

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

[I kufizuar] Përditësoni një projekt ekzistues me një ID çelësi të jashtëm

Ky është i njëjtë me endpoint ekzistues Update Project, me shtimin e parametrit external_key_id në kërkesë dhe përgjigje.


Rekomandojmë të krijoni projekte të reja API për ngarkesat tuaja EKM. Nëse dëshironi EKM në të gjitha projektet tuaja ekzistuese API, kërkojini drejtorit të llogarisë suaj dhe ne do t'ju shtojmë në feature flag. Ju lutemi vini re praktikat më të mira të mëposhtme përpara se ta vendosni EKM-në në përdorim në projektet tuaja ekzistuese të prodhimit.

  • Testoni fillimisht të gjitha veçoritë e API-së që përdorni në prodhim në projektin tuaj testues EKM API

  • Zbatoni një hedhje graduale në përdorim, në vend që ta aktivizoni EKM-në në të gjitha projektet API të prodhimit njëherësh

Kërkesë shembull

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

Listoni të gjitha projektet në organizatën tuaj

Ky është i njëjtë me endpoint ekzistues, por me shtimin e external_key_id në përgjigjen e API-së

Kërkesë shembull

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

Përgjigje shembull

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

A ishte i dobishëm ky artikull?