OpenAI
ეს გვერდი მანქანური თარგმანის მეშვეობით ითარგმნა. სტატიის ინგლისური დედნის ნახვა.

EKM (გარე გასაღებები) Management API-ში

მართეთ EKM-ის გარე გასაღებები Management API-ის გამოყენებით

განახლებულია: 7 days ago

შეჯამება

წვდომა

  • EKM endpoint-ებზე წვდომა შესაძლებელია Management API-ში Admin API გასაღებით. https://platform.openai.com/settings/organization/admin-keys (არ გამოიყენოთ ჩვეულებრივი API გასაღები). Admin API გასაღებები ხელმისაწვდომია ორგანიზაციის მფლობელებისთვის.

  • გამოიყენეთ api.external_keys.write გარე გასაღებების შესაქმნელად ან წასაშლელად, ხოლო api.external_keys.read — გარე გასაღებების ჩამოსათვლელად ან დასადასტურებლად. ერთ გასაღებს ორივე scope მხოლოდ მაშინ სჭირდება, თუ მან წაკითხვისა და ჩაწერის ოპერაციებიც უნდა შეასრულოს.

  • ამ endpoint-ებისთვის თქვენს ორგანიზაციას ამჟამად 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 კონფიგურაციები აქტიურდება პროექტის დონეზე, როცა external_key_id გადაეცემა არსებული Create Project endpoint-ის https://api.openai.com/v1/organization/projects body-ში

შეზღუდვები

  • ჯერ EKM უნდა გამოსცადოთ ახალ პროექტზე Management API-ის მეშვეობით.

  • გირჩევთ, თქვენი EKM სამუშაო დატვირთვებისთვის ახალი პროექტები შექმნათ. თუმცა, თუ EKM არსებულ პროექტზე გსურთ, შეგვიძლია feature flag-ში დაგამატოთ. სანამ EKM-ს არსებულ საწარმოო პროექტებზე გაუშვებთ, გაითვალისწინეთ შემდეგი საუკეთესო პრაქტიკები.

    • ჯერ თქვენს სატესტო EKM API პროექტში შეამოწმეთ ყველა API ფუნქცია, რომელსაც საწარმოო გარემოში იყენებთ

    • ყველა საწარმოო API პროექტზე EKM-ის ერთბაშად დამატების ნაცვლად, გამოიყენეთ ეტაპობრივი გაშვება

ორგანიზაციის დონის endpoint-ები

თქვენს ორგანიზაციაში გარე გასაღების რეგისტრაცია

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, რომელიც შეიცავს Workload Identity provider-ს, რომელიც OpenAI-ისთვის დაარეგისტრირეთ

  • workload_identity_provider_id: string - Workload Identity provider, რომელიც OpenAI-ისთვის დაარეგისტრირეთ

  • audience: string - audience, რომელიც OpenAI-მ token-ში უნდა გადასცეს, როცა თქვენი GCP STS-ის მეშვეობით როლს ვიღებთ

  • 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-საათიანი cache TTL-ების ამოწურვის შემდეგ (დაინახავთ შეცდომის პასუხს)

მოთხოვნის ნიმუში

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

პასუხის ნიმუში

{
 "status": "success"
}

ან ღრუბლოვანი პროვაიდერისგან მიღებული შეცდომა.

პროექტის დონის endpoint-ები

ახალი პროექტის შექმნა გარე გასაღების 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-ს არსებულ საწარმოო პროექტებზე გაუშვებთ, გაითვალისწინეთ შემდეგი საუკეთესო პრაქტიკები.

  • ჯერ თქვენს სატესტო EKM API პროექტში შეამოწმეთ ყველა API ფუნქცია, რომელსაც საწარმოო გარემოში იყენებთ

  • ყველა საწარმოო API პროექტზე EKM-ის ერთბაშად დამატების ნაცვლად, გამოიყენეთ ეტაპობრივი გაშვება

მოთხოვნის ნიმუში

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
}

სასარგებლო იყო ეს სტატია?