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

使用托管标识将搜索服务连接到其他 Azure 资源

项目
04/08/2024

可以使用系统分配或用户分配的托管标识和 Azure 角色分配来配置 Azure AI 搜索服务，以连接到其他 Azure 资源。使用托管标识和角色分配，便无需在连接字符串或代码中传递机密和凭据。

先决条件

基本层或更高层的搜索服务。
一种 Azure 资源，用于接受来自具有有效角色分配的 Microsoft Entra 登录名的传入请求。

支持的方案

Azure AI 搜索可以在与 Azure 资源进行出站连接时使用系统分配或用户分配的托管标识。当连接字符串是 Microsoft Entra ID 感知服务或应用程序的唯一资源 ID 时，将指示系统管理标识。用户分配的托管标识是通过“标识”属性指定的。

搜索服务使用 Azure 存储作为索引器数据源，并用作调试会话、扩充缓存和知识存储的数据接收器。对于写回存储的搜索功能，托管标识需要参与者角色分配，如“分配角色”部分中所述。

场景	系统托管标识	用户分配的托管标识（预览版）
与支持的 Azure 数据源的索引器连接¹³	是	是
用于客户管理的密钥的 Azure 密钥保管库	是	是
调试会话（托管在 Azure 存储中）¹	是	否
扩充缓存（托管在 Azure 存储中）^1、²	是	是
知识存储（托管在 Azure 存储中）¹	是	是
自定义技能（托管在 Azure Functions 或等效项中）	是	是
Azure OpenAI 嵌入技能	是	是
Azure OpenAI 矢量器	是	是

¹ 对于搜索和存储之间的连接，网络安全配置会对可使用的托管标识类型进行约束。只有系统托管标识可用于通过受信任的服务异常或资源实例规则与存储建立同区域连接。有关详细信息，请参阅访问受网络保护的存储帐户。

² 导入数据向导中有一种指定扩充缓存的方法。目前，该向导不接受用于扩充缓存的托管标识连接字符串。但是，在向导完成后，可更新索引器 JSON 定义中的连接字符串以指定系统或用户分配的托管标识，然后重新运行索引器。

³ 请注意，用作数据源的 Azure 表当前不支持禁用 Azure 存储帐户中的密钥。尽管托管标识用于不以显式方式提供存储密钥，但 AI 搜索服务仍对此实现使用这些密钥。

创建系统托管标识

启用系统分配的托管标识后，Azure 将为搜索服务创建一个标识，该标识可用于对同一租户和订阅中的其他 Azure 服务进行身份验证。然后，可以在基于角色的访问控制 (Azure RBAC) 分配中使用此标识，该分配允许在编制索引期间访问数据。

系统分配的托管标识在搜索服务中是唯一的，并在其生命周期内绑定到该服务。

登录到 Azure 门户并查找你的搜索服务。
在“设置”下选择“标识”。
在“系统分配”选项卡上的“状态”下，选择“开”。
选择“保存”。

保存后，你将看到已分配给搜索服务的对象标识符。

请参阅创建或更新服务（管理 REST API）。

可以使用管理 REST API 代替门户来分配用户分配的托管标识。

构建创建或更新搜索服务的请求。

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

响应中会返回确认和系统托管标识的对象标识符。

创建用户分配的托管标识（预览版）

用户分配的托管标识是 Azure 上的一种资源。如果需要更细化的角色分配，则此方法非常有用，因为你可以为不同的应用程序和方案创建单独的标识。

重要

此功能根据补充使用条款处于公开预览状态。目前不支持用户分配的托管标识连接到受网络保护的存储帐户。搜索请求当前需要公共 IP 地址。

Azure 门户
REST API

登录到 Azure 门户
选择“+ 创建资源”。
在“搜索服务和市场”搜索栏中，搜索“用户分配的托管标识”，然后选择“创建”。
选择订阅、资源组和区域。为标识提供描述性名称。
选择“创建”，并等待资源完成部署。

在接下来的几个步骤中，你将向搜索服务分配用户分配的托管标识。
在搜索服务页面的“设置”下，选择“标识”。
在“用户分配”选项卡上，选择“添加”。
选择订阅，然后选择在上一步中创建的用户分配的托管资源。

可以使用管理 REST API 代替门户来分配用户分配的托管标识。执行此任务式，请务必使用 2021-04-01-preview 版本。

构建创建或更新搜索服务的请求。

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

设置“标识”属性以指定完全限定的托管标识：
- “类型”是标识的类型。如果要想同时使用两者，则有效值为“SystemAssigned”、“UserAssigned”或“SystemAssigned、UserAssigned”。如果值为“None”，将从搜索服务中清除任何先前分配的标识。
- “userAssignedIdentities”包括用户分配的托管标识的详细信息。此标识必须已经存在，你才能在创建或更新服务请求中指定它。

允许防火墙访问

如果你的 Azure 资源位于防火墙后面，请确保有一个入站规则来接受来自你的搜索服务的请求。

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

分配角色

托管标识必须与确定 Azure 资源权限的 Azure 角色配对。

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

以下步骤适用于 Azure 存储。如果资源是 Azure Cosmos DB 或 Azure SQL，则步骤是类似的。

登录 Azure 门户并查找搜索服务必须有权访问的 Azure 资源。
在 Azure 存储中，选择左侧导航窗格中的“访问控制(AIM)”。
选择“添加角色分配”。

在“角色”页上，选择你的搜索服务所需的角色：

任务	角色分配
使用索引器进行 Blob 索引编制	添加“存储 Blob 数据读取者”
使用索引器进行 ADLS Gen2 索引编制	添加“存储 Blob 数据读取者”
使用索引器进行表索引编制	添加“读取者和数据访问”
使用索引器进行文件索引编制	添加“读取者和数据访问”
写入到知识存储	添加适用于对象和文件投影的“存储 Blob 数据参与者”，以及适用于表投影的“读取者和数据访问”。
写入到扩充缓存	添加“存储 Blob 数据参与者”
保存调试会话状态	添加“存储 Blob 数据参与者”
使用 Azure OpenAI 嵌入模型嵌入数据（矢量化）	添加认知服务 OpenAI 用户

在“成员”页上，选择“托管标识”。
选择成员。在“选择托管标识”页中，选择订阅，按服务类型进行筛选，然后选择服务。只有具有托管标识的服务才可供选择。
选择“查看 + 分配”。

连接字符串示例

为搜索服务定义托管标识并提供角色分配后，可以将出站连接修改为使用其他 Azure 资源的唯一资源 ID。下面是各种方案的连接字符串的一些示例。

Blob 数据源（系统）：

索引器数据源包括“凭据”属性，可以确定如何与数据源建立连接。以下示例显示了一个连接字符串，该字符串指定存储帐户的唯一资源 ID。 Microsoft Entra ID 将使用搜索服务的系统托管标识对请求进行身份验证。请注意，连接字符串不包含容器。在数据源定义中，容器名称是在“容器”属性（未显示）中指定的，而不是在连接字符串中指定的。

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

Blob 数据源（用户）：

也可以在用户分配的托管标识下发出对 Azure 存储的搜索请求（目前处于预览状态）。搜索服务用户标识在“标识”属性中指定。可以使用门户或 REST API 预览版 2021-04-30-Preview 来设置此标识。

"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 存储的连接字符串。在 Azure 存储上，知识存储将以 blob 和表的形式创建投影。此连接字符串是存储帐户的唯一资源 ID。请注意，该字符串没有在路径中包括容器或表。它们是在嵌入的投影定义中定义的，而不是在连接字符串中定义的。

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

扩充缓存：

索引器创建、使用并记住用于缓存扩充的容器。没有必要在缓存连接字符串中包括容器。可以在门户中搜索服务的“标识”页上找到对象 ID。

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

调试会话：

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

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

自定义技能：

自定义技能面向托管自定义代码的 Azure 函数或应用的终结点。此终结点在自定义技能定义中指定。 “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 矢量器：

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",
  "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"
      }
    }
  ]