Կառավարեք EKM-ի արտաքին բանալիները Management API-ով

Ամփոփում

Մուտք

EKM endpoints-ը հասանելի են Management API-ում՝ Admin API Key-ի միջոցով։ https://platform.openai.com/settings/organization/admin-keys (մի օգտագործեք սովորական API բանալի)։ Admin API բանալիները հասանելի են կազմակերպության սեփականատերերին։
Արտաքին բանալիներ ստեղծելու կամ ջնջելու համար օգտագործեք api.external_keys.write, իսկ արտաքին բանալիները ցուցակելու կամ վավերացնելու համար՝ api.external_keys.read։ Մեկ բանալուն երկու scope-ն էլ պետք է միայն այն դեպքում, երբ այն պետք է կատարի և՛ կարդալու, և՛ գրելու գործողություններ։
Այս endpoints-ին մուտք տալու համար ներկայում պետք է ձեր կազմակերպության համար միացնենք feature flag-ը։ Feature flag-ը միացված է, եթե գործող List Projects endpoint-ից վերադարձվող պատասխանում տեսնում եք external_key_id -ը՝ https://api.openai.com/v1/organization/projects

Օգտագործում

Ձեր EKM կազմաձևը գրանցվում է կազմակերպության մակարդակում՝ նոր endpoint-ի միջոցով՝ https://api.openai.com/v1/organization/external_keys
Ձեր EKM կազմաձևը գրանցելիս վերադարձվում է external_key_id՝ extkey_xxxx ձևաչափով
EKM կազմաձևերը ակտիվացվում են նախագծի մակարդակում՝ գործող Create Project https://api.openai.com/v1/organization/projects endpoint-ի մարմնում փոխանցելով external_key_id

Սահմանափակումներ

Նախ պետք է փորձարկեք EKM-ը նոր նախագծում՝ Management API-ի միջոցով։
Խորհուրդ ենք տալիս ձեր EKM ծանրաբեռնվածությունների համար ստեղծել նոր նախագծեր։ Այնուամենայնիվ, եթե ցանկանում եք EKM միացնել գոյություն ունեցող նախագծում, կարող ենք ձեզ ավելացնել feature flag-ին։ Նախքան EKM-ը ձեր գոյություն ունեցող արտադրական նախագծերում ներդնելը, նկատի ունեցեք հետևյալ լավագույն գործելակերպերը։
- Նախ փորձարկեք արտադրությունում օգտագործվող բոլոր API գործառույթները ձեր փորձնական EKM API նախագծում
- Կիրառեք աստիճանական ներդրում՝ EKM-ը միանգամից բոլոր արտադրական API նախագծերում միացնելու փոխարեն

Կազմակերպության մակարդակի endpoints

Գրանցել արտաքին բանալի ձեր կազմակերպությունում

AWS

Հարցման օրինակ

type: string - միշտ “aws”
name: string - ձեր կազմաձևի հեշտ ճանաչելի անունը
role_arn: string - Role ARN-ը, որը OpenAI-ն կստանձնի ձեր ամպում
kms_arn: string - ձեր կառավարած գլխավոր բանալու Key Management System ARN-ը
external_id: string - ձեր կազմակերպության ID-ն կամ API նախագծի 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>
}'

Պատասխանի օրինակ

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

Հարցման օրինակ

type: string - միշտ "gcp",
name: string - ձեր կազմաձևի հեշտ ճանաչելի անունը
workload_identity_project_number: string - GCP նախագծի 12-նիշանոց համարը, որտեղ գրանցել եք OpenAI-ի workload identity-ն
workload_identity_pool_id: string - այն pool-ը, որը պարունակում է OpenAI-ի համար գրանցած Workload Identity provider-ը
workload_identity_provider_id: string - Workload Identity provider-ը, որը գրանցել եք OpenAI-ի համար
audience: string - audience-ը, որը OpenAI-ն պետք է փոխանցի թոքենում, երբ ձեր GCP STS-ի միջոցով role է ստանձնում
kms_project_id: string - GCP նախագծի անունը, որտեղ գտնվում է ձեր KMS-ը
kms_key_ring_name: string - Key Management System key ring-ը, որը պարունակում է ձեր կառավարած գլխավոր բանալին
kms_key_name: string - Key Management System գլխավոր բանալու անունը
kms_key_location: string - տարածաշրջանը, որտեղ գտնվում է ձեր Key Management System գլխավոր բանալին

Եթե ձեր KMS-ը գտնվում է այլ GCP նախագծում, քան այն, որտեղ գրանցել եք OpenAI-ի Workload Identity-ն, համոզվեք, որ OpenAI-ի Workload Identity-ն պարունակող նախագծում առնվազն KMS-ը միացված է՝ այցելելով 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"
}'

Պատասխանի օրինակ

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

Հարցման օրինակ

type: string - միշտ "azure",
name: string - ձեր կազմաձևի հեշտ ճանաչելի անունը
tenant_id: string - ձեր Azure tenant-ի UUID-ն
vault_uri: string - ձեր կառավարած գլխավոր բանալին պարունակող Azure vault-ի URI-ն
key_name: string - ձեր կառավարած Azure Key Vault գլխավոր բանալու անունը։
- Այն պետք է ունենա <org-xxx>--<any_name> ձևը
- որտեղ org-xxx-ը ձեր OpenAI կազմակերպության ID-ն է, որը կարող եք գտնել այստեղ՝ https://platform.openai.com/settings/organization/general

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

Պատասխանի օրինակ

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

Ջնջել ձեր կազմակերպությունում գրանցված արտաքին բանալին

Նշում. Արտաքին բանալին կարող եք ջնջել միայն այն դեպքում, երբ այն կապված չէ որևէ ակտիվ API նախագծի կամ աշխատատարածքի հետ։ Եթե այն կապված է ակտիվ API նախագծի հետ, նախ արխիվացրեք այդ նախագիծը։ Եթե այն կապված է աշխատատարածքի հետ, բանալին չի կարող ջնջվել։

Հարցման օրինակ

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

Պատասխանի օրինակ

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

Ստանալ ձեր կազմակերպությունում գրանցված արտաքին բանալիները

Հարցման օրինակ

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

Պատասխանի օրինակ

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

Վավերացնել արտաքին բանալին

Այս endpoint-ը կարող եք օգտագործել մի քանի բան ստուգելու համար

Ձեր արտաքին ամպային կազմաձևը OpenAI-ի հետ մնում է վավեր փոփոխություններ կատարելուց հետո (կտեսնեք հաջողության պատասխան)
Ձեր բանալու չեղարկումը ճիշտ է կատարվել, մշակվում է OpenAI-ի կողմից և ուժի մեջ կմտնի 1 ժամանոց քեշի TTL-ների ավարտից հետո (կտեսնեք սխալի պատասխան)

Հարցման օրինակ

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

Պատասխանի օրինակ

{
 "status": "success"
}

Կամ՝ ամպային մատակարարից ստացված սխալ։

Նախագծի մակարդակի endpoints

Ստեղծել նոր նախագիծ արտաքին բանալու ID-ով

Սա նույնն է, ինչ գործող Create Project endpoint-ը, պարզապես հարցման և պատասխանի մեջ ավելացված է external_key_id պարամետրը։

Հարցման օրինակ

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

Պատասխանի օրինակ

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

[Սահմանափակված] Թարմացնել գոյություն ունեցող նախագիծը արտաքին բանալու ID-ով

Սա նույնն է, ինչ գործող Update Project endpoint-ը, պարզապես հարցման և պատասխանի մեջ ավելացված է external_key_id պարամետրը։

Խորհուրդ ենք տալիս ձեր EKM ծանրաբեռնվածությունների համար ստեղծել նոր API նախագծեր։ Եթե ցանկանում եք EKM միացնել ձեր բոլոր գոյություն ունեցող API նախագծերում, դիմեք ձեր հաշվի տնօրենին, և մենք ձեզ կավելացնենք feature flag-ին։ Նախքան EKM-ը ձեր գոյություն ունեցող արտադրական նախագծերում ներդնելը, նկատի ունեցեք հետևյալ լավագույն գործելակերպերը։

Նախ փորձարկեք արտադրությունում օգտագործվող բոլոր API գործառույթները ձեր փորձնական EKM API նախագծում
Կիրառեք աստիճանական ներդրում՝ EKM-ը միանգամից բոլոր արտադրական API նախագծերում միացնելու փոխարեն

Հարցման օրինակ

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

Ցուցադրել ձեր կազմակերպության բոլոր նախագծերը

Սա նույնն է, ինչ գործող endpoint-ը, պարզապես API պատասխանում ավելացված է external_key_id

Հարցման օրինակ

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

Պատասխանի օրինակ

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

EKM (արտաքին բանալիներ) Management API-ում

Ամփոփում

Մուտք

Օգտագործում

Սահմանափակումներ

Կազմակերպության մակարդակի endpoints

Գրանցել արտաքին բանալի ձեր կազմակերպությունում

AWS

Հարցման օրինակ

Պատասխանի օրինակ

GCP

Հարցման օրինակ

Պատասխանի օրինակ

Azure

Հարցման օրինակ

Պատասխանի օրինակ

Ջնջել ձեր կազմակերպությունում գրանցված արտաքին բանալին

Հարցման օրինակ

Պատասխանի օրինակ

Ստանալ ձեր կազմակերպությունում գրանցված արտաքին բանալիները

Հարցման օրինակ

Պատասխանի օրինակ

Վավերացնել արտաքին բանալին

Հարցման օրինակ

Պատասխանի օրինակ

Նախագծի մակարդակի endpoints

Ստեղծել նոր նախագիծ արտաքին բանալու ID-ով

Հարցման օրինակ

Պատասխանի օրինակ

[Սահմանափակված] Թարմացնել գոյություն ունեցող նախագիծը արտաքին բանալու ID-ով

Հարցման օրինակ

Ցուցադրել ձեր կազմակերպության բոլոր նախագծերը

Հարցման օրինակ

Պատասխանի օրինակ

Այս հոդվածն օգտակա՞ր էր։