Ամփոփում
Մուտք
EKM վերջնակետերը հասանելի են Կառավարման API-ում՝ Ադմինիստրատորի API բանալիով։ https://platform.openai.com/settings/organization/admin-keys (մի՛ օգտագործեք սովորական API բանալի)։ Ադմինիստրատորի API բանալիները հասանելի են կազմակերպության սեփականատերերին։
Արտաքին բանալիներ ստեղծելու կամ ջնջելու համար օգտագործեք
api.external_keys.write, իսկ արտաքին բանալիների ցանկը ստանալու կամ դրանց վավերականությունը ստուգելու համար՝api.external_keys.read։ Մեկ բանալուն երկու թույլտվություններն էլ անհրաժեշտ են միայն այն դեպքում, երբ այն պետք է կատարի և՛ կարդալու, և՛ գրելու գործողություններ։Այս պահին մենք պետք է գործառույթի դրոշակով ձեր կազմակերպության համար ակտիվացնենք այս վերջնակետերի հասանելիությունը։ Գործառույթի դրոշակն ակտիվ է, եթե նախագծերի ցանկը վերադարձնող գործող վերջնակետի պատասխանում տեսնում եք external_key_id՝ https://api.openai.com/v1/organization/projects։
Օգտագործում
Ձեր EKM կազմաձևումը գրանցվում է կազմակերպության մակարդակում՝ նոր վերջնակետի միջոցով՝ https://api.openai.com/v1/organization/external_keys։
EKM կազմաձևումը գրանցելիս վերադարձվում է external_key_id՝ extkey_xxxx ձևաչափով։
EKM կազմաձևումները ակտիվացվում են նախագծի մակարդակում՝ նախագծի ստեղծման գործող https://api.openai.com/v1/organization/projects վերջնակետին ուղղված հարցման մարմնում փոխանցելով external_key_id։
Սահմանափակումներ
Նախ պետք է EKM-ն փորձարկեք նոր նախագծում՝ Կառավարման API-ի միջոցով։
Խորհուրդ ենք տալիս EKM օգտագործող առաջադրանքների համար ստեղծել նոր նախագծեր։ Սակայն եթե ցանկանում եք EKM-ն օգտագործել առկա նախագծում, կարող ենք ձեզ համար ակտիվացնել գործառույթի դրոշակը։ Նախքան EKM-ն ձեր առկա արտադրական նախագծերում ներդնելը հաշվի առեք հետևյալ առաջարկվող գործելակերպերը։
Արտադրական միջավայրում օգտագործվող API-ի բոլոր գործառույթները նախ փորձարկեք ձեր փորձնական EKM API նախագծում։
EKM-ն ներդրեք փուլ առ փուլ, այլ ոչ թե միանգամից բոլոր արտադրական API նախագծերում։
Կազմակերպության մակարդակի endpoints
Գրանցել արտաքին բանալի ձեր կազմակերպությունում
AWS
Հարցման օրինակ՝
type՝ տող — միշտ «aws»
name՝ տող — ձեր կազմաձևման համար հեշտ ճանաչելի անուն
role_arn՝ տող — այն դերի ARN-ը, որը OpenAI-ը կստանձնի ձեր ամպային միջավայրում
kms_arn՝ տող — ձեր կառավարած հիմնական բանալու ARN-ը բանալիների կառավարման համակարգում
external_id՝ տող — ձեր Կազմակերպության 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՝ տող — միշտ «gcp»,
name՝ տող — ձեր կազմաձևման համար հեշտ ճանաչելի անուն
workload_identity_project_number՝ տող — այն GCP նախագծի թվային համարը, որտեղ գրանցել եք OpenAI-ի Workload Identity-ն
workload_identity_pool_id՝ տող — այն խումբը, որը պարունակում է OpenAI-ի համար ձեր գրանցած Workload Identity մատակարարին
workload_identity_provider_id՝ տող — OpenAI-ի համար ձեր գրանցած Workload Identity մատակարարը
audience: տող — թիրախային ստացողը, որը OpenAI-ը պետք է փոխանցի նույնականացման թոքենում, երբ ձեր GCP STS-ի միջոցով դեր ենք ստանձնում
kms_project_id: տող — այն GCP նախագծի անունը, որտեղ տեղակայված է ձեր KMS-ը
kms_key_ring_name՝ տող — բանալիների կառավարման համակարգի բանալիների հավաքածուն, որը պարունակում է ձեր կառավարած հիմնական բանալին
kms_key_name՝ տող — բանալիների կառավարման համակարգի հիմնական բանալու անունը
kms_key_location՝ տող — այն տարածաշրջանը, որտեղ գտնվում է ձեր բանալիների կառավարման համակարգի հիմնական բանալին
Եթե ձեր 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՝ տող — միշտ «azure»,
name՝ տող — ձեր կազմաձևման համար հեշտ ճանաչելի անուն
tenant_id՝ տող — ձեր Azure վարձակալի UUID-ն
vault_uri՝ տող — ձեր կառավարած հիմնական բանալին պարունակող Azure պահոցի URI-ն
key_name՝ տող — ձեր կառավարած 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"
}Ստուգել արտաքին բանալու վավերականությունը
Այս վերջնակետով կարող եք ստուգել հետևյալը՝
Ձեր արտաքին ամպային միջավայրի կազմաձևումը փոփոխություններից հետո շարունակում է վավեր լինել 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-ով
Սա նախագծի ստեղծման նույն գործող վերջնակետն է, սակայն հարցմանն ու պատասխանին ավելացվել է 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": "organization.project",
"id": "proj_xxxxx",
"name": "Some Project",
"external_key_id": "extkey_xxxx",
"created_at": 1740012721,
"archived_at": null,
"status": "active"
}[Սահմանափակ հասանելիություն] Թարմացնել առկա նախագիծը՝ ավելացնելով արտաքին բանալու ID
Սա նախագծի թարմացման նույն գործող վերջնակետն է, սակայն հարցմանն ու պատասխանին ավելացվել է external_key_id պարամետրը։
Խորհուրդ ենք տալիս EKM օգտագործող առաջադրանքների համար ստեղծել նոր API նախագծեր։ Եթե ցանկանում եք EKM-ն օգտագործել ձեր բոլոր առկա API նախագծերում, դիմեք ձեր հաշվի պատասխանատուին, և մենք ձեզ համար կակտիվացնենք գործառույթի դրոշակը։ Նախքան 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"
}'Ստանալ ձեր կազմակերպության բոլոր նախագծերի ցանկը
Սա նույն գործող վերջնակետն է, սակայն 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
}