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

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

შეიტყვეთ, როგორ მართოთ EKM-ის გარე გასაღებები მართვის API-ით.

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

შეჯამება

წვდომა

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

შეზღუდვები

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

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

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

    • EKM ეტაპობრივად დანერგეთ და არა ყველა საწარმოო API პროექტში ერთდროულად.

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

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

AWS

მოთხოვნის მაგალითი:

  • type: სტრიქონი — ყოველთვის „aws“

  • name: სტრიქონი — თქვენი კონფიგურაციის ადვილად ამოსაცნობი სახელი

  • role_arn: სტრიქონი — იმ როლის ARN, რომელსაც OpenAI თქვენს ღრუბლოვან გარემოში მიიღებს

  • 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: სტრიქონი — იმ 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 ორგანიზაციის იდენტიფიკატორი, რომელიც შეგიძლიათ ნახოთ ბმულზე 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"
}

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

პროექტის დონის 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": "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 პროექტები შექმნათ. თუ გსურთ 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
}

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