ID を使用してアプリをAzure AI 検索に接続する

Note

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

アプリケーションコードでは、認証と承認にMicrosoft Entra IDとロールを使用するAzure AI 検索へのキーレス接続を設定できます。ほとんどのAzure サービスに対するアプリケーション要求は、キーまたはキーレス接続で認証する必要があります。開発者は、安全でない場所にアクセス・キーを公開しないよう注意する必要があります。このキーへのアクセス権を取得したユーザーは誰でもサービスの認証を受けることができます。キーレス認証では、保存するキー (または接続文字列) がないため、アカウントキーよりも管理とセキュリティの利点が向上します。

この記事では、アプリケーションコードで DefaultAzureCredential を使用する方法について説明します。

コードにキーレス接続を実装するには、次の手順に従います。

検索サービスに対するロールベースのアクセスを有効にする
必要に応じて、環境変数を設定します。
Azure AI 検索クライアントオブジェクトを作成するには、Azure ID ライブラリの資格情報の種類を使用します。

[前提条件]

Azure AI 検索、どのリージョンでも課金対象レベル (Basic 以上) である必要があります。
検索サービスでロールベースのアクセスが有効になっています。
Azure AI 検索でのロールの割り当て。 ID に次のロールを割り当てます。
- ローカル開発用検索サービスの共同作成者と検索インデックスデータの共同作成者（フルアクセス）
- 運用用読み取り専用クエリの検索インデックスデータリーダー
詳細な手順については、「開発のためのロールの割り当て」を参照してください。

Azure Identity クライアントライブラリをインストールする

キーレスアプローチを使用するには、AI Search 対応コードを Azure Identity クライアントライブラリで更新します。

.NETAzure ID クライアントライブラリと> Azure Search Documents クライアントライブラリをインストールします。

dotnet add package Azure.Identity
dotnet add package Azure.Search.Documents

Java 用 Azure Identity クライアントライブラリと Azure Search Documents クライアントライブラリを、次の POM ファイルを使用してインストールします。

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.15.1</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.0</version>
        </dependency>
    </dependencies>
</dependencyManagement>

JavaScript 用の Azure Id クライアントライブラリと Azure Search Documents クライアントライブラリをインストールします。

npm install --save @azure/identity @azure/search-documents

PythonAzure ID クライアントライブラリと >Azure Search Documents クライアントライブラリをインストールします。

pip install azure-identity azure-search-documents

DefaultAzureCredential を使用するようにソースコードを更新する

Azure ID ライブラリの DefaultAzureCredential を使用すると、ローカル開発環境とAzure クラウドで同じコードを実行できます。 1 つの資格情報を作成し、必要に応じてその資格情報インスタンスを再利用して、トークンのキャッシュを利用します。

.NETのDefaultAzureCredentialの詳細については、「Azure Identity クライアントライブラリ for .NET」を参照してください。

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;
using System;
using static System.Environment;

string endpoint = GetEnvironmentVariable("AZURE_SEARCH_ENDPOINT");
string indexName = "my-search-index";

DefaultAzureCredential credential = new();
SearchClient searchClient = new(new Uri(endpoint), indexName, credential);
SearchIndexClient searchIndexClient = new(endpoint, credential);

Reference:SearchClient、 SearchIndexClient、 DefaultAzureCredential

JavaのDefaultAzureCredentialに関する詳細は、「Azure Identity クライアントライブラリ for Java」を参照してください。

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.search.documents.SearchAsyncClient;
import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.indexes.SearchIndexAsyncClient;
import com.azure.search.documents.indexes.SearchIndexClientBuilder;

String ENDPOINT = System.getenv("AZURE_SEARCH_ENDPOINT");
String INDEX_NAME = "my-index";

DefaultAzureCredential credential = new DefaultAzureCredentialBuilder().build();

// Sync SearchClient
SearchClient searchClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildClient();

// Sync IndexClient
SearchIndexClient searchIndexClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildClient();

// Async SearchClient
SearchAsyncClient searchAsyncClient = new SearchClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .indexName(INDEX_NAME)
    .buildAsyncClient();

// Async IndexClient
SearchIndexAsyncClient searchIndexAsyncClient = new SearchIndexClientBuilder()
    .endpoint(ENDPOINT)
    .credential(credential)
    .buildAsyncClient();

Reference:SearchClient、 SearchIndexClient、 DefaultAzureCredential

JavaScript の DefaultAzureCredential の詳細については、「Azure JavaScript の ID クライアントライブラリを参照してください。

import { DefaultAzureCredential } from "@azure/identity";
import {
  SearchClient,
  SearchIndexClient
} from "@azure/search-documents";

const AZURE_SEARCH_ENDPOINT = process.env.AZURE_SEARCH_ENDPOINT;
const index = "my-index";
const credential = new DefaultAzureCredential();

// To query and manipulate documents
const searchClient = new SearchClient(
  AZURE_SEARCH_ENDPOINT,
  index,
  credential
);

// To manage indexes and synonymmaps
const indexClient = new SearchIndexClient(
  AZURE_SEARCH_ENDPOINT, 
  credential
);

Reference:SearchClient、 SearchIndexClient、 DefaultAzureCredential

PythonのDefaultAzureCredentialの詳細については、Python 用 Azure Identity クライアントライブラリを参照してください。

import os
from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Azure Public Cloud
audience = "https://search.azure.com"
authority = AzureAuthorityHosts.AZURE_PUBLIC_CLOUD

service_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
index_name = os.environ["AZURE_SEARCH_INDEX_NAME"]
credential = DefaultAzureCredential(authority=authority)

search_client = SearchClient(
    endpoint=service_endpoint, 
    index_name=index_name, 
    credential=credential, 
    audience=audience)

search_index_client = SearchIndexClient(
    endpoint=service_endpoint, 
    credential=credential, 
    audience=audience)

Reference:SearchClient、 SearchIndexClient、 DefaultAzureCredential

接続を確認する

クライアントを設定した後、簡単な操作を実行して接続を確認します。次の例では、検索サービスのインデックスを一覧表示します。

// List indexes to verify connection
var indexes = searchIndexClient.GetIndexNames();
foreach (var name in indexes)
{
    Console.WriteLine(name);
}

// List indexes to verify connection
searchIndexClient.listIndexNames().forEach(System.out::println);

// List indexes to verify connection
for await (const name of indexClient.listIndexesNames()) {
  console.log(name);
}

# List indexes to verify connection
for index in search_index_client.list_index_names():
    print(index)

接続が成功すると、インデックスの名前が出力されます (インデックスが存在しない場合は空のリスト)。認証エラーが発生した場合は、ロールベースのアクセスが有効になっており、ID に必要なロールの割り当てがあることを確認します。

既定の機関はパブリッククラウドAzure。ソブリンクラウドまたは特殊クラウド向けのカスタム audience 値は次のとおりです。

Azure Government の場合の https://search.azure.us
21Vianet 運営による https://search.azure.cn
Azure Germany の場合の https://search.microsoftazure.de

ローカル開発

ロールを使用したローカル開発には、次の手順が含まれます。

特定のリソースで RBAC ロールに個人 ID を割り当てます。
Azureで認証するには、Azure CLIやAzure PowerShellなどのツールを使用します。
リソースの環境変数を設定します。

ローカル開発のロール

ローカル開発者は、Azure ID でデータプレーン操作を完全に制御する必要があります。推奨されるロールは次のとおりです。

Search Service 共同作成者、オブジェクトの作成と管理
インデックスデータ共同作成者の検索、インデックスの読み込みとクエリの実行、ナレッジベースからの取得

次のツールのいずれかを使用して、個人の ID を確認します。その ID を <identity-id> 値として使用します。

プレースホルダー <role-name>、 <identity-id>、 <subscription-id>、および <resource-group-name> を、次のコマンドの実際の値に置き換えます。

Azure CLIにサインインします。
```
az login
```
認証用のブラウザーウィンドウが開きます。サインインに成功すると、ターミナルにサブスクリプション情報が表示されます。
個人の ID を取得します。
```
az ad signed-in-user show \
    --query id -o tsv
```
このコマンドは、ユーザーオブジェクト ID (GUID) を返します。次の手順で使用するため、この値を保存します。
リソースグループの ID にロールベースのアクセス制御 (RBAC) ロールを割り当てます。
```
az role assignment create \
    --role "<role-name>" \
    --assignee "<identity-id>" \
    --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
```
割り当てが成功すると、ロールの割り当ての詳細を含む JSON オブジェクトが返されます。

プレースホルダー <role-name>、 <identity-id>、 <subscription-id>、および <resource-group-name> を、次のコマンドの実際の値に置き換えます。

PowerShell を使用してサインインします。
```
Connect-AzAccount
```
認証用のブラウザーウィンドウが開きます。サインインに成功すると、ターミナルにアカウントとサブスクリプションの情報が表示されます。
個人の ID を取得します。
```
(Get-AzContext).Account.ExtendedProperties.HomeAccountId.Split('.')[0]
```
このコマンドは、ユーザーオブジェクト ID (GUID) を返します。次の手順で使用するため、この値を保存します。
リソースグループの ID にロールベースのアクセス制御 (RBAC) ロールを割り当てます。
```
New-AzRoleAssignment -ObjectId "<identity-id>" -RoleDefinitionName "<role-name>" -Scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>"
```
割り当てが成功すると、ロールの割り当てオブジェクトと、 RoleAssignmentIdなどの詳細が返されます。

ローカル開発の認証

ローカル開発環境のツールを使用して Azure ID に対する認証を行います。認証が完了すると、ソースコードの DefaultAzureCredential インスタンスが ID を検索し、認証のために使用します。

ローカル開発時に認証用のツールを選択します。

ローカル開発の環境変数を構成する

Azure AI 検索に接続するには、コードがリソースエンドポイントを認識している必要があります。

Azure AI 検索エンドポイントの AZURE_SEARCH_ENDPOINT という名前の環境変数を作成します。通常、この URL の形式は https://<YOUR-RESOURCE-NAME>.search.windows.net/ です。

運用ワークロード

運用ワークロードのデプロイには次の手順が含まれます。

最小限の特権の原則に従う RBAC ロールを選択します。
特定のリソース上の運用 ID に RBAC ロールを割り当てます。
リソースの環境変数を設定します。

運用ワークロードのロール

運用リソースを作成するには、ユーザー割り当てマネージド ID を作成し、その ID を正しいロールを持つリソースに割り当てる必要があります。

運用アプリケーションには次のロールが推奨されます。

役割名	ID (アイディー)
検索インデックスデータ閲覧者	1407120a-92aa-4202-b7e9-c0e197c71c8f

運用ワークロードの認証

次の Azure AI 検索 Bicep テンプレート を使用してリソースを作成し、identityId の認証を設定します。 Bicepにはロール ID が必要です。この Bicep スニペットに示されている name は Azure ロールではありません。これは Bicep デプロイに固有です。

// main.bicep
param environment string = 'production'
param roleGuid string = ''

module aiSearchRoleUser 'core/security/role.bicep' = {
    scope: aiSearchResourceGroup
    name: 'aiSearch-role-user'
    params: {
        principalId: (environment == 'development') ? principalId : userAssignedManagedIdentity.properties.principalId 
        principalType: (environment == 'development') ? 'User' : 'ServicePrincipal'
        roleDefinitionId: roleGuid
    }
}

main.bicep ファイルは、次の汎用Bicep コードを呼び出して、任意のロールを作成します。ユーザー用と運用用など、複数の RBAC ロールを作成することもできます。これにより、同じBicepデプロイ内で開発環境と運用環境の両方を有効にすることができます。

// core/security/role.bicep
metadata description = 'Creates a role assignment for an identity.'
param principalId string // passed in from main.bicep

@allowed([
    'Device'
    'ForeignGroup'
    'Group'
    'ServicePrincipal'
    'User'
])
param principalType string = 'ServicePrincipal'
param roleDefinitionId string // Role ID

resource role 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
    name: guid(subscription().id, resourceGroup().id, principalId, roleDefinitionId)
    properties: {
        principalId: principalId
        principalType: principalType
        roleDefinitionId: resourceId('Microsoft.Authorization/roleDefinitions', roleDefinitionId)
    }
}

運用ワークロードの環境変数を構成する

Azure AI 検索に接続するには、コードでリソースエンドポイントとマネージド ID の ID を認識する必要があります。

デプロイされたキーレス Azure AI 検索リソースの環境変数を作成します。

AZURE_SEARCH_ENDPOINT: この URL は、Azure AI 検索リソースのアクセスポイントです。通常、この URL の形式は https://<YOUR-RESOURCE-NAME>.search.windows.net/ です。
AZURE_CLIENT_ID: これは認証する ID です。

一般的なエラーのトラブルシューティング

エラー	原因	解決策
`AuthenticationFailedException`	資格情報が無効または見つからない	`az login` (CLI) または `Connect-AzAccount` (PowerShell) でサインインしていることを確認します。 Azure アカウントにサブスクリプションへのアクセス権があることを確認します。
`403 Forbidden`	ID に必要なロールがない	適切なロールを割り当てます (クエリのインデックスデータ閲覧者の検索、インデックス作成のためのインデックスデータ共同作成者の検索)。ロールの割り当てが反映されるまでに最大 10 分かかることがあります。
`401 Unauthorized`	検索サービスで RBAC が有効になっていない	Azure ポータルの Settings>Keys>Role ベースのアクセス制御でロールベースのアクセスを有効にします。
`ResourceNotFoundException`	無効なエンドポイントまたはインデックス名	`AZURE_SEARCH_ENDPOINT`環境変数が検索サービスの URL (形式: `https://<service-name>.search.windows.net`) と一致するかどうかを確認します。
`CredentialUnavailableException`	有効な資格情報が見つかりません	`DefaultAzureCredential` は、複数の認証方法を試みます。少なくとも 1 つが構成されていることを確認します (Azure CLI、Visual Studio、環境変数)。

フィードバック

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

Last updated on 2026-04-07

ID を使用してアプリをAzure AI 検索に接続する

[前提条件]

Azure Identity クライアント ライブラリをインストールする

DefaultAzureCredential を使用するようにソース コードを更新する

接続を確認する

ローカル開発

ローカル開発のロール

ローカル開発の認証

ローカル開発の環境変数を構成する

運用ワークロード

運用ワークロードのロール

運用ワークロードの認証

運用ワークロードの環境変数を構成する

一般的なエラーのトラブルシューティング

関連コンテンツ

フィードバック

その他のリソース

Azure Identity クライアントライブラリをインストールする

DefaultAzureCredential を使用するようにソースコードを更新する