キーを使用して Azure AI 検索に接続する
Azure AI 検索には、検索サービスへの接続用のキーベースの認証が用意されています。 API キーは、ランダムに生成された 52 個の数字と文字から成る一意の文字列です。 ソース コードでは、プロジェクトの環境変数としてまたはアプリ設定として指定し、要求で変数を参照できます。 検索サービス エンドポイントに対して行われた要求は、要求と API キーの両方が有効な場合に受け入れられます。
既定では、キーベースの認証となります。
これは、ロールベースのアクセスに置き換えることができます。そうすると、コードベースでキーをハードコーディングする必要がありません。
API キーの種類
要求の認証には、次の 2 種類のキーが使用されます。
| Type | アクセス許可レベル | 最大値 | 作成方法 |
|---|---|---|---|
| [Admin] | すべてのコンテンツ操作に対するフル アクセス (読み取り/書き込み) | 2 1 | プライマリ キーおよびセカンダリ キーと呼ばれる、ポータルの 2 つの管理者キーは、サービスの作成時に生成され、要求に応じて個別に再生成できます。 |
| クエリ | 検索インデックスのドキュメント コレクションを対象とした読み取り専用アクセス | 50 | サービスで 1 つのクエリ キーが生成されます。 検索サービス管理者は、さらに必要に応じて作成できます。 |
1 2 つあることで、サービスへの継続的なアクセスに 1 つのキーを使用している間に、もう 1 つのキーをロールオーバーできます。
管理者キーとクエリ キーに見た目の違いはありません。 どちらのキーも、ランダムに生成された 52 個の英数字からなる文字列です。 アプリケーションで指定されているキーの種類がわからなくなった場合、ポータルでキーの値を確認できます。
接続で API キーを使用する
API キーは、Search REST API で表されるインデックスやその他の要求の作成やアクセスなど、データ プレーン (コンテンツ) 要求に使用されます。 サービスの作成時に、API キーはデータ プレーン操作の唯一の認証メカニズムですが、コードでハードコーディングされたキーを使用できない場合は、キー認証を Azure ロールで置き換えたり補完したりできます。
管理キーは、オブジェクトの作成、変更、または削除に使用されます。 また、管理キーは、オブジェクト定義とシステム情報を取得 (GET) するためにも使用されます。
通常、クエリを発行するクライアント アプリケーションにクエリ キーが配布されます。
REST 呼び出しにおける API キーの使用方法:
要求ヘッダーに管理者キーを設定します。 URI または要求の本文で管理者キーを渡すことはできません。 管理者キーは、作成、読み取り、更新、削除操作や、インデックスの一覧取得 (LIST) やサービス統計情報の取得 (GET) など、検索サービス自体に対して発行された要求にも使用されます。
インデックス作成要求での管理者 API キーの使用方法の例を次に示します。
### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{adminApiKey}}
{
"name": "my-new-index",
"fields": [
{"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "Name", "type": "Edm.String", "searchable": true }
]
}
POST の要求ヘッダーまたは GET の URI にクエリ キーを設定します。 クエリ キーは、index/docs コレクションを対象とする操作 (ドキュメントの検索、オートコンプリート、提案、またはドキュメントの取得 (GET)) に使用されます。
ドキュメントの検索 (GET) 要求でのクエリ API キーの使用方法の例を次に示します。
### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}
Note
api-key などの機密データを要求 URI で渡すことは、セキュリティ上推奨されません。 このため、Azure AI Search はクエリ文字列内の api-key としてクエリ キーのみを受け入れます。 一般的なルールとして、api-key は要求ヘッダーとして渡すことをお勧めします。
API キーを表示または管理するためのアクセス許可
API キーを表示および管理するためのアクセス許可は、ロールの割り当てによって伝達されます。 次のロールのメンバーは、キーの表示と再生成が可能です:
- [所有者]
- Contributor
- Search Service Contributor
- 管理者と共同管理者 (クラシック)
次のロールは API キーにアクセスできません。
- 閲覧者
- 検索インデックス データ共同作成者
- 検索インデックス データ閲覧者
既存のキーを見つける
API キーを表示および管理するには、Azure portal を使用するか、PowerShell、Azure CLI、または REST API 経由で行います。
Azure portal にサインインし、ご利用の検索サービスを探します。
[設定] で [キー] を選択して、管理者キーとクエリ キーを表示します。
クエリ キーを作成する
クエリ キーは、ドキュメント コレクションをターゲットとする操作のために、インデックス内のドキュメントへの読み取り専用アクセスに使用されます。 検索、フィルター、および推奨クエリは、いずれもクエリ キーを取得する操作です。 インデックス定義やインデクサーの状態など、システム データまたはオブジェクト定義を返す読み取り専用操作には、管理者キーが必要です。
クライアント アプリでアクセスと操作を制限することは、サービスで検索アセットを保護するために不可欠です。 クライアント アプリから発信されたクエリには、常に管理者キーではなくクエリ キーを使用します。
Azure portal にサインインし、ご利用の検索サービスを探します。
[設定]で [キー] 選択して、API キーを表示します。
[クエリ キーの管理] で、サービス用に既に生成されているクエリ キーを使用するか、新しいクエリ キーを作成します。 既定のクエリ キーには名前はありませんが、生成された他のクエリ キーには、管理を容易にするために名前を付けることができます。
管理者キーを再生成する
ビジネス継続性のためにセカンダリ キーを使用しているときに、プライマリ キーをローテーションできるように、サービスごとに 2 つの管理者キーが作成されます。
[設定]で [キー] 選択し、セカンダリ キーをコピーします。
すべてのアプリケーションについて、セカンダリ キーを使用するように API キーの設定を更新します。
プライマリ キーを再生成します。
新しいプライマリ キーを使用するように、すべてのアプリケーションを更新します。
誤って両方のキーを同時に再生成すると、それらのキーを使用するすべてのクライアント要求が HTTP 403 Forbidden で失敗します。 ただし、コンテンツは削除されず、永続的にロックアウトされることはありません。
引き続き、ポータルまたはプログラムを使用してサービスにアクセスできます。 管理機能は、サービス API キーではなくサブスクリプション ID を使用して操作するため、自分の API キーがない場合でも使用できます。
ポータルまたは管理レイヤーを介して新しいキーを作成した後に、要求時にそのキーを指定すると、アクセスがコンテンツ (インデックス、インデクサー、データ ソース、シノニム マップ) に復元されます。
API キーをセキュリティ保護する
ロールの割り当てを使用して、API キーへのアクセスを制限します。
カスタマー マネージド キー暗号化を使用して API キーを暗号化することはできません。 CMK で暗号化できるのは、検索サービス自体内の機密データ (データ ソース オブジェクト定義のインデックス コンテンツや接続文字列など) のみです。
Azure portal で検索サービス ページを開きます。
左のナビゲーション ペインで、[アクセス制御 (IAM)] を選択し、[ロールの割り当て] タブを選択します。
[ロール] フィルターで、キーを表示または管理するアクセス許可を持つロール (所有者、共同作成者、Search Service 共同作成者) を選択します。 これらのロールに割り当てられた結果のセキュリティ プリンシパルは、検索サービスに対するキーのアクセス許可を持ちます。
予防措置として、[クラシック管理者] タブを確認して、管理者と共同管理者がアクセス権を持っているかどうかを確認します。
ベスト プラクティス
データ漏えいのリスクがない (サンプル データを使用する場合など) 場合や、ファイアウォールの背後で操作している場合にのみ、API キーを使用します。 API キーを公開すると、データと検索サービスの不正使用の両方のリスクがあります。
コード、サンプル、トレーニング資料は公開前に必ず確認し、有効な API キーを残さないようにします。
運用ワークロードの場合、Microsoft Entra ID とロールベースのアクセスに切り替えます。 または、API キーを引き続き使用する場合は、API キーにアクセスできるユーザーを常に監視し、定期的に API キーを再生成してください。