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

1. Azure portal にサインインします。

2. 左側のウィンドウで [アクセス制御 (IAM)] を選択します。

3. [+ 追加]>[ロールの割り当ての追加] を選択して [ロールの割り当ての追加] ウィザードを起動します。

   

4. ロールを選択します。

   • 所有者 (クエリのアクセス許可を除く、すべてのデータ プレーン操作とコントロール プレーン操作へのフル アクセス)
   • 共同作成者 (ロールを割り当てるアクセス許可を除き、所有者と同じ)
   • 閲覧者 (メトリックの監視と表示に使用可能)

5. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。 別の Azure サービスのアクセス許可を設定する場合は、システムまたはユーザー マネージド ID を選択します。

6. [確認と 割り当て] タブで、[確認と割り当て] を選択して ロールを割り当てます。

PowerShell を使用してロールを割り当てる場合は、New-AzRoleAssignment を呼び出して、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

この例では、検索サービスにスコープを設定したロールの割り当てを作成します。

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

参照：New-AzRoleAssignment

1. Azure portal にサインインします。

2. 左側のウィンドウで [アクセス制御 (IAM)] を選択します。

3. [+ 追加]>[ロールの割り当ての追加] を選択して [ロールの割り当ての追加] ウィザードを起動します。

   

4. ロールを選択します。

   • Search Service 共同作成者 (インデックス、インデクサー、スキルセット、およびその他の最上位オブジェクトに対する作成、読み取り、更新、および削除操作)
   • Search インデックス データ共同作成者 (ドキュメントの読み込みとインデックス作成ジョブの実行)
   • 検索インデックス データ閲覧者 (インデックスのクエリ)

5. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。 別の Azure サービスのアクセス許可を設定する場合は、システムまたはユーザー マネージド ID を選択します。

6. [確認と 割り当て] タブで、[確認と割り当て] を選択して ロールを割り当てます。

PowerShell を使用してロールを割り当てる場合は、New-AzRoleAssignment を呼び出して、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

この例では、検索サービスにスコープを設定したロールの割り当てを作成します。

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

この例では、特定のインデックスにスコープを設定したロールの割り当てを作成します。

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

Reference:New-AzRoleAssignment

1. Azure portal にサインインします。

2. 左側のウィンドウで [アクセス制御 (IAM)] を選択します。

3. [+ 追加]>[ロールの割り当ての追加] を選択して [ロールの割り当ての追加] ウィザードを起動します。

   

4. 検索インデックス データ閲覧者ロールを選択します。

5. [メンバー] タブで Microsoft Entra ユーザーまたはグループの ID を選びます。 別の Azure サービスのアクセス許可を設定する場合は、システムまたはユーザー マネージド ID を選択します。

6. [確認と 割り当て] タブで、[確認と割り当て] を選択して ロールを割り当てます。

PowerShell を使用してロールを割り当てる場合は、New-AzRoleAssignment を呼び出して、Azure のユーザーまたはグループの名前と、割り当てのスコープを指定します。

1. サブスクリプション ID、Search Service リソース グループ、Search Service 名を取得します。

2. Azure OpenAI などの Azure サービスのオブジェクト識別子を取得します。

    Get-AzADServicePrincipal -SearchString <your-azure-openai-resource-name>
   

   出力には、ロールの割り当てに必要なオブジェクト ID を含む Id プロパティが含まれます。

3. ロール定義を取得し、アクセス許可を確認して、これが目的のロールであることを確認します。

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. プレースホルダーを有効な値で置き換えて、ロールの割り当てを作成します。

   New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>
   

   割り当てが成功すると、 RoleAssignmentIdを含むロールの割り当ての詳細が返されます。

5. 特定のインデックスにスコープを設定したロールの割り当ての例を次に示します。

   New-AzRoleAssignment -ObjectId <your-azure-openai-object-id> `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/<your-subscription-id>/resourcegroups/<your-resource-group>/providers/Microsoft.Search/searchServices/<your-search-service-name>/indexes/<your-index-name>
   

   参照:New-AzRoleAssignment

1. Azure portal にサインインします。

2. お使いの検索サービスに移動します。

3. [概要] ページで、[インデックス] タブを選択します。

   • Search サービス共同作成者は、任意のオブジェクトを表示および作成できますが、ドキュメントを読み込んだり、インデックスに対してクエリを実行したりすることはできません。 権限を確認するには、検索インデックスを作成します。

   • Search インデックス データ共同作成者は、ドキュメントを読み込むことができます。 Azure portal では [データのインポート] ウィザードの外部には [ドキュメントの読み込み] オプションはありませんが、[インデクサーのリセットと実行] を行うことでドキュメントの読み込みアクセス許可を確認できます。

   • 検索インデックス データ閲覧者は、インデックスに対してクエリを実行できます。 権限を確認するには、Search エクスプローラーを使用します。 クエリを送信し、結果を表示できるようにする必要がありますが、インデックス定義を表示できたり、作成できたりする必要はありません。

この方法では、VISUAL Studio Code と REST クライアント拡張機能を前提としています。

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

   az login
   

2. テナント ID とサブスクリプション ID を取得します。 この ID は、今後の手順で変数として使用します。

   az account show
   

3. アクセス トークンを取得します。

   az account get-access-token --query accessToken --output tsv
   

4. Visual Studio Code 内の新しいテキスト ファイルに、次の変数を貼り付けます。

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

5. 指定した変数を使用する要求を貼り付けて送信します。 "検索インデックス データ閲覧者" であればクエリを送信できます。 サポートされている API バージョンを使用できます。

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2025-09-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

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

   リファレンス:ドキュメントの検索

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

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

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

3. 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

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

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

5. クエリの実行例を次に示します。

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

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

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

   pip install azure-search-documents azure-identity
   

2. トークン認証用に Azure.Identity for Python を使用します。

3. Python クライアントがサーバー側で実行しているアプリケーションである場合、DefaultAzureCredential を使用します。 アプリがブラウザーで実行している場合、対話型の認証を有効にします。

4. 次に例を示します。

   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

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

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

2. トークン認証用に Azure.Identity for JavaScript を使用します。

3. React を使用している場合は、Search に対する Microsoft Entra 認証に InteractiveBrowserCredential を使用します。 詳細については、「@azure/identity を使用する場合」を参照してください。

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

   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-search-documents</artifactId>
     <version>11.6.0</version>
   </dependency>
   <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-identity</artifactId>
     <version>1.10.0</version>
   </dependency>
   

2. トークン認証用に Azure.Identity for Java を使用します。

3. Azure で実行されるアプリには DefaultAzureCredential を使用します。

次の手順は、「Azure portal を使用して Azure カスタム ロールを作成または更新する」から派生したものです。 検索サービス ページでは、既存のロールからの複製がサポートされています。

次の手順では、インデックスを名前で一覧表示する権限を追加して検索クエリの権限を増強したカスタム ロールを作成します。 通常、インデックスの一覧表示は管理者用の機能とされています。

1. Azure portal で、検索サービスに移動します。

2. 左側のナビゲーション ペインで [アクセス制御 (IAM)] を選択します。

3. アクション バーで、[ロール] を選択します。

4. [検索インデックス データ閲覧者] (または別のロール) を右クリックし、[複製] を選択して [カスタム ロールを作成する] ウィザードを開きます。

5. [基本] タブでカスタム ロールの名前 ("Search Index Data Explorer" など) を指定し、[次へ] をクリックします。

6. [アクセス許可] タブで [アクセス許可の追加] を選択します。

7. [アクセス許可の追加] タブで、Microsoft Search タイルを検索して選択します。

8. カスタム ロールのアクセス許可を設定します。 ページの上部で、既定の [アクション] の選択を使用します。

   • Microsoft.Search/operations で、[Read : List all available operations]\(読み取り: 使用可能なすべての操作を一覧表示する\) を選択します。
   • Microsoft.Search/searchServices/indexes で、[Read: Read Index]\(読み取り: インデックスの読み取り\) を選択します。

9. 同じページの [データ アクション] に切り替え、Microsoft.Search/searchServices/indexes/documents で [Read : Read Documents]\(読み取り: ドキュメントの読み取り\) を選択します。

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

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. [確認および作成] を選択してロールを作成します。 これで、ユーザーとグループをロールに割り当てることがきるようになりました。

PowerShell の例では、 検索インデックス データ 閲覧者の複製であるカスタム ロールを作成するための JSON 構文を示しますが、名前ですべてのインデックスを一覧表示できます。

1. アトミック アクセス許可の一覧を確認して、必要なものを判断します。 この例では、次のアクセス許可が必要です。

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. カスタム ロールを作成する PowerShell セッションを設定します。 詳細な手順については、 Azure PowerShell を参照してください。

3. JSON ドキュメントとしてロール定義を用意します。 PowerShell を使ってカスタム ロールを作成する構文の例を次に示します。

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

1. アトミック アクセス許可の一覧を確認して、必要なものを判断します。

2. 手順については、「REST API を使用して Azure カスタム ロールを作成または更新する」を参照してください。

3. ロールをコピーまたは作成するか、JSON を使用してカスタム ロールを指定します (JSON の構文については、[PowerShell] タブを参照してください)。

1. アトミック アクセス許可の一覧を確認して、必要なものを判断します。

2. 手順については、「Azure CLI を使用して Azure カスタム ロールを作成または更新する」を参照してください。

3. JSON 構文については、[PowerShell] タブを参照してください。