API キー
API キーは、Zilliz Cloud の control plane および data plane リソースにアクセスするために API または SDK 呼び出しを行うユーザーまたはアプリケーションを認証するために使用されます。API キーは、名前や ID などの独自のプロパティを持つ英数字の文字列です。
API キーの概要
Zilliz Cloud では、多様なユーザー要件に対応するために 2 種類の API キーを提供しています。
-
Personal API keys: ユーザー登録時に自動生成され、各キーはユーザーのアカウントに関連付けられ、ユーザーが所属する organization および project におけるユーザーのロールの権限を継承します。アカウントユーザーが organization を離れると、関連する personal キーは自動的に削除されます。Organization Owner または Project Admin として、Zilliz Cloud Web コンソールでは次の 2 種類の personal API キーを確認できます。
-
Your own personal API key: 自分のみに属する personal キーです。この API キーを表示してコピーできます。
-
Member's personal API key: organization または project 内の他のユーザーに属する既存の personal キーの一覧です。これらのキーの名前と ID のみを表示でき、キーそのものは表示できません。
-
-
Customized API keys: Organization Owners と Project Admins が、Zilliz Cloud アカウントを持たないアプリケーションまたは外部ユーザーのために手動で作成するキーです。これらのキーは長期的なアクセス要件に適しており、API キーの初期作成者が organization を離れた場合でもサービス継続性を確保できます。
本番環境では、代わりに customized キーを使用してください。Personal API keys はユーザーアカウントとともに削除されます。
次の図は、API Key のロールとリソースアクセスを示しています。
以下の表は、割り当てられたロールに基づく API キーのアクセス範囲を詳しく示しています。ロールと権限の詳細については、Access Control Explained を参照してください。
API Key Role | Access Level | |
|---|---|---|
Organization Owner | organization 内のすべてのリソース（projects、clusters、volumes を含む）に対する完全な管理者アクセス。 | |
Organization Billing Admin | organization の請求に対する管理者アクセスのみ。organization 内の projects、clusters、volumes にはアクセスできません。 | |
Organization Member | Project Admin | 指定された projects に対する完全な管理者アクセス、およびデフォルトでその projects 内のすべての clusters と volumes に対する完全な管理者アクセス。 |
Project Read-Write | 指定された projects に対する読み取りおよび書き込みアクセス、およびデフォルトでその projects 内のすべての clusters と volumes に対する読み取りおよび書き込みアクセス。 | |
Project Read-Only | 指定された projects に対する読み取り専用アクセス、およびデフォルトでその projects 内のすべての clusters と volumes に対する読み取り専用アクセス。 | |
制限事項
-
データ操作を実行するには、代わりに cluster token を使用してください。有効な cluster token は
user:passのように、コロンで区切られた cluster のユーザー名とパスワードです。 -
各 organization には、最大 100 個の customized API キーを含めることができます。
-
API キーの管理権限は、organization および project におけるユーザーのロールの影響を受けます。具体的な権限は次のとおりです。
Organization Owner
Organization Billing Admin
Organization Member
Project Admin
Project Read-Write
Project Read-Only
Your Own Personal API Key
Create
自動生成
自動生成
自動生成
自動生成
自動生成
View and copy
Edit
Reset
Delete
ユーザーが organization を離れると自動削除
ユーザーが organization を離れると自動削除
ユーザーが organization を離れると自動削除
ユーザーが organization を離れると自動削除
ユーザーが organization を離れると自動削除
Members' Personal API Key
Create
自動生成
自動生成
自動生成
自動生成
自動生成
View names and IDs
Copy
Edit
Reset
Delete
メンバーが organization を離れると自動削除
メンバーが organization を離れると自動削除
メンバーが organization を離れると自動削除
メンバーが organization を離れると自動削除
メンバーが organization を離れると自動削除
Customized API Key
Create
View and copy
Edit
Reset
Delete
API キーを作成する
Zilliz Cloud が各 organization ユーザーに対して自動生成する personal キーとは別に、customized キーを作成できます。customized API キーを作成できるのは Organization Owners と Project Admins のみです。
organization の API Keys ページに移動します。+ API Key をクリックします。
API Key Name を入力し、API Key Access を設定します。
-
API Key Name: 名前は 64 文字を超えてはいけません。
-
API Key Description (optional): 作成する API キーの説明です。最大 255 文字です。
-
API Key Access: 適切な organization および project ロールを割り当てることで、現在の customized API キーのアクセス範囲を定義します。さらに細かなアクセス制御が必要な場合は、Restrict Access to Specific Clusters and Volumes をチェックして、キーがアクセスできる clusters と volumes を制限できます。
📘📘 NotesProject Admins の場合、このユーザーが API キーに付与できる権限は、そのユーザー自身の権限範囲に制限されます。
API キーを表示する
organization の API Keys ページに移動します。表示内容は、あなたの具体的な role によって異なる場合があります。
-
Organization Owner としては、自分の personal キー、すべてのメンバーの personal キー、およびすべての customized キーを表示できます。
-
Project Admin としては、自分の personal キーに加え、自分の権限範囲内にあるメンバーの personal キーおよび customized キーを表示できます。たとえば、User 1 が Project A のみの Project Admin であり、Key 1 が Projects A、B、および C に対する Admin アクセスを持つ場合、Key 1 のアクセス範囲は User 1 の権限を超えているため、User 1 には Key 1 は表示されません。
-
Organization Billing Admin、Project Read-Write、または Project Read-Only としては、自分の personal API キーのみを表示できます。
以下のスクリーンショットは、Organization Owner の API キー表示画面を示しています。
API キーを編集する
現在、編集できるのは customized API キーのみです。Personal キーはアカウントユーザーに紐付いているため、編集できません。personal キーのアクセス範囲を変更するには、まずユーザーの organization および project ロールを調整する必要があります。ユーザーのロールに対する変更は、キーのアクセス権限に自動的に反映されます。
以下の手順では、customized API キーを編集する方法を説明します。
organization の API Keys ページに移動します。操作列の ... をクリックし、Edit をクリックします。
API キーの API Key Name と API Key Access を編集します。
-
API Key Name: 名前は 64 文字を超えてはいけません。
-
API Key Access: 適切な organization および project ロールを割り当てることで、現在の customized API キーのアクセス範囲を定義します。さらに細かなアクセス制御が必要な場合は、Restrict Access to Specific Clusters and Volumes をチェックして、キーがアクセスできる clusters と volumes を制限できます。
📘📘 NotesProject Admins の場合、このユーザーが API キーに付与できる権限は、そのユーザー自身の権限範囲に制限されます。
API キーをリセットする
personal または customized API キーが侵害された可能性がある場合は、直ちにリセットする必要があります。
この操作により、現在の API キーはリセットされ、無効になります。このキーを使用しているアプリケーションコードは、新しいキー値で関連コードを更新するまで動作を停止します。
キーの種類に応じて、手順は異なります。
-
Reset personal API keys: ロールに関係なく、自分自身の personal API キーのみリセットできます。
-
Reset customized API keys: customized API キーをリセットできるのは Organization Owners と Project Admins のみです。
API キーを削除する
customized API キーが不要になった場合は、できるだけ早く削除してください。customized API キーを削除できるのは Organization Owners と Project Admins のみです。
personal キーは手動で削除できません。ただし、対応するユーザーが organization を離れると、自動的に無効化および削除されます。
以下のスクリーンショットは、customized API キーを削除する方法を示しています。
API キーを削除すると、そのキーを使用しているあらゆるサービスの Zilliz Cloud リソースへのアクセスは不可逆的に終了します。
FAQ
本番環境で personal API キーを使用すべきですか？
いいえ。Personal API keys は個々のユーザーアカウントに紐付いており、ユーザーが organization を離れると自動的に削除されます。キー所有者のアカウントが削除されると、そのキーに依存しているアプリケーションやサービスは直ちに Zilliz Cloud リソースへのアクセスを失います。
本番環境では、代わりに customized API keys を使用してください。customized キーは特定の個人ユーザーアカウントに依存しないため、チームメンバーが organization を離れた場合でもサービス継続性を確保できます。