使用角色连接到Azure AI 搜索

Azure通过 Microsoft Entra ID 为平台上运行的所有服务提供全局身份验证和基于角色的访问控制。在本文中，了解哪些角色提供对Azure AI 搜索搜索内容和管理的访问权限。

在Azure AI 搜索中，可以为以下项分配Azure角色：

服务管理
对搜索服务的开发或写入访问权限
查询的只读访问权限
一定范围内对单个索引的访问权限

通过搜索结果的每个用户访问权限（有时称为行级安全性或文档级别访问）通过 Azure Data Lake Storage (ADLS) Gen2 和 Azure blob 索引的权限继承以及所有其他平台的安全筛选器（请参阅文档级访问控制）支持。

角色分配在所有工具和客户端库中是广泛且累积的。可以使用 Azure 基于角色的访问控制文档中描述的任何支持的方法来分配角色。

基于角色的访问是可选的，但建议使用。该选项的替代方法是基于密钥的身份验证，这是默认选项。

快速参考：按任务分配的角色

任务	所需角色
创建或管理索引、索引器、技能集	搜索服务参与者
将文档加载到索引中	搜索索引数据贡献者
查询索引	索引数据读取器
完全开发访问权限	搜索服务参与者 + 搜索索引数据参与者 + 搜索索引数据读取者
服务管理	所有者或参与者

先决条件

任何区域中位于任何层的搜索服务，针对基于角色的访问而启用。
所有者、用户访问管理员、基于角色的访问控制管理员，或具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色。

搜索中使用的内置角色

角色是对影响数据平面或控制平面的特定操作的权限集合。

数据平面是指针对搜索服务终结点的操作，例如索引或查询等，或者 Search Service REST API 或等效 Azure SDK 客户端库中指定的任何其他操作。

控制平面是指 Azure 资源管理，例如创建或配置搜索服务。

以下角色是内置角色。如果这些角色不符合你的需求，请创建自定义角色。

角色	平面	说明
所有者	控制与数据	完全访问搜索资源的控制平面，包括分配Azure角色的功能。只有所有者角色可以启用或禁用身份验证选项或管理其他用户的角色。默认情况下，订阅管理员是成员。在数据平面上，此角色具有与搜索服务参与者角色相同的访问权限。它包括对所有数据平面操作的访问权限，但不包括查询文档的能力。
参与者	控制与数据	与所有者相同的控制平面访问权限级别，但无法分配角色或更改身份验证选项。在数据平面上，此角色具有与搜索服务参与者角色相同的访问权限。它包括对除了查询文档或编制文档索引之外的所有数据平面操作的访问权限。
读者	控制与数据	跨整个服务的读取访问权限，包括搜索指标、内容指标（消耗的存储、对象数量）以及数据平面资源的对象定义（例如索引、索引器等）。但是，它无法读取 API 密钥或读取索引中的内容。
搜索服务参与者	控制与数据	对对象定义（索引、别名、同义词映射、索引器、数据源和技能组）的读写访问权限。此角色适用于创建对象的开发人员，以及管理搜索服务及其对象的管理员，但无权访问索引内容。使用此角色可创建、删除和列出索引、获取索引定义、获取服务信息（统计信息和配额）、测试分析器、创建和管理同义词映射、索引器、数据源和技能集。有关权限列表，请参阅 `Microsoft.Search/searchServices/*`。
搜索索引数据参与者	数据	对索引中内容的读写访问权限。此角色适用于需要导入、刷新或查询索引文档集合的开发人员或索引所有者。此角色不支持索引创建或管理。默认情况下，此角色适用于搜索服务上的所有索引。请参阅授予对单个索引的访问权限以缩小范围。
搜索索引数据读取者	数据	查询搜索索引的只读访问权限。此角色适用于运行查询的应用和用户。此角色不支持对对象定义的读取访问。例如，无法读取搜索索引定义或获取搜索服务统计信息。默认情况下，此角色适用于搜索服务上的所有索引。请参阅授予对单个索引的访问权限以缩小范围。

合并这些角色以获取足够的用例权限。

注意

如果禁用Azure基于角色的访问，则控制平面（所有者、参与者、读者）的内置角色将继续可用。禁用基于角色的访问只会删除与这些角色关联的数据相关权限。如果禁用数据平面角色，搜索服务参与者相当于控制平面参与者。

权限摘要

权限	索引数据读取器	搜索索引数据贡献者	搜索服务参与者	所有者/参与者	读者
在 Azure 门户中查看资源	❌	❌	✅	✅	✅
查看资源属性、指标和终结点	❌	❌	✅	✅	✅
列出资源上的所有对象	❌	❌	✅	✅	✅
访问配额和服务统计信息	❌	❌	✅	✅	❌
读取和查询索引	✅	✅	❌	❌	❌
上传用于编制索引 ¹ 的数据	❌	✅	❌	❌	❌
无论权限筛选器如何，读取权限提升 ²	❌	✅	❌	❌	❌
创建或编辑索引和别名	❌	❌	✅	✅	❌
创建、编辑和运行索引器、数据源和技能集	❌	❌	✅	✅	❌
创建或编辑同义词映射	❌	❌	✅	✅	❌
创建或编辑调试会话	❌	❌	✅	✅	❌
创建或管理部署	❌	❌	✅	✅	❌
创建或配置Azure AI 搜索资源	❌	❌	✅	✅	❌
在“密钥”下查看、复制和重新生成密钥	❌	❌	✅	✅	❌
查看角色、策略和定义	❌	❌	✅	✅	❌
设置身份验证选项	❌	❌	✅	✅	❌
配置专用连接	❌	❌	✅	✅	❌
配置网络安全	❌	❌	✅	✅	❌

¹ 在Azure门户中，所有者或参与者可以运行创建和加载索引的导入数据向导，即使它们不能在其他客户端中上传文档。搜索服务本身（而不是单个用户）在向导中建立数据连接。向导具有完成此任务所需的 Microsoft.Search/searchServices/indexes/documents/* 权限。

² 使用提升权限的读取来调试使用被调用方的身份获取结果的查询。有关详细信息，请参阅调查不正确的查询结果。

所有者和参与者授予相同的权限，但只有所有者可分配角色。

分配角色

在本部分中，为以下用途分配角色：

服务管理
对搜索服务的开发或写入访问权限
查询的只读访问权限

为服务管理分配角色

作为服务管理员，你可以创建和配置搜索服务，并执行管理 REST API 或等效客户端库中所述的所有控制平面操作。如果你是所有者或参与者，也可以在Azure门户中执行大多数数据平面Search REST API 任务。

角色	ID
`Owner`	8e3af657-a8ff-443c-a75c-2fe8c4bcb635
`Contributor`	b24988ac-6180-42a0-ab88-20f7382dd24c
`Reader`	acdd72a7-3385-48ef-bd42-f606fba81ae7

Azure portal
PowerShell

登录到 Azure 门户。
在左窗格中选择 访问控制（IAM）。
选择+ 添加>添加角色分配，以启动添加角色分配向导。
选择角色。
- 所有者（对所有数据平面和控制平面操作拥有完整访问权限，查询权限除外）
- 参与者（与所有者相同，但分配角色的权限除外）
- 阅读器（适于监控和查看指标）
在 Members 选项卡上，选择Microsoft Entra用户或组标识。如果要为另一个 Azure 服务设置权限，请选择系统或用户管理身份。
在“查看 + 分配”选项卡上，选择该选项以分配角色。

使用 PowerShell 分配角色时，请调用 New-AzRoleAssignment，提供Azure用户或组名称和分配范围。

示例中在搜索服务范围内创建了一个角色指派。

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

Reference：New-AzRoleAssignment

分配用于开发的角色

角色分配在搜索服务中全局应用。若要范围对单个索引的权限，请使用 PowerShell 或Azure CLI创建自定义角色。

任务	角色	ID
创建或管理对象	`Search Service Contributor`	7ca78c08-252a-4471-8644-bb5ff32d4ba0
加载文档，运行索引作业	`Search Index Data Contributor`	8ebe5a00-799e-43f5-93ac-243d3dce84a7
查询索引	`Search Index Data Reader`	1407120a-92aa-4202-b7e9-c0e197c71c8f

可提供完整访问权限的另一种角色组合是参与者或所有者加上搜索索引数据读取者。

重要

如果为服务或索引配置基于角色的访问，并且还在请求中提供 API 密钥，则搜索服务将使用 API 密钥进行身份验证。

Azure portal
PowerShell

登录到 Azure 门户。
在左窗格中选择 访问控制（IAM）。
选择+ 添加>添加角色分配，以启动添加角色分配向导。
选择角色。
- 搜索服务参与者（对索引、索引器、技能集和其他顶级对象进行创建、读取、更新和删除操作）
- 搜索索引数据参与者（加载文档并运行索引作业）
- 搜索索引数据读取器（查询索引）
在 Members 选项卡上，选择Microsoft Entra用户或组标识。如果要为另一个Azure服务设置权限，请选择系统或用户托管标识。
在“查看 + 分配”选项卡上，选择该选项以分配角色。

使用 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

为只读查询分配角色

对只需要对索引具有读取访问权限的应用和进程使用搜索索引数据读取者角色。

角色	ID
`Search Index Data Reader` 使用 PowerShell	1407120a-92aa-4202-b7e9-c0e197c71c8f

此角色非常具体。它对搜索索引的文档集合授予 GET 或 POST 访问权限，用于搜索、自动完成和建议。它不支持对索引或其他顶层对象或 GET 服务统计信息执行 GET 或 LIST 操作。

本部分提供设置角色分配的基本步骤，为了完整性而包含在此处。关于如何为基于角色的访问配置应用的详细说明，请参阅无密钥使用 Azure AI 搜索。

注意

作为开发人员，如果需要调试基于 Microsoft 标识的查询，请使用“搜索索引数据参与者”角色或创建自定义角色，该角色为你提供用于调试目的的提升权限。

Azure portal
PowerShell

登录到 Azure 门户。
在左窗格中选择 访问控制（IAM）。
选择+ 添加>添加角色分配，以启动添加角色分配向导。
选择 “搜索索引数据读取者 ”角色。
在 Members 选项卡上，选择Microsoft Entra用户或组标识。如果要为另一个Azure服务设置权限，请选择系统或用户托管标识。
在“查看 + 分配”选项卡上，选择该选项以分配角色。

使用 PowerShell 分配角色时，请调用 New-AzRoleAssignment，提供Azure用户或组名称和分配范围。

获取订阅 ID、搜索服务资源组和搜索服务名称。

获取Azure服务的对象标识符。

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

获取角色定义并查看权限，以确保这是所需的角色。
```
Get-AzRoleDefinition -Name "Search Index Data Reader"
```

创建角色分配，替换占位符的有效值。

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

以下是一个关于特定索引的角色分配的示例：

New-AzRoleAssignment -ObjectId <your-azure-aiservice-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>

Reference：New-AzRoleAssignment

测试角色分配

使用客户端测试角色分配。请记住，角色是可以叠加的。不能在资源（搜索服务）级别删除或拒绝那些在订阅或资源组级别上已限定作用域的继承角色。

为应用程序配置无密钥连接，并在测试之前设置好角色分配。

登录到 Azure 门户。
访问搜索服务。
在“概述”页上，选择“索引”选项卡：
- 搜索服务参与者可以查看和创建任何对象，但无法加载文档或查询索引。若要验证权限，请创建搜索索引。
- 搜索索引数据参与者可以加载文档。导入数据向导之外的Azure门户中没有加载文档选项，但可以设置并运行索引器以确认文档加载权限。
- 搜索索引数据读取者可以查询索引。若要验证权限，请使用搜索资源管理器。你应该可以发送查询并查看结果，但无法查看或创建索引定义。

此方法假定使用 Visual Studio Code 的 REST 客户端扩展。

打开Azure CLI命令 shell 并登录到Azure订阅。
```
az login
```
获取租户 ID 和订阅 ID。在将来的步骤中，将 ID 用作变量。
```
az account show
```

获取访问令牌。

az account get-access-token --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

粘贴并使用指定的变量发送请求。对于“搜索索引数据读取者”角色，可以发送查询。可以使用任何受支持的 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 则包含空数组。

参考：搜索文档

小窍门

有关如何获取特定环境的令牌的详细信息，请参阅使用 REST API 管理Azure AI 搜索服务和Microsoft 标识平台身份验证库。

安装所需的包：

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

使用 Azure.Identity for .NET 进行令牌身份验证。对于大多数方案，Azure建议使用 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.azure.cn"
index_name = "myindex"
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

Reference：SearchClient、 DefaultAzureCredential

安装所需的包：

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

使用 Azure.Identity for JavaScript 进行令牌身份验证。
如果您使用 React，请使用 InteractiveBrowserCredential 进行 Microsoft Entra 的身份验证以启用搜索功能。有关详细信息，请参阅何时使用 @azure/identity。

将所需的依赖项添加到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>

使用 Azure.Identity for Java 进行令牌身份验证。
对在 Azure 上运行的应用使用 DefaultAzureCredential。

作为当前用户进行测试

如果您已经是搜索服务的贡献者或所有者，可以使用持有者令牌对用户身份进行身份验证，以使用 Azure AI 搜索。

使用Azure CLI获取当前用户的持有者令牌：

az account get-access-token --scope https://search.azure.cn/.default

或者使用 PowerShell：

Get-AzAccessToken -ResourceUrl https://search.azure.cn

将这些变量粘贴到Visual Studio Code的新文本文件中。

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

粘贴，然后发送请求以确认访问权限。下面是针对 hotels-quickstart 索引的查询。

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
     }

授予对单个索引的访问权限

在某些情况下，你可能希望限制应用程序对单个资源（如索引）的访问权限。

Azure门户目前不支持此级别的角色分配，但可以使用 PowerShell 或 Azure CLI 分配角色。

在 PowerShell 中，使用 New-AzRoleAssignment，提供Azure用户或组名称和分配范围。

加载 Azure 和 AzureAD 模块并连接到Azure帐户：

Import-Module -Name Az
Import-Module -Name AzureAD
Connect-AzAccount -Environment AzureChinaCloud

将角色分配作用域限定为单个索引

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

创建自定义角色

如果内置角色未提供适当的权限组合，你可以创建一个自定义角色来支持所需的操作。

此示例克隆“搜索索引数据读取者”，然后添加按名称列出索引的功能。通常，在搜索服务中列出索引被视为一种管理权限。

这些步骤派生自使用 Azure 门户创建或更新Azure自定义角色。支持在搜索服务页面上克隆现有角色。

这些步骤将创建一个自定义角色来补充搜索查询权限，以包括按名称列出索引的权限。通常，列出索引被视为一项管理功能。

在 Azure 门户网站中，转到您的搜索服务。
在左侧导航窗格中，选择访问控制（IAM）。
在操作栏中，选择“角色”。
右键点击“搜索索引数据读取者”（或其他角色），选择“克隆”以打开“创建自定义角色”向导。
在“基本信息”选项卡上，提供自定义角色的名称，例如“搜索索引数据资源管理器”，然后选择Next。
在“权限”选项卡上，选择“添加权限”。
在“添加权限”选项卡上，搜索并选择Microsoft 搜索磁贴。
为自定义角色设置权限。在页面顶部，使用默认操作选择：
- 在Microsoft.Search/operations下，选择Read：列出所有可用操作。
- 在Microsoft下的Search/searchServices/indexes中，选择Read: Read Index。

在同一页上，切换到数据操作，在 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": []
         }
     ]
   }
 }

选择“查看 + 创建”以创建角色。现在可将用户和组分配到该角色。

PowerShell 示例显示了用于创建自定义角色的 JSON 语法，该角色是 搜索索引数据读取器的克隆，但能够按名称列出所有索引。

查看原子权限列表以确定所需的权限。对于此示例，需要执行以下操作：

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

设置 PowerShell 会话以创建自定义角色。有关详细说明，请参阅 Azure PowerShell
以 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}"
  ]
}

注意

如果在索引级别分配范围，请使用数据操作"Microsoft.Search/searchServices/indexes/documents/read"。

条件性访问

如果需要强制实施组织策略（如多重身份验证），请使用 Microsoft Entra 条件访问。

若要为Azure AI 搜索启用条件访问策略，请执行以下步骤：

登录 Azure 门户。
搜索 Microsoft Entra 条件访问。
选择“策略”。
选择“新策略” 。
在策略的 Cloud 应用或操作部分中，添加 Azure AI 搜索 作为云应用，具体取决于设置策略的方式。
更新策略的其余参数。例如，指定要将此策略应用于哪些用户和组。
保存策略。

重要

如果搜索服务分配了托管标识，则特定搜索服务会显示为云应用，你可以将其作为条件访问策略的一部分包含或排除。不能在特定搜索服务上强制实施条件访问策略。相反，请确保选择常规 Azure AI 搜索 云应用。

排查基于角色的访问控制问题

开发使用基于角色的访问控制进行身份验证的应用程序时，可能会遇到一些常见问题：

如果授权令牌来自托管标识，并且最近分配了适当的权限，则这些权限分配可能需要几个小时才能生效。
搜索服务的默认配置是基于密钥的身份验证。如果不将默认密钥设置更改为“ 两者 ”或“基于 角色的访问控制”，则无论基础权限如何，都将自动拒绝所有使用基于角色的身份验证的请求。

Last updated on 2026-04-08

通过

使用角色连接到Azure AI 搜索

快速参考：按任务分配的角色

先决条件

搜索中使用的内置角色

权限摘要

分配角色

为服务管理分配角色

分配用于开发的角色

为只读查询分配角色

测试角色分配

作为当前用户进行测试

授予对单个索引的访问权限

创建自定义角色

条件性访问

排查基于角色的访问控制问题

其他资源