ማጠቃለያ

መዳረሻ

የEKM endpoints በManagement API ውስጥ በAdmin API Key በኩል መድረስ ይቻላል። https://platform.openai.com/settings/organization/admin-keys (መደበኛ API key አይጠቀሙ)። Admin API keys ለorganization owners ይገኛሉ።
ውጫዊ keys ለመፍጠር ወይም ለመሰረዝ api.external_keys.write ይጠቀሙ፤ ውጫዊ keys ለመዘርዘር ወይም ለማረጋገጥ ደግሞ api.external_keys.read ይጠቀሙ። አንድ key ሁለቱንም scopes የሚያስፈልገው የማንበብም የመጻፍም ክንውኖችን መፈጸም ካለበት ብቻ ነው።
በአሁኑ ጊዜ ድርጅትዎን ወደ እነዚህ endpoints በfeature flag ማስገባት ያስፈልገናል። ከነባሩ List Projects endpoint የተመለሰ external_key_id ካዩ፣ feature flag እንዳለዎት ያውቃሉ፦ https://api.openai.com/v1/organization/projects

አጠቃቀም

የEKM configዎ በአዲስ endpoint https://api.openai.com/v1/organization/external_keys በኩል በorganization ደረጃ ይመዘገባል
የEKM configዎን ሲመዘግቡ በextkey_xxxx ቅርጸት external_key_id ይመልሳል
የEKM configs በነባሩ Create Project https://api.openai.com/v1/organization/projects endpoint አካል ውስጥ external_key_id በማስተላለፍ በproject ደረጃ ይነቃቃሉ

ገደቦች

መጀመሪያ EKMን በአዲስ ፕሮጀክት ላይ በManagement API በኩል መፈተሽ አለብዎት።
ለEKM workloadsዎ አዲስ ፕሮጀክቶችን እንዲጀምሩ እንመክራለን። ነገር ግን EKMን በነባር ፕሮጀክት ላይ ከፈለጉ፣ ወደ feature flag ልንጨምርዎ እንችላለን። EKMን ወደ ነባር production ፕሮጀክቶችዎ ከማስጀመርዎ በፊት እባክዎ የሚከተሉትን ምርጥ ልምዶች ያስተውሉ።
- በproduction ውስጥ የሚጠቀሙባቸውን ሁሉንም API ባህሪያት መጀመሪያ በሙከራ EKM API ፕሮጀክትዎ ውስጥ ይፈትሹ
- EKMን በሁሉም production API ፕሮጀክቶች ላይ በአንድ ጊዜ ከመሙላት ይልቅ ቀስ በቀስ የሚካሄድ rollout ይተግብሩ

በድርጅት ደረጃ endpoints

በድርጅትዎ ላይ ውጫዊ key ይመዝግቡ

AWS

የናሙና ጥያቄ

type: string - ሁልጊዜ “aws”
name: string - ለconfigዎ ቀላል መጠሪያ ስም
role_arn: string - OpenAI በcloudዎ ውስጥ የሚወስደው Role ARN
kms_arn: string - ለሚያስተዳድሩት master key የKey Management System ARN
external_id: string - የድርጅትዎ id ወይም API project 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 - ለconfigዎ ቀላል መጠሪያ ስም
workload_identity_project_number: string - የOpenAI workload identity የመዘገቡበት 12-አሃዝ GCP ፕሮጀክት ቁጥር
workload_identity_pool_id: string - ለOpenAI የመዘገቡትን Workload Identity provider የያዘ pool
workload_identity_provider_id: string - ለOpenAI የመዘገቡት Workload Identity provider
audience: string - በGCP STSዎ በኩል role ስንወስድ OpenAI በtoken ውስጥ ማስተላለፍ ያለበት audience
kms_project_id: string - KMSዎ የሚገኝበት የGCP ፕሮጀክት ስም
kms_key_ring_name: string - የሚያስተዳድሩትን master key የያዘ የKey Management System key ring
kms_key_name: string - የKey Management System master key ስም
kms_key_location: string - የKey Management System master keyዎ የሚገኝበት region

KMSዎ OpenAI's Workload Identity ከመዘገቡበት የGCP ፕሮጀክት በተለየ ፕሮጀክት ውስጥ ከሆነ፣ OpenAI's 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 - ለconfigዎ ቀላል መጠሪያ ስም
tenant_id: string - የAzure tenant UUIDዎ
vault_uri: string - የሚያስተዳድሩትን master key የያዘው የAzure vault URI
key_name: string - የሚያስተዳድሩት የAzure Key Vault master key ስም።
- በ<org-xxx>--<any_name> ቅርጸት መሆን አለበት
- እዚህ org-xxx በhttps://platform.openai.com/settings/organization/general ላይ ሊያገኙት የሚችሉት የOpenAI ድርጅትዎ ID ነው

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

በድርጅትዎ ላይ የተመዘገበ ውጫዊ key ይሰርዙ

ማስታወሻ፦ ውጫዊ key መሰረዝ የሚችሉት ከማንኛውም ንቁ API ፕሮጀክቶች ወይም የስራ ቦታ ጋር ካልተያያዘ ብቻ ነው። ከንቁ API ፕሮጀክት ጋር ተያይዞ ከሆነ፣ መጀመሪያ ያንን ፕሮጀክት archive ያድርጉ። ከየስራ ቦታ ጋር ተያይዞ ከሆነ፣ key መሰረዝ አይቻልም።

የናሙና ጥያቄ

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

በድርጅትዎ ላይ የተመዘገቡ ውጫዊ keys ያግኙ

የናሙና ጥያቄ

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

ውጫዊ key ያረጋግጡ

ይህን endpoint በመጠቀም ብዙ ነገሮችን መፈተሽ ይችላሉ

ለውጦችን ካደረጉ በኋላ ውጫዊ cloud configurationዎ ከOpenAI ጋር እንደቀጠለ ትክክለኛ መሆኑን (የስኬት ምላሽ ያያሉ)
የkey መሻርዎ በትክክል እንደተከናወነ፣ በOpenAI እየተሰራ እንዳለ፣ እና የ1 ሰዓት cache TTLs ካበቁ በኋላ ተግባራዊ እንደሚሆን (የስህተት ምላሽ ያያሉ)

የናሙና ጥያቄ

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

የናሙና ምላሽ

{
 "status": "success"
}

ወይም ከcloud provider የወጣ ስህተት።

በፕሮጀክት ደረጃ endpoints

በውጫዊ key ID አዲስ ፕሮጀክት ይፍጠሩ

ይህ ከነባሩ Create Project endpoint ጋር ተመሳሳይ ነው፤ በጥያቄውና በምላሹ ውስጥ የexternal_key_id parameter ተጨምሮበታል።

የናሙና ጥያቄ

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

[Restricted] ነባር ፕሮጀክትን በውጫዊ key ID ያዘምኑ

ይህ ከነባሩ Update Project endpoint ጋር ተመሳሳይ ነው፤ በጥያቄውና በምላሹ ውስጥ የexternal_key_id parameter ተጨምሮበታል።

ለEKM workloadsዎ አዲስ API ፕሮጀክቶችን እንዲጀምሩ እንመክራለን። በሁሉም ነባር API ፕሮጀክቶችዎ ላይ EKM ከፈለጉ፣ የaccount directorዎን ይጠይቁ፤ እኛም ወደ feature flag እንጨምርዎታለን። EKMን ወደ ነባር production ፕሮጀክቶችዎ ከማስጀመርዎ በፊት እባክዎ የሚከተሉትን ምርጥ ልምዶች ያስተውሉ።

በproduction ውስጥ የሚጠቀሙባቸውን ሁሉንም API ባህሪያት መጀመሪያ በሙከራ EKM API ፕሮጀክትዎ ውስጥ ይፈትሹ
EKMን በሁሉም production API ፕሮጀክቶች ላይ በአንድ ጊዜ ከመሙላት ይልቅ ቀስ በቀስ የሚካሄድ rollout ይተግብሩ

የናሙና ጥያቄ

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 (External Keys) በManagement API ውስጥ

ማጠቃለያ

መዳረሻ

አጠቃቀም

ገደቦች

በድርጅት ደረጃ endpoints

በድርጅትዎ ላይ ውጫዊ key ይመዝግቡ

AWS

የናሙና ጥያቄ

የናሙና ምላሽ

GCP

የናሙና ጥያቄ

የናሙና ምላሽ

Azure

የናሙና ጥያቄ

የናሙና ምላሽ

በድርጅትዎ ላይ የተመዘገበ ውጫዊ key ይሰርዙ

የናሙና ጥያቄ

የናሙና ምላሽ

በድርጅትዎ ላይ የተመዘገቡ ውጫዊ keys ያግኙ

የናሙና ጥያቄ

የናሙና ምላሽ

ውጫዊ key ያረጋግጡ

የናሙና ጥያቄ

የናሙና ምላሽ

በፕሮጀክት ደረጃ endpoints

በውጫዊ key ID አዲስ ፕሮጀክት ይፍጠሩ

የናሙና ጥያቄ

የናሙና ምላሽ

[Restricted] ነባር ፕሮጀክትን በውጫዊ key ID ያዘምኑ

የናሙና ጥያቄ

በድርጅትዎ ላይ ያሉ ሁሉንም ፕሮጀክቶች ይዘርዝሩ

የናሙና ጥያቄ

የናሙና ምላሽ

ይህ ጽሑፍ ጠቃሚ ነበር?