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

注

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

Azure AI 検索では、Microsoft Entra IDによるロールベースのアクセス制御がサポートされます。ロールベースのアクセスは省略可能ですが、推奨されます。代替策としてはキーベースの認証があり、こちらは既定のものです。

セキュリティプリンシパルに複数のロールを割り当てると、アクセス許可が組み合わされます。ロールの割り当ては、すべてのツールとクライアントライブラリに適用されます。

この記事では、サービス管理、開発、読み取り専用のクエリおよび取得アクセス用の組み込みロールを割り当てる方法について説明します。また、カスタムロールを作成し、ロールの割り当てをテストする手順も示します。

ヒント

組み込みロールの概要を簡単に確認したい場合アクセス許可の概要を参照してください。
ドキュメントレベル (行レベルのセキュリティとも呼ばれます) で検索結果へのアクセスを制御するには、Azure AI 検索の Document レベルのアクセス制御を参照してください。

前提条件

ロールベースアクセスが有効な Azure AI 検索サービス (任意のリージョンと任意の層)。
Azureロールを割り当てる権限。次のいずれのロールでも動作します。
- Owner
- ユーザーアクセス管理者
- ロールベースのアクセス制御管理者
- Microsoft.Authorization/roleAssignments/write 権限を持つカスタムロール
優先クライアントのロールの割り当て手順を確認します。
使用するクライアントで必要な担当者の値を特定してください。クライアントと割り当て先の種類によっては、この値はユーザープリンシパル名、グループオブジェクト ID、サービスプリンシパル名、サービスプリンシパルアプリケーション ID、またはMicrosoft Entra オブジェクト ID です。

組み込みロール

ロールは、コントロールプレーンまたはデータプレーンに影響を与えるアクセス許可のコレクションです。

コントロールプレーン: サービスのプロビジョニング、構成、および管理のための操作。コントロールプレーン操作には、検索サービスの作成または削除、API キーの一覧表示、ネットワークと認証の設定の管理が含まれます。 Azure Resource Manager REST API、Search Management REST API、および同等のAzure SDK クライアントライブラリを通じて使用できます。
データプレーン: 検索サービスエンドポイントに対する操作。データプレーン操作は、オブジェクト管理とコンテンツアクセスの 2 つのカテゴリに分類されます。 Search Service REST API および同等のAzure SDK クライアントライブラリを介して使用できます。

ロールの説明

次の組み込みロールは、Azure AI 検索へのアクセス許可を付与します。コントロールプレーンロールは常に使用できますが、データプレーンロールでは、検索サービスでロールベースのアクセスを有効にする必要があります。組み込みのロールを組み合わせて幅広いアクセスを行ったり、必要な特定のアクセス許可を持つカスタムロールを作成したりできます。

Role	プレーン	説明
所有者	制御	ロールを割り当て、認証設定を変更する機能を含む、フルコントロールプレーンアクセス。サブスクリプション管理者には、既定でこのロールがあります。 API キーを管理できます。検索オブジェクトの作成、ドキュメントの読み込み、インデックスのクエリ、ナレッジベースからの取得はできません。
投稿者	制御	所有者と同等のコントロールプレーンアクセスを持ちつつ、ロールを割り当てる権限がないレベル。
閲覧者	制御	読み取り専用コントロールプレーンアクセス。サービスメトリックとオブジェクト定義を表示できます。 API キーの表示や管理、ドキュメントの読み込み、インデックスのクエリ、ナレッジベースからの取得はできません。
Search Service サービス貢献者	コントロールとデータ	フルコントロールプレーンへのアクセス。データプレーンへのアクセスは、オブジェクト管理に限定されます。インデックス、インデクサー、スキルセット、ナレッジベース、およびその他の検索オブジェクトを作成できます。コントロールプレーン操作を使用して、管理者キーとクエリ API キーを取得できます。ロールベースのアクセスを通じて、ドキュメントの読み込み、インデックスのクエリ、ナレッジベースからの取得を直接行うことはできません。完全なアクセス許可の一覧については、「`Microsoft.Search/searchServices/*`」を参照してください。
検索インデックスデータ共同作成者	Data	読み取りおよび書き込みのコンテンツアクセス。ドキュメントの読み込み、インデックスのクエリ、ナレッジベースからの取得を行うことができます。オブジェクト定義を変更したり、管理者キーを取得したりすることはできません。
検索インデックスデータ閲覧者	Data	コンテンツの読み取り専用アクセスインデックスのクエリを実行し、ナレッジベースから取得できます。ドキュメントの読み込み、オブジェクト定義の変更、管理者キーの取得はできません。

重要

所有者、共同作成者、および Search Service 共同作成者は、データプレーンへの完全な読み取り/書き込みアクセスを提供する管理者キーを取得できます。これらのロールを信頼されたユーザーにのみ付与します。
既定では、データプレーンロールは検索サービスのすべてのインデックスに適用されます。検索インデックスデータ共同作成者または検索インデックスデータ閲覧者のスコープを 1 つのインデックスに設定するには、「1 つのインデックスへのアクセスを許可する」を参照してください。

アクセス許可の概要

次の表を使用して、必要なアクセス許可を提供するロールをすばやく見つけます。

アクセス許可	所有者/共同作成者	閲覧者	検索サービス寄稿者	検索インデックスデータ共同作成者	検索インデックスデータ閲覧者
Azure AI 検索サービスの作成と構成	✅	❌	✅	❌	❌
Azure ポータルでサービスにアクセスする	✅	✅	✅	❌	❌
サービスのプロパティ、メトリック、エンドポイントを表示する	✅	✅	✅	❌	❌
サービス上のすべてのオブジェクトを一覧表示する	✅	✅	✅	❌	❌
クォータとサービス統計情報にアクセスする	✅	❌	✅	❌	❌
キーを表示、コピー、再生成する	✅	❌	✅	❌	❌
認証オプションを設定する	✅	❌	✅	❌	❌
ロール、ポリシー、および定義を表示する	✅	✅	✅	❌	❌
ネットワークセキュリティとプライベート接続を構成する	✅	❌	✅	❌	❌
検索オブジェクトの作成、実行、管理 ¹	❌	❌	✅	❌	❌
インデックス作成用のデータをアップロードする ²	❌	❌	❌	✅	❌
インデックスのクエリ	❌	❌	❌	✅	✅
ナレッジベースから取得する	❌	❌	❌	✅	✅
権限昇格された読み取りを使用してアクセス許可フィルターをバイパスする	❌	❌	❌	✅	❌

¹ インデックス、インデクサー、データソース、スキルセット、エイリアス、シノニムマップ、デバッグセッション、ナレッジベース、ナレッジソースが含まれます。インデクサーでは、実行操作とリセット操作もサポートされます。

² 所有者または共同作成者は、他のクライアントでドキュメントをアップロードできない場合でも、 データのインポート ウィザードを実行してインデックスを作成および読み込むことができます。同様に、インデクサーは、インデックスごとのロールの割り当てに関係なく、検索サービス上の任意のインデックスに書き込むことができます。どちらの場合も、(ユーザーではなく) 検索サービスは、Microsoft.Search/searchServices/indexes/documents/* アクセス許可を使用してデータプレーンアクションを実行します。

組み込みロールを割り当てる

このセクションでは、次のロールを割り当てます。

サービス管理
発達
読み取り専用アクセス

サービス管理のロールを割り当てる

次のロールを使用すると、検索サービスを作成、構成、管理できます。これらのロールは階層構造であるため、必要なアクセスレベルに基づいて 1 つ選択します。

Role	ID
所有者	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
投稿者	b24988ac-6180-42a0-ab88-20f7382dd24c
閲覧者	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure ポータルで検索サービスに移動します。
左側のウィンドウで、Access control (IAM) を選択します。
[+ 追加]>[ロール割り当ての追加] の順に選択します。
ロール ( 所有者、 共同作成者、閲覧者) を選択 します。
Members タブで、Microsoft Entraユーザーまたはグループ ID を選択します。別のAzure サービスのアクセス許可を設定する場合は、システム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択します。
[確認と割り当て] タブで、[確認と割り当て] を選択してロールを割り当てます。

Azure サブスクリプションにサインインします。
```
az login
```

検索サービスを対象としたロールの割り当てを作成します。担当者とスコープを指定します。

az role assignment create \
    --assignee <assignee> \
    --role "Reader" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

リファレンス:az role assignment create

必要なモジュールをインポートし、Azure アカウントに接続します。
```
Import-Module Az.Resources
Connect-AzAccount
```

検索サービスを対象としたロールの割り当てを作成します。この例では、ユーザーのサインイン名を使用します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

参照：New-AzRoleAssignment

コマンドシェルを開き、Azure サブスクリプションにサインインします。
```
az login
```

Azure Resource Managerのアクセストークンを取得します。

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

PUT 要求を送信して、検索サービスをスコープとしたロールの割り当てを作成します。 principalTypeを、担当者と一致するようにUser、Group、またはServicePrincipalに設定します。

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/acdd72a7-3385-48ef-bd42-f606fba81ae7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

リファレンス:ロールの割り当て - 作成

開発用のロールを割り当てる

次のロールを使用すると、検索オブジェクトの作成、ドキュメントの読み込み、インデックスのクエリ、ナレッジベースからの取得を行うことができます。 3 つのロールをすべて割り当てて、さまざまな開発タスクに対応します。

Role	ID
Search Service サービス貢献者	7ca78c08-252a-4471-8644-bb5ff32d4ba0
検索インデックスデータ共同作成者	8ebe5a00-799e-43f5-93ac-243d3dce84a7
検索インデックスデータ閲覧者	1407120a-92aa-4202-b7e9-c0e197c71c8f

Azure ポータルで検索サービスに移動します。
左側のウィンドウで、Access control (IAM) を選択します。
[+ 追加]>[ロール割り当ての追加] の順に選択します。
[Search Service Contributor]\(Search Service 共同作成者\) を選択します。
Members タブで、Microsoft Entraユーザーまたはグループ ID を選択します。別のAzure サービスのアクセス許可を設定する場合は、システム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択します。
[確認と割り当て] タブで、[確認と割り当て] を選択してロールを割り当てます。
検索インデックスデータ共同作成者と検索インデックスデータ閲覧者を割り当てるには、次の手順を繰り返します。

Azure サブスクリプションにサインインします。
```
az login
```

検索サービスを対象としたロールの割り当てを作成します。担当者とスコープを指定します。

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Contributor" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

リファレンス:az role assignment create

(省略可能)インデックスをスコープとしたロールの割り当てを作成します。担当者とスコープを指定します。

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Contributor" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

リファレンス:az role assignment create

必要なモジュールをインポートし、Azure アカウントに接続します。
```
Import-Module Az.Resources
Connect-AzAccount
```

検索サービスを対象としたロールの割り当てを作成します。この例では、ユーザーのサインイン名を使用します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

参照：New-AzRoleAssignment

(省略可能)インデックスをスコープとしたロールの割り当てを作成します。この例では、ユーザーのサインイン名を使用します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

参照：New-AzRoleAssignment

コマンドシェルを開き、Azure サブスクリプションにサインインします。
```
az login
```

Azure Resource Managerのアクセストークンを取得します。

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

リファレンス:ロールの割り当て - 作成

(省略可能)インデックスをスコープとしたロールの割り当てを作成する PUT 要求を送信します。

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

リファレンス:ロールの割り当て - 作成

読み取り専用アクセスのロールを割り当てる

インデックスとナレッジベースへの読み取りアクセスのみが必要なアプリとプロセスには、次のロールを使用します。サポートされている操作には、インデックスの検索、検索、オートコンプリート、検索候補、ナレッジベースの取得などがあります。

Role	ID
検索インデックスデータ閲覧者	1407120a-92aa-4202-b7e9-c0e197c71c8f

Azure ポータルで検索サービスに移動します。
左側のウィンドウで、Access control (IAM) を選択します。
[+ 追加]>[ロール割り当ての追加] の順に選択します。
検索インデックスデータ閲覧者ロールを選択します。
Members タブで、Microsoft Entraユーザーまたはグループ ID を選択します。別のAzure サービスのアクセス許可を設定する場合は、システム割り当てマネージド ID またはユーザー割り当てマネージド ID を選択します。
[確認と割り当て] タブで、[確認と割り当て] を選択してロールを割り当てます。

Azure サブスクリプションにサインインします。
```
az login
```

検索サービスを対象としたロールの割り当てを作成します。担当者とスコープを指定します。

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Reader" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

リファレンス:az role assignment create

(省略可能)インデックスをスコープとしたロールの割り当てを作成します。担当者とスコープを指定します。

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Reader" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

リファレンス:az role assignment create

必要なモジュールをインポートし、Azure アカウントに接続します。
```
Import-Module Az.Resources
Connect-AzAccount
```

検索サービスを対象としたロールの割り当てを作成します。この例では、ユーザーのサインイン名を使用します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

参照：New-AzRoleAssignment

(省略可能)インデックスをスコープとしたロールの割り当てを作成します。この例では、ユーザーのサインイン名を使用します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

参照：New-AzRoleAssignment

コマンドシェルを開き、Azure サブスクリプションにサインインします。
```
az login
```

Azure Resource Managerのアクセストークンを取得します。

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

リファレンス:ロールの割り当て - 作成

(省略可能)インデックスをスコープとしたロールの割り当てを作成する PUT 要求を送信します。

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/1407120a-92aa-4202-b7e9-c0e197c71c8f",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

リファレンス:ロールの割り当て - 作成

ロールの割り当てをテストする

クライアントを使用して、ロールの割り当てをテストします。役割は累積的であることを覚えておいてください。リソース (検索サービス) レベルでサブスクリプションまたはリソースグループレベルをスコープとする継承されたロールを削除または拒否することはできません。

続行する前に、キーレス接続用にアプリケーションを構成し、ロールの割り当てを行います。

Azure ポータルで検索サービスに移動します。
左側のウィンドウで、[ 検索の管理>Indexes ] を選択して、インデックス関連のアクセス許可をテストします。
- Search Service 共同作成者は、検索オブジェクトを作成、変更、削除できますが、ドキュメントを読み込んだり、クエリを実行したりすることはできません。権限を確認するには、検索インデックスを作成します。
- Search インデックスデータ共同作成者は、ドキュメントを読み込むことができます。 Azure ポータルには、Import data ウィザードの外部にドキュメントの読み込みオプションはありませんが、reset を実行し、インデクサーを実行してドキュメントの読み込みアクセス許可を確認できます。
- 検索インデックスデータ閲覧者はインデックスに対してクエリを実行できます。権限を確認するには、Search エクスプローラーを使用します。クエリを送信して結果を表示することはできますが、インデックス定義を表示したり、インデックスを作成したりすることはできません。

この方法では、REST クライアント拡張機能を使用したVisual Studio Codeを想定しています。

Azure CLI用のコマンドシェルを開き、Azure サブスクリプションにサインインします。
```
az login
```

Azure AI 検索データプレーンのアクセストークンを取得します。

az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

これらの変数をVisual Studio Codeの新しいテキストファイルに貼り付けます。

@baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
@index-name = PASTE-YOUR-INDEX-NAME-HERE
@token = PASTE-YOUR-TOKEN-HERE

指定した変数を使用する要求を送信します。 Search Index Data Reader ロールでは、サポートされている任意の API バージョンを使用してクエリを送信できます。
```
POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2026-04-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}

{
    "queryType": "simple",
    "search": "motel",
    "filter": "",
    "select": "HotelName,Description,Category,Tags",
    "count": true
}
```
リファレンス:ドキュメントの検索

クエリが成功すると、一致するドキュメントを含む検索結果が返されます。インデックスが空の場合、または一致しない場合、 value には空の配列が含まれます。

ヒント

特定の環境のトークンを取得する方法の詳細については、「 REST API を使用してAzure AI 検索サービスを管理するおよびMicrosoft ID プラットフォーム認証ライブラリを参照してください。

必要なパッケージをインストールします。

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

.NET のトークン認証には、Azure.Identity を使用します。 Microsoftでは、ほとんどのシナリオで DefaultAzureCredential() をお勧めします。

DefaultAzureCredential() を使用したクライアント接続の例を次に示します。

// Create a SearchIndexClient to send create/delete index commands
// Requires Search Service Contributor role
SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());

// Create a SearchClient to load and query documents
// Requires Search Index Data Contributor (load) or Search Index Data Reader (query)
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());

Reference:SearchClient、 SearchIndexClient、 DefaultAzureCredential

クライアントシークレット資格情報を使用する別の例を次に示します。

var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);

クエリを実行する例を次に示します。

SearchResults<SearchDocument> response = srchclient.Search<SearchDocument>("motel");
foreach (SearchResult<SearchDocument> result in response.GetResults())
{
    Console.WriteLine(result.Document["HotelName"]);
}

クエリが成功すると、検索結果が返されます。一致するドキュメントがない場合、結果コレクションは空です。

必要なパッケージをインストールします。
```
pip install azure-search-documents azure-identity
```
Azure.Identity for Pythonを使用してトークン認証を行います。
Python クライアントがサーバー側を実行するアプリケーションの場合は、DefaultAzureCredential を使用します。アプリがブラウザーで実行している場合、対話型の認証を有効にします。

次に例を示します。

from azure.search.documents import SearchClient
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
endpoint = "https://<mysearch>.search.windows.net"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Reference:SearchClient、 DefaultAzureCredential

必要なパッケージをインストールします。
```
npm install @azure/search-documents @azure/identity
```
JavaScript 用のトークン認証には Azure.Identity を使用します。
React を使用している場合は、Azure AI 検索の Microsoft Entra 認証に InteractiveBrowserCredential を使用します。詳細については、「@azure/identityを使用するタイミング」を参照してください。

Reference:SearchClient、 DefaultAzureCredential

必要な依存関係を pom.xmlに追加します。

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-search-documents</artifactId>
  <version>11.7.4</version>
</dependency>
<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-identity</artifactId>
  <version>1.15.0</version>
</dependency>

Azure.Identity for Java を使用してトークン認証を行います。
Azureで実行されるアプリには、DefaultAzureCredential を使用します。

1 つのインデックスへのアクセスを許可する

シナリオの一部では、アプリケーションでアクセスできる範囲を単一のリソース (インデックスなど) に制限することが必要になる場合があります。

現在、Azure ポータルでは、インデックスレベルでのロールの割り当てはサポートされていません。 Azure CLI、PowerShell、または REST API を使用して、1 つのインデックスにスコープ付けされたロールを割り当てます。

Azure サブスクリプションにサインインします。
```
az login
```

1 つのインデックスをスコープとしたロールの割り当てを作成します。割り当て先とインデックスレベルのスコープを指定します。

az role assignment create \
    --assignee <assignee> \
    --role "Search Index Data Contributor" \
    --scope "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

リファレンス:az role assignment create

必要なモジュールをインポートし、Azure アカウントに接続します。
```
Import-Module Az.Resources
Connect-AzAccount
```

1 つのインデックスをスコープとしたロールの割り当てを作成します。この例では、ユーザーのサインイン名を使用します。

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

参照：New-AzRoleAssignment

コマンドシェルを開き、Azure サブスクリプションにサインインします。
```
az login
```

Azure Resource Managerのアクセストークンを取得します。

az account get-access-token --scope https://management.azure.com/.default --query accessToken --output tsv

PUT 要求を送信して、1 つのインデックスをスコープとしたロールの割り当てを作成します。 principalTypeを、担当者と一致するようにUser、Group、またはServicePrincipalに設定します。

PUT https://management.azure.com/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>/providers/Microsoft.Authorization/roleAssignments/<role-assignment-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleDefinitionId": "/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/8ebe5a00-799e-43f5-93ac-243d3dce84a7",
        "principalId": "<principal-object-id>",
        "principalType": "<principal-type>"
    }
}

リファレンス:ロールの割り当て - 作成

インデックスごとのスコープとインデクサーの操作

インデックスごとのロールの割り当ては、ユーザーまたはアプリケーションからのクエリやドキュメントのアップロードなどの直接 API 操作にのみ適用されます。インデクサーは、サービスレベルの資格情報で動作するため、インデックスごとのアクセス許可によって制限されません。

Search Service 共同作成者ロールを持つユーザーは、インデックスごとのロールの割り当てを持たないインデックスであっても、検索サービス上の任意のインデックスに書き込むインデクサーを作成できます。

インデックス間で厳密なデータ分離を行う場合は、次の方法を検討してください。

インデックスレベルの分離を必要とするチームまたはユーザーには、個別の検索サービスを使用します。
Search Service 共同作成者は、インデクサーを管理する管理者にのみ割り当てます。
ドキュメントレベルのアクセス制御とセキュリティフィルターを使用して、共有インデックス内のクエリ結果を制限します。

カスタムロールの作成

組み込みロールで適切なアクセス許可の組み合わせが提供されない場合は、必要な操作をサポートするカスタムロールを作成できます。

次の例では、 検索インデックスデータリーダー を複製し、名前でインデックスを一覧表示する機能を追加します。通常、検索サービスのインデックスを一覧表示することは管理者の権利とされています。

Azure ポータルにサインインし、検索サービスに移動します。
左側のウィンドウで、Access control (IAM) を選択します。
[ロール] タブで、検索インデックスデータ閲覧者 または他のロールを見つけ、省略記号 (...) を選択し、[複製] を選択します。
Basics タブで、"Search Index Data Explorer" などのカスタムロールの名前を入力し、Next を選択します。
[ アクセス許可 ] タブで、[ アクセス許可の追加] を選択します。
アクセス許可の追加 ウィンドウで、Microsoft Search タイルを選択します。
上部で [アクション] が選択されている状態で、次のアクセス許可を設定します。
- Microsoft.Search/operationsで、Read : 使用可能なすべての操作を一覧表示します を選択します。
- [Microsoft.Search/searchServices/indexes] で、[Read : Read Index] を選択します。

上部にある Data Actions に切り替え、Microsoft.Search/searchServices/indexes/documents で Read: Read Documents を選択します。

JSON の定義は、次の例のようになります。

{
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

[ 追加] を選択してペインを閉じます。
[確認および作成] を選択してロールを作成します。

これで、ユーザーとグループをロールに割り当てることがきるようになりました。これらの手順の詳細については、「Azure ポータルを使用してカスタムロールAzure作成または更新するを参照してください。

Azure CLIの例は、Search Index Data Reader の複製であるカスタムロールを作成するための JSON 構文を示していますが、名前ですべてのインデックスを一覧表示できます。カスタムロールの作成の詳細な手順については、「Azure CLIを使用してカスタムロールAzure作成または更新する」を参照してください。

アトミックアクセス許可の一覧を確認して、必要なものを判断します。この例では、次のアクセス許可が必要です。
```
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
```

次のロール定義を、 search-index-data-explorer.jsonという名前の JSON ファイルに保存します。 Idの場合は、生成する新しい GUID を指定します。

{
    "Name": "Search Index Data Explorer",
    "Id": "<role-definition-guid>",
    "IsCustom": true,
    "Description": "List all indexes on the service and query them.",
    "Actions": [
        "Microsoft.Search/operations/read",
        "Microsoft.Search/searchServices/indexes/read"
    ],
    "NotActions": [],
    "DataActions": [
        "Microsoft.Search/searchServices/indexes/documents/read"
    ],
    "NotDataActions": [],
    "AssignableScopes": [
        "/subscriptions/<subscription>/resourceGroups/<resource-group>"
    ]
}

JSON ファイルを az role definition createに渡して、カスタムロールを作成します。
```
az role definition create --role-definition @search-index-data-explorer.json
```
参考:az role definition create

PowerShell の例では、 検索インデックスデータ閲覧者の複製であるカスタムロールを作成するための JSON 構文を示しますが、名前ですべてのインデックスを一覧表示できます。カスタムロールの作成の詳細な手順については、「Azure PowerShellを使用してカスタムロールAzure作成または更新する」を参照してください。

アトミックアクセス許可の一覧を確認して、必要なものを判断します。この例では、次のアクセス許可が必要です。
```
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
```

次のロール定義を、 search-index-data-explorer.jsonという名前の JSON ファイルに保存します。 Idの場合は、生成する新しい GUID を指定します。

{
    "Name": "Search Index Data Explorer",
    "Id": "<role-definition-guid>",
    "IsCustom": true,
    "Description": "List all indexes on the service and query them.",
    "Actions": [
        "Microsoft.Search/operations/read",
        "Microsoft.Search/searchServices/indexes/read"
    ],
    "NotActions": [],
    "DataActions": [
        "Microsoft.Search/searchServices/indexes/documents/read"
    ],
    "NotDataActions": [],
    "AssignableScopes": [
        "/subscriptions/<subscription>/resourceGroups/<resource-group>"
    ]
}

JSON ファイルを New-AzRoleDefinitionに渡して、カスタムロールを作成します。
```
New-AzRoleDefinition -InputFile "search-index-data-explorer.json"
```
Reference:New-AzRoleDefinition

REST API の例は、 検索インデックスデータ閲覧者の複製であるカスタムロールを作成するための JSON 構文を示していますが、すべてのインデックスを名前で一覧表示できます。カスタムロールの作成の詳細な手順については、「REST API を使用してカスタムロールAzure作成または更新する」を参照してください。

アトミックアクセス許可の一覧を確認して、必要なものを判断します。この例では、次のアクセス許可が必要です。
```
"Microsoft.Search/operations/read",
"Microsoft.Search/searchServices/indexes/read",
"Microsoft.Search/searchServices/indexes/documents/read"
```

ロール定義エンドポイントに次の要求を送信して、カスタムロールを作成します。

PUT https://management.azure.com/subscriptions/<subscription>/providers/Microsoft.Authorization/roleDefinitions/<role-definition-guid>?api-version=2022-04-01 HTTP/1.1
Authorization: Bearer <access-token>
Content-Type: application/json

{
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "type": "CustomRole",
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ],
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ]
    }
}

リファレンス:ロール定義 - 作成または更新

条件付きアクセスポリシーを作成する

多要素認証などの組織のポリシーを適用する必要がある場合は、Microsoft Entra 条件付きアクセスを使用します。

Azure AI 検索の条件付きアクセスポリシーを作成するには:

Azure ポータルにサインインします。
Microsoft Entra 条件付きアクセスを検索します。
[ 概要 ] ページで、[ 新しいポリシーの作成] を選択します。
Cloud アプリまたはアクションで、ポリシーの設定方法に応じて、Azure AI 検索 をクラウドアプリとして追加します。
ポリシーの残りのパラメーターを更新します。たとえば、ポリシーを適用するユーザーとグループを指定します。
ポリシーを保存します。

重要

検索サービスにマネージド ID が割り当てられている場合、特定の検索サービスはクラウドアプリとして表示されます。ただし、その特定の検索サービスを選択しても、ポリシーは適用されません。代わりに、一般的な Azure AI 検索 クラウドアプリを選択して、条件付きアクセスポリシーを検索サービスに適用します。

Troubleshooting

認証にロールベースのアクセス制御を使用するアプリケーションを開発すると、いくつかの一般的な問題が発生する可能性があります。

Search Service の既定の構成は、キーベースの認証です。この設定を [両方 ] または [ ロールベースのアクセス制御] に変更しない場合、基になるアクセス許可に関係なく、ロールベースの認証を使用するすべての要求が自動的に拒否されます。
要求にロールベースの資格情報と共に API キーが含まれている場合、サービスはキーを使用して認証します。ロールベースの認証を使用するには、要求ヘッダーから API キーを削除します。
承認トークンがマネージド ID から取得され、適切なアクセス許可を最近割り当てた場合、アクセス許可の割り当てが有効になるには数時間かかる場合があります。
ドキュメントレベルのアクセス許可を持つクエリで期待される結果が返されない場合は、検索インデックスデータ共同作成者を使用するか、昇格されたアクセス許可を持つカスタムロールを作成して調査します。

次のステップ

この記事では、Azure AI 検索での制御およびデータプレーン操作のロールを割り当てる方法について説明します。ロールベースのアクセスをアプリケーションコードに追加する包括的な手順については、次の手順を実行します。

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

フィードバック

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

Last updated on 2026-07-28

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

前提条件

組み込みロール

ロールの説明

アクセス許可の概要

組み込みロールを割り当てる

サービス管理のロールを割り当てる

開発用のロールを割り当てる

読み取り専用アクセスのロールを割り当てる

ロールの割り当てをテストする

1 つのインデックスへのアクセスを許可する

インデックスごとのスコープとインデクサーの操作

カスタム ロールの作成

条件付きアクセス ポリシーを作成する

Troubleshooting

次のステップ

フィードバック

その他のリソース

カスタムロールの作成

条件付きアクセスポリシーを作成する