你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

配置搜索服务以使用托管标识进行连接

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

你可以将 Microsoft Entra ID 安全主体和角色分配用于从 Azure AI 搜索到在索引或查询期间提供数据、应用的 AI 或矢量化的其他 Azure 资源的出站连接。

要在出站连接上使用角色，请先将搜索服务配置为使用系统分配的托管标识或用户分配的托管标识作为Microsoft Entra 租户中搜索服务的安全主体。获得托管标识后，可以分配角色以实现授权访问。使用托管标识和角色分配，便无需在连接字符串或代码中传递机密和凭据。

先决条件

位于任何区域且采用基本层或更高级别的 Azure AI 搜索服务。
一种 Azure 资源，用于接受来自具有有效角色分配的 Microsoft Entra 安全主体的传入请求。
若要创建托管标识，你必须是所有者或用户访问管理员。若要分配角色，你必须是所有者、用户访问管理员、基于角色的访问控制管理员，或具有 Microsoft.Authorization/roleAssignments/write 权限的自定义角色的成员。

支持的方案

可以在以下场景中使用托管标识。

场景	系统分配	用户已分配
连接到索引器数据源¹	是的	是的
通过技能/矢量器 ² 连接到 Azure OpenAI、Microsoft Foundry 和 Azure Functions 中的嵌入和聊天补全模型	是的	是的
连接到 Azure 密钥保管库以管理客户的密钥	是的	是的
连接到调试会话（Azure 存储）¹	是的	不
连接到托管在 Azure 存储中的扩充缓存（预览版）^1,³	是的	是 ⁴
连接到知识库（在 Azure 存储中托管）¹	是的	是的

¹ 对于搜索和存储之间的连接，网络安全会对可以使用哪种类型的托管标识施加约束。只有系统托管标识可用于与 Azure 存储的同一区域连接，并且该连接必须通过 受信任的服务异常或资源实例规则。有关详细信息，请参阅访问受网络保护的存储帐户。

²通过技能/向量器连接到 Azure OpenAI、Foundry 和 Azure Functions 包括：Custom 技能、Custom 向量器 Azure OpenAI 嵌入技能、Azure OpenAI 向量器、AML 技能和Microsoft Foundry 模型目录向量器。

³ AI 搜索服务当前无法连接到已关闭共享密钥访问的存储帐户上的表。

⁴ 用户分配的用于扩充缓存连接的托管标识需要预览版 REST API（2025-11-01-preview 或更高版本）或预览版 SDK 包。此表中的所有其他用户分配托管标识方案均受 REST API 版本 2026-04-01 及更高版本支持。

创建系统托管标识

系统分配的托管标识是自动创建并链接到 Azure 资源（例如 Azure AI 搜索服务）的 Microsoft Entra ID 安全主体。

对于每个搜索服务，可以有一个系统分配的托管标识。它对于您的搜索服务是独特的，并且在服务的整个生命周期内始终与其绑定。

启用系统分配的托管标识时，Microsoft Entra ID为搜索服务创建一个安全主体，用于向其他Azure资源进行身份验证。然后，可以在角色分配中使用此标识来授权访问数据和操作。

在 Azure 门户中转到你的搜索服务。
在左窗格中，选择 “设置>标识”。
在 “系统分配 ”选项卡上的“ 状态”下，选择“ 打开”。
选择“ 保存”。

保存设置后，页面将更新以显示分配给搜索服务的对象标识符。

Set-AzSearchService `
  -Name YOUR-SEARCH-SERVICE-NAME `
  -ResourceGroupName YOUR-RESOURCE-GROUP-NAME `
  -IdentityType SystemAssigned

有关详细信息，请参阅使用系统分配的托管标识创建搜索服务（Azure PowerShell。

az search service update `
  --name YOUR-SEARCH-SERVICE-NAME `
  --resource-group YOUR-RESOURCE-GROUP-NAME `
  --identity-type SystemAssigned

有关详细信息，请参阅使用系统分配的托管标识创建搜索服务（Azure CLI）。

使用服务 - 创建或更新（REST API）来构建请求。

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

响应包括系统分配的托管标识的确认和对象标识符。

创建用户分配的托管标识

用户分配的托管标识是一种Azure资源，可以限定为订阅、资源组或资源类型。

可以创建多个用户分配的托管标识，以便在角色分配中实现更高的精细度。例如，你可能希望针对不同的应用程序和方案使用单独的标识。作为独立创建和管理的资源，它不会绑定到服务本身。

设置用户分配的托管标识的步骤如下：

在Azure订阅中，创建用户分配的托管标识。
在搜索服务中，将用户分配的托管标识与搜索服务相关联。
在要连接到的其他Azure服务上，为标识创建角色分配。

Azure门户、搜索管理 REST API 和提供该功能的 SDK 包支持将用户分配的托管标识与Azure AI 搜索服务相关联。

Azure 门户
REST API

登录到 Azure 门户。
在仪表板的左上角，选择“ 创建资源”。
使用搜索框查找 用户分配的托管标识，然后选择“ 创建”。
选择订阅、资源组和区域。为标识提供描述性名称。
选择“ 创建 ”并等待资源完成部署。

使用标识前需要几分钟时间。
在搜索服务页上，选择 “设置>标识”。
在“ 用户分配 ”选项卡上，选择“ 添加”。
选择之前创建的订阅和用户分配的托管标识。

与其使用 Azure 门户，可以使用搜索管理 REST APIs 来分配用户分配的托管标识。

使用服务 - 更新（REST API）来构建请求。

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2025-05-01  HTTP/1.1
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[name of resource group]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

将 identity.type 设置为身份类型。
- 有效值为SystemAssigned、UserAssigned或SystemAssigned, UserAssigned，适用于两者。
- 值None会从搜索服务中清除以前分配的任何标识。
更新 identity.userAssignedIdentities 以包含用户分配的托管标识的详细信息。必须先存在此标识，然后才能在请求中指定它。

分配角色

获得托管标识后，分配用于确定 Azure 资源的搜索服务权限的角色。

索引器数据连接和访问Azure 密钥保管库中客户管理的密钥需要读取权限。
AI 扩充功能需要写入权限，这些功能使用Azure 存储在知识存储中托管调试会话数据、扩充缓存和长期内容存储。

以下步骤说明了角色分配工作流。此示例适用于 Azure OpenAI。有关其他Azure资源，请参阅 Connect 到 Azure 存储、Connect 到 Azure Cosmos DB 或 Connect 到 Azure SQL。

在 Azure 门户中，转到 Azure OpenAI 资源。
从左侧菜单中选择 访问控制 。
选择 “添加” ，然后选择“ 添加角色分配”。
在 “作业功能角色”下，选择 “认知服务 OpenAI 用户 ”，然后选择“ 下一步”。
在成员下，选择托管标识，然后选择成员。
按订阅和资源类型（搜索服务）进行筛选，然后选择搜索服务的托管标识。
选择 “审阅 + 分配”。

连接字符串示例

回想一下方案说明，可以在连接字符串中使用托管标识到其他 Azure 资源。本部分提供示例。

系统分配的托管标识连接使用普遍可用的 REST API 版本。用户分配的托管标识连接使用 REST API 版本 2026-04-01 或更高版本，但扩充缓存连接仍需要预览版 API 版本。

提示

可以在 Azure 门户中创建大部分对象，并指定系统或用户分配的托管标识，然后查看 JSON 定义以获取连接字符串。

Blob 数据源（系统托管标识）：

索引器数据源包含一个 credentials 属性，用于确定如何与数据源建立连接。以下示例演示如何通过连接字符串指定存储帐户的唯一资源 ID。

当连接字符串是 Microsoft Entra ID 感知服务或应用程序的唯一资源 ID 时，将指示系统管理标识。用户分配的托管标识是通过属性 identity 指定的。

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob 数据源（用户托管标识）：

用户分配的托管标识可通过具有 REST API 版本 2026-04-01 或更高版本的 identity 上的属性进行支持。

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

知识存储（系统托管标识）：

知识存储的定义包括一个用于 Azure 存储的连接字符串。连接字符串是存储帐户的唯一资源 ID。请注意，字符串不包括路径中的容器或表。这些内容由嵌入式投影定义决定，而不是由连接字符串决定。

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

知识存储（用户托管标识）：

通过 REST API 版本 2026-04-01 或更高版本中 identity 的属性支持用户分配的托管标识。

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};",
  "identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }
}

扩充缓存（预览版）：

索引器创建、使用和记住用于缓存扩充的容器。无需在缓存连接字符串中包含容器。可以在 Azure 门户中搜索服务的 Identity 页上找到对象 ID。

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

调试会话：

调试会话在 Azure 门户中运行，当启动会话时会采用连接字符串。可以粘贴类似于以下示例的字符串。

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

自定义技能：

自定义技能针对托管自定义代码的 Azure 函数或应用的终结点。

uri 是函数或应用的终结点。
authResourceId 告知搜索服务使用托管标识进行连接，在属性中传递目标函数或应用的应用程序 ID。

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

模型的连接示例

对于使用托管标识建立的连接，本部分显示了搜索服务如何连接到其他资源上模型的示例信息。通过系统托管标识建立的连接是透明的;标识和角色已到位，如果正确配置连接，则连接会成功。相比之下，用户托管标识需要额外的连接属性。

Azure OpenAI 嵌入技能和Azure OpenAI vectorizer：

AI 搜索中的 Azure OpenAI 嵌入技能和矢量化程序以托管嵌入模型的 Azure OpenAI 的终结点为目标。终结点在 Azure OpenAI 嵌入技能定义和/或 Azure OpenAI 向量器定义中指定。

如果 "apikey" 和 "authIdentity" 为空，则会自动使用系统托管标识，如以下示例所示。该 "authIdentity" 属性仅用于用户分配的托管标识。

系统托管身份示例：

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

下面是为系统分配的托管标识配置的向量器示例。向量器会在搜索索引中指定。

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
      }
    }
  ]

用户分配的托管标识示例：

如果 "apiKey" 为空并且提供了有效的 "authIdentity"，则使用用户分配的托管标识。

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "modelName": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ],
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
   }
}

下面是为用户分配的托管标识配置的向量化示例。向量器会在搜索索引中指定。

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002",
        "modelName": "text-embedding-ada-002"
        "authIdentity": {
            "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
            "userAssignedIdentity": "/subscriptions/<subscription_id>/resourcegroups/<resource_group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<user-assigned-managed-identity-name>"
          }
      }
    }
  ]

检查防火墙访问权限

如果Azure资源位于防火墙后面，请确保存在允许来自搜索服务和Azure门户的请求的入站规则。

对于与 Azure Blob 存储或 Azure Data Lake Storage Gen2 的同区域连接，请使用托管标识和受信任的服务异常。（可选）可以配置资源实例规则以允许请求。
对于所有其他资源和连接，配置允许来自Azure AI 搜索的请求的 IP 防火墙规则。有关详细信息，请参阅 Indexer 访问受Azure网络安全功能保护的内容。

另请参阅

反馈

此页面是否有帮助？

Last updated on 2026-05-14