キーを使用して Azure AI 検索に接続する

Azure AI Search では、検索サービスへの接続に対して、ID ベースの認証とキーベースの認証の両方がサポートされています。 API キーは、ランダムに生成された 52 個の数字と文字から成る一意の文字列です。

ソースコードでは、要求ヘッダーで API キーを直接指定できます。または、環境変数またはアプリ設定としてプロジェクトに格納し、要求で変数を参照することもできます。

重要

検索サービスを作成する際には、キーベース認証が既定値となりますが、これが最も安全な選択肢というわけではありません。これをロールベースのアクセスに置き換えることをお勧めします。

既定で有効

キーベースの認証は、新しい検索サービスの既定です。検索サービスエンドポイントに対して行われた要求は、要求と API キーの両方が有効であり、検索サービスが要求で API キーを許可するように構成されている場合に受け入れられます。

Azure portal の [設定]>[キー]ページで認証を指定します。 API キーまたは両方のいずれかが、キーのサポートを提供します。

キーの種類

要求の認証には、次の 2 種類のキーが使用されます。

タイプ	アクセス許可レベル	作成方法	最大値
[Admin]	すべてのコンテンツ操作に対するフルアクセス (読み取り/書き込み)	Azure portal で "プライマリ" および "セカンダリ" キーと呼ばれる 2 つの管理者キーがサービスの作成時に生成され、必要に応じてそれらを個別に生成し直すことができます。	2 ¹
クエリ	検索インデックスのドキュメントコレクションを対象とした読み取り専用アクセス	サービスで 1 つのクエリキーが生成されます。検索サービス管理者は、さらに必要に応じて作成できます。	50

¹ 2 つあることで、サービスへの継続的なアクセスに 1 つのキーを使用している間に、もう 1 つのキーをロールオーバーできます。

管理者キーとクエリキーに見た目の違いはありません。どちらのキーも、ランダムに生成された 52 個の英数字からなる文字列です。アプリケーションで指定されているキーの種類がわからなくなった場合、Azure portal でキーの値を確認できます。

キーと役割のマッピング

この記事では、API キーについて説明します。ただし、ロールベースのアクセスに移行する場合は、 Azure AI Search の組み込みロールにキーがどのようにマップされるかを理解すると便利です。

管理キーは、 Search Service 共同作成者 ロールと 検索インデックスデータ共同作成者 ロールに対応します。
クエリキーは、 検索インデックスデータ閲覧者 ロールに対応します。

キーを表示または管理するためのアクセス許可

API キーを表示および管理するためのアクセス許可は、ロールの割り当てによって伝達されます。次のロールのメンバーは、キーの表示と再生成が可能です:

[所有者]
投稿者
Search Service サービス貢献者
管理者と共同管理者 (クラシック)

次のロールは API キーにアクセスできません。

閲覧者
検索インデックスデータ共同作成者
検索インデックスデータ閲覧者

既存のキーを見つける

API キーは、 Azure portal、 PowerShell、 Azure CLI、または REST API を使用して表示および管理できます。

Azure portal にサインインし、ご利用の検索サービスを探します。
左側のウィンドウで [設定]>[キー ]を選択して、管理者キーとクエリキーを表示します。

Az.Search モジュールをインストールします。
```
Install-Module Az.Search
```

管理者キーを返します。

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

クエリキーを返します。

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

管理者とクエリの API キーをそれぞれ返すには、次のコマンドを使用します。

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Management REST API で管理者キーの一覧表示またはクエリキーの一覧表示を使用して、API キーを返します。

API キーを取得または更新するには、有効なロールの割り当てが必要です。 REST API を使用したロール要件の満たすガイダンスについては、「 REST API を使用して Azure AI Search Serviceを管理する」を参照してください。

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01

接続でキーを使用する

API キーは、インデックスや Search Service REST API で表されるその他の要求の作成やアクセスなど、データプレーン (コンテンツ) 要求に使用されます。

コントロールプレーン (サービス) 要求には、API キーまたはロールを使用できます。 API キーを使用する場合:

管理キーは、オブジェクトの作成、変更、または削除に使用されます。管理キーは、 LIST インデックスや GET サービス統計などの GET オブジェクト定義とシステム情報にも使用されます。
通常、クエリを発行するクライアントアプリケーションにクエリキーが配布されます。

要求ヘッダーに管理者キーを設定します。 URI または要求の本文で管理者キーを渡すことはできません。

インデックス作成要求での管理者 API キーの使用方法の例を次に示します。

@baseUrl=https://my-demo-search-service.search.windows.net
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-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=2025-09-01&api-key={{queryApiKey}}

注

api-key などの機密データを要求 URI で渡すことは、セキュリティ上推奨されません。このため、Azure AI Search はクエリ文字列内の api-key としてクエリキーのみを受け入れます。一般的なルールとして、api-key は要求ヘッダーとして渡すことをお勧めします。

API キーを環境変数として設定することをお勧めしますが、わかりやすくするために、この例では文字列として表示します。この例では、クエリ操作にクエリ API キーを使用します。

# Import libraries
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.windows.net/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

次の構文を使用して、要求ヘッダーに API キーを設定します。

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

変数を使用して、完全修飾クエリを格納します。

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2025-09-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

検索サービスに要求を送信します。

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

その他の操作のスクリプト例については、「クイックスタート: REST API を使用して PowerShell で Azure AI Search インデックスを作成する」を参照してください。

クエリキーを作成する

クエリキーは、ドキュメントコレクションをターゲットとする操作のために、インデックス内のドキュメントへの読み取り専用アクセスに使用されます。検索、フィルター、および推奨クエリは、いずれもクエリキーを取得する操作です。インデックス定義やインデクサーの状態など、システムデータまたはオブジェクト定義を返す読み取り専用操作には、管理者キーが必要です。

クライアントアプリでアクセスと操作を制限することは、サービスで検索アセットを保護するために不可欠です。クライアントアプリから発信されたクエリには、常に管理者キーではなくクエリキーを使用します。

Azure portal にサインインし、ご利用の検索サービスを探します。
左側のウィンドウで、[設定]>[キー] を選択して API キーを表示します。
[クエリキーの管理] で、サービス用に既に生成されているクエリキーを使用するか、新しいクエリキーを作成します。既定のクエリキーには名前はありませんが、生成された他のクエリキーには、管理を容易にするために名前を付けることができます。

Management REST API のクエリキーの作成を使用します。

API キーを作成または管理するには、有効なロールの割り当てが必要です。 REST API を使用したロール要件の満たすガイダンスについては、「 REST API を使用して Azure AI Search Serviceを管理する」を参照してください。

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2025-05-01

管理者キーを再生成する

ビジネス継続性のためにセカンダリキーを使用しているときに、プライマリキーをローテーションできるように、サービスごとに 2 つの管理者キーが作成されます。

Azure portal にサインインし、ご利用の検索サービスを探します。
次に、左側のペインで [設定]>[キー] を選択します。
セカンダリキーをコピーします。
すべてのアプリケーションについて、セカンダリキーを使用するように API キーの設定を更新します。
プライマリキーを再生成します。
新しいプライマリキーを使用するように、すべてのアプリケーションを更新します。

誤って両方のキーを同時に再生成すると、それらのキーを使用するすべてのクライアント要求が HTTP 403 Forbidden で失敗します。ただし、コンテンツは削除されず、永続的にロックアウトされることはありません。

引き続き、Azure portal またはプログラムを使ってサービスにアクセスできます。管理機能は、サービス API キーではなくサブスクリプション ID を使用して操作するため、自分の API キーがない場合でも使用できます。

ポータルまたは管理レイヤーを介して新しいキーを作成した後に、要求時にそのキーを指定すると、アクセスがコンテンツ (インデックス、インデクサー、データソース、シノニムマップ) に復元されます。

セキュリティで保護されたキー

ロールの割り当てを使用して、API キーへのアクセスを制限します。

カスタマーマネージドキー暗号化を使用して API キーを暗号化することはできません。 CMK で暗号化できるのは、検索サービス自体内の機密データ (データソースオブジェクト定義のインデックスコンテンツや接続文字列など) のみです。

Azure portal にサインインし、ご利用の検索サービスを探します。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択し、[ロールの 割り当て ] タブを選択します。
[ロール] フィルターで、キーを表示または管理するアクセス許可を持つロール (所有者、共同作成者、Search Service 共同作成者) を選択します。これらのロールに割り当てられた結果のセキュリティプリンシパルは、検索サービスに対するキーのアクセス許可を持ちます。
予防措置として、[クラシック管理者] タブを確認して、管理者と共同管理者がアクセス権を持っているかどうかを確認します。

ベストプラクティス

運用ワークロードの場合、Microsoft Entra ID とロールベースのアクセスに切り替えます。また、API キーを引き続き使用する場合は、API キーにアクセスできるユーザーを常に監視し、定期的に API キーを再生成してください。
データ漏えいのリスクがない (サンプルデータを使用する場合など) 場合や、ファイアウォールの背後で操作している場合にのみ、API キーを使用します。 API キーを公開すると、データと検索サービスの両方が不正使用のリスクにさらされます。
API キーを使用する場合は、それを Azure Key Vault などの別の場所に安全に保存します。 API キーは、コード内に直接含めないようにし、絶対に公開しないでください。
コード、サンプル、トレーニング資料は公開前に必ず確認し、API キーを誤って公開しないようにしてください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-02