Қорытынды
Қол жеткізу
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 конфигурациясын тіркегенде, extkey_xxxx пішіміндегі external_key_id қайтарылады.
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: жол — OpenAI бұлттық ортаңызда қабылдайтын рөлдің ARN идентификаторы
kms_arn: жол — сіз басқаратын негізгі кілттің кілттерді басқару жүйесіндегі ARN идентификаторы
external_id: жол — ұйым идентификаторы немесе 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>"
}'Жауап үлгісі:
{
"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: жол — OpenAI жұмыс жүктемесінің сәйкестендіру деректерін тіркеген GCP жобасының сандық нөмірі
workload_identity_pool_id: жол — OpenAI үшін тіркеген Workload Identity провайдері бар пул
workload_identity_provider_id: жол — OpenAI үшін тіркеген Workload Identity провайдері
audience: жол — GCP STS қызметіңіз арқылы рөлді қабылдаған кезде OpenAI токенде көрсетуі тиіс аудитория
kms_project_id: жол — KMS жүйеңіз орналасқан GCP жобасының атауы
kms_key_ring_name: жол — сіз басқаратын негізгі кілтті қамтитын кілттерді басқару жүйесінің кілттер жинағы
kms_key_name: жол — кілттерді басқару жүйесіндегі негізгі кілттің атауы
kms_key_location: жол — кілттерді басқару жүйесіндегі негізгі кілт орналасқан аймақ
Егер KMS жүйеңіз OpenAI үшін Workload Identity тіркеген GCP жобасынан басқа жобада орналасса, https://console.developers.google.com/apis/api/cloudkms.googleapis.com/overview бетіне өтіп, OpenAI Workload Identity деректері бар жобада кем дегенде KMS қосылғанына көз жеткізіңіз.
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 ұйым идентификаторы. Оны 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
Сыртқы кілт идентификаторы бар жаңа жоба жасау
Бұл қолданыстағы жоба жасау соңғы нүктесімен бірдей, тек сұрау мен жауапқа 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"
}[Қолжетімділігі шектеулі] Қолданыстағы жобаны сыртқы кілт идентификаторымен жаңарту
Бұл қолданыстағы жобаны жаңарту соңғы нүктесімен бірдей, тек сұрау мен жауапқа external_key_id параметрі қосылған.
EKM жұмыс жүктемелері үшін жаңа API жобаларын жасауды ұсынамыз. Қолданыстағы барлық API жобаларыңызға EKM қосуды қаласаңыз, клиенттік менеджеріңізге хабарласыңыз, сонда біз сізге бұл мүмкіндікті қосамыз. 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
}