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

通过共享专用链接建立出站连接

项目
12/19/2024

本文介绍如何配置从 Azure AI 搜索到在 Azure 虚拟网络中运行的 Azure 资源的专用出站调用。

通过设置专用连接，使搜索服务可连接到虚拟网络 IP 地址，而不是连接到对 Internet 开放的端口。为连接创建的对象称为“共享专用链接”。在连接中，搜索服务使用内部的共享专用链接来访问网络边界内的 Azure 资源。

共享专用链接是按使用量计费的高级功能。设置共享专用链接时，会将专用终结点的费用添加到 Azure 发票中。在用户使用共享专用链接时，系统还会对入站和出站访问的数据传输费率开票。有关详细信息，请参阅 Azure 专用链接定价。

注意

如果要设置与 SQL 托管实例的专用索引器连接，请转而参阅本文，了解特定于该资源类型的步骤。

何时使用共享专用链接

在以下场景中，Azure AI 搜索将对其他 Azure 资源发出出站调用：

用于矢量化的 Azure OpenAI、Azure AI 视觉或 Azure AI Foundry 模型目录的索引器或查询连接
与受支持的数据源的索引器连接
将索引器（技能组）连接到 Azure 存储以缓存扩充内容、调试会话状态或写入知识存储
索引器（技能组）出于计费目的连接到 Azure AI 服务
对 Azure 密钥保管库发出加密密钥请求
对 Azure Functions 或类似资源发出自定义技能请求

共享专用链接仅适用于 Azure 到 Azure 连接。如果你要连接到 OpenAI 或其他外部模型，则必须通过公共 Internet 进行连接。

共享专用链接用于通过 Azure 资源或者在 Azure 虚拟网络中运行的客户端的专用终结点访问的操作和数据。

共享专用链接：

是使用 Azure AI 搜索工具、API 或 SDK 创建的
由 Azure 资源所有者批准
在内部由 Azure AI 搜索用于与特定 Azure 资源建立专用连接

只有搜索服务可以使用它所创建的专用链接，并且对于每个资源和子资源组合，只能在该服务上创建一个共享专用链接。

设置专用链接后，每当搜索服务连接到资源时，就会自动使用此链接。无需修改连接字符串或更改用于发出请求的客户端，不过，用于连接的设备必须使用 Azure 资源防火墙中已授权的 IP 进行连接。

可以通过两种方案来结合使用 Azure 专用链接和 Azure AI 搜索。

方案一：创建共享专用链接，当与 Azure 的出站（索引器）连接需要专用连接时，适用该方案。
方案二：针对从虚拟网络中运行的客户端建立的专用入站连接配置搜索。

本文将介绍第一个方案。

虽然这两种方案都依赖于 Azure 专用链接，但它们是独立的。你可以创建共享专用链接，而无需为专用终结点配置自己的搜索服务。

限制

在为方案评估共享专用链接时，请记住这些限制。

共享专用链接中使用的多种资源类型目前是作为预览版提供的。如果你要连接到预览版资源（Azure Database for MySQL 或 Azure SQL 托管实例），请使用管理 REST API 预览版创建共享专用链接。这些版本包括 2020-08-01-preview、2021-04-01-preview、2024-03-01-preview、2024-06-01-preview。建议使用最新的预览版 API。
索引器执行必须使用特定于你的搜索服务的专用执行环境。多租户内容处理环境不支持专用终结点连接。本文将介绍如何根据此要求完成配置设置。
查看每个层的共享专用链接资源限制。

先决条件

支持的 Azure 资源，配置为在虚拟网络中运行。

按工作负载划分的具有层和区域要求的 Azure AI 搜索服务：

工作负荷	层要求	区域要求	服务创建要求
没有技能组的索引器	基础版及更高版本	无	无
具有嵌入技能（集成矢量化）的技能组	基础版及更高版本	高容量区域	2024 年 4 月 3 日之后
使用其他内置或自定义技能的技能组	标准 2 (S2) 及更高版本	无	2024 年 4 月 3 日之后

同时在 Azure AI 搜索和 Azure 资源上具有的权限：

资源	权限
Azure AI 搜索	`Microsoft.Search/searchServices/sharedPrivateLinkResources/write` `Microsoft.Search/searchServices/sharedPrivateLinkResources/read` `Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read`
其他 Azure 资源	批准专用终结点连接的权限。例如，在 Azure 存储上，需要 `Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action`。

支持的资源类型

可为以下资源创建共享专用链接。

资源类型	子资源（或组 ID）
Microsoft.Storage/storageAccounts ¹	`blob`、`table`、`dfs`、`file`
Microsoft.DocumentDB/databaseAccounts ²	`Sql`
Microsoft.Sql/servers ³	`sqlServer`
Microsoft.KeyVault/vaults	`vault`
Microsoft.DBforMySQL/servers（预览版）	`mysqlServer`
Microsoft.Web/sites ⁴	`sites`
Microsoft.Sql/managedInstances（预览版）⁵	`managedInstance`
Microsoft.CognitiveServices/accounts ⁶ ⁷	`openai_account`
Microsoft.CognitiveServices/帐户 ⁸	`cognitiveservices_account`

¹ 如果 Azure 存储和 Azure AI 搜索位于同一区域，则会通过 Microsoft 主干网来与存储建立连接，这意味着，共享专用链接对于此配置是冗余的。但是，如果你已经为 Azure 存储设置了专用终结点，则还应该设置共享专用链接，否则存储端将拒绝连接。此外，如果你在搜索中为各种场景使用多种存储格式，请确保为每个子资源创建一个单独的共享专用链接。

²Microsoft.DocumentDB/databaseAccounts 资源类型用于与 Azure Cosmos DB for NoSQL 建立索引器连接。提供程序名称和组 ID 区分大小写。

³ Microsoft.Sql/servers 资源类型用于连接到 Azure SQL 数据库。目前不支持共享专用链接到 Azure Synapse SQL。

³ Microsoft.Web/sites 资源类型用于应用服务和 Azure 函数。在 Azure AI 搜索的上下文中，Azure 函数是更常见的方案。 Azure 函数通常用于托管自定义技能的逻辑。 Azure 函数具有“消耗”、“高级”和“专用”的应用程序服务托管计划。目前不支持应用服务环境 (ASE)、Azure Kubernetes 服务 (AKS) 和 Azure API 管理。

⁴ 有关说明，请参阅为 SQL 托管实例创建共享专用链接。

⁶ 当实现集成矢量化时，Microsoft.CognitiveServices/accounts 资源类型用于与 Azure OpenAI 嵌入模型建立矢量化器和索引器连接。自 2024 年 11 月 19 日起，支持在 Azure AI Foundry 模型目录中嵌入模型或 Azure AI 视觉多模式 API 的共享专用链接。

⁷ 只有公有云支持 Azure OpenAI 的共享专用链接。其他云产品（例如 Microsoft Azure 政府）不支持 openai_account 组 ID 的共享专用链接。

⁸ 共享专用链接现在（自 2024 年 11 月起）支持连接到 Azure AI 多服务帐户。 Azure AI 搜索连接到 Azure AI 多服务，以进行计费。这些连接现在可以通过共享专用链接成为私有连接。仅当在技能集定义中配置托管标识（无密钥配置）时，才支持共享专用链接。

1 - 创建共享专用链接

使用 Azure 门户、管理 REST API、Azure CLI 或 Azure PowerShell 创建共享专用链接。

下面是一些提示：

为专用链接指定一个有意义的名称。在 Azure PaaS 资源中，共享专用链接将与其他专用终结点一起显示。 “shared-private-link-for-search”之类的名称可以提示你如何使用该专用链接。

完成此部分的步骤后，即已预配一个处于挂起状态的共享专用链接。创建该链接需要几分钟时间。创建后，资源所有者必须先批准请求，然后才能进行操作。

登录到 Azure 门户并查找你的搜索服务。
在左侧导航窗格上的“设置”下，选择“网络”。
在“共享专用访问”页上，选择“+ 添加共享专用访问”。
选择“连接到我的目录中的 Azure 资源”或“按资源 ID 连接到 Azure 资源”。
如果选择第一个选项（建议），Azure 门户将帮助你选取相应的 Azure 资源并填充其他属性，例如资源的组 ID 和资源类型。
如果选择第二个选项，请手动输入 Azure 资源 ID，然后从本文开头的列表中选择相应的组 ID。
确认预配状态为“正在更新”。
成功创建资源后，资源的预配状态将更改为“成功”。

注意

对于处于预览状态的组 ID，必须使用预览 API 版本。以下资源类型目前处于预览状态：managedInstance、mySqlServer、sites。

Azure 门户、Azure PowerShell 或 Azure CLI 等工具提供用于帐户登录的内置机制，而 REST 客户端则需要提供持有者令牌才能传递请求。

本部分使用 Azure CLI 步骤来获取持有者令牌，因为这种方法简单快捷。有关更持久的方法，请参阅使用 REST 进行管理。

打开命令行并运行 az login 以进行 Azure 登录。
显示活动帐户和订阅。验证此订阅是否与你要为其创建共享专用链接的 Azure PaaS 资源所在的订阅相同。
```
az account show
```
如果订阅不正确，请更改订阅：
```
az account set --subscription {{Azure PaaS subscription ID}}
```
创建持有者令牌，然后复制整个令牌（引号之间的所有内容）。
```
az account get-access-token
```

切换到 REST 客户端并设置一个 GET 共享专用链接资源。查看现有的共享专用链接以确保不会复制某个链接。每个资源和子资源组合只能有一个共享专用链接。

@subscriptionId = PASTE-HERE
@rg-name = PASTE-HERE
@service-name = PASTE-HERE
@token = PASTE-TOKEN-HERE

GET https://https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

发送请求。你应会获得一个列表，其中列出了搜索服务的所有共享专用链接资源。确保资源和子资源组合没有现有的共享专用链接。

构建 PUT 请求，为 Azure PaaS 资源创建或更新共享专用链接。

PUT https://https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2023-11-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

{
    "properties":
     {
        "groupID": "blob",
        "privateLinkResourceId": "/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Storage/storageAccounts/{{storage-account-name}}",
        "provisioningState": "",
        "requestMessage": "Please approve this request.",
        "resourceRegion": "",
        "status": ""
     }
}

如果 Azure PaaS 资源位于不同的订阅中，请使用 Azure CLI 更改订阅，然后获取对该订阅有效的持有者令牌：

az account set --subscription {{Azure PaaS subscription ID}}

az account get-access-token

发送请求。若要检查状态，请重新运行第一个“GET 共享专用链接”请求，以监视预配状态从“正在更新”到“成功”的转换。

有关入门说明，请参阅使用 PowerShell 进行管理。

首先，使用 Get-AzSearchSharedPrivateLinkResource 查看所有现有的共享专用链接，以确保不会复制某个链接。每个资源和子资源组合只能有一个共享专用链接。

Get-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name>

使用 New-AzSearchSharedPrivateLinkResource 创建共享专用链接（用有效值替换占位符）。此示例适用于 Blob 存储。

New-AzSearchSharedPrivateLinkResource -ResourceGroupName <search-service-resource-group-name> -ServiceName <search-service-name> -Name <spl-name> -PrivateLinkResourceId /subscriptions/<alphanumeric-subscription-ID>/resourceGroups/<storage-resource-group-name>/providers/Microsoft.Storage/storageAccounts/myBlobStorage -GroupId blob -RequestMessage "Please approve"

重新运行第一个请求，以监视预配状态从“正在更新”到“成功”的转换。

有关入门说明，请参阅使用 Azure CLI 进行管理。

首先，使用 az-search-shared-private-link-resource list 查看所有现有的共享专用链接，以确保不会复制某个链接。每个资源和子资源组合只能有一个共享专用链接。

az search shared-private-link-resource list --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}}

在下一步骤中使用 az-search-shared-private-link-resource create。此示例适用于 Azure Cosmos DB for NoSQL。

语法区分大小写，因此请确保组 ID 为 Sql，提供程序名称为 Microsoft.DocumentDB。

az search shared-private-link-resource create --name {{your-shared-private-link-name}} --service-name {{your-search-service-name}} --resource-group {{your-search-service-resource-group}} --group-id Sql --resource-id "/subscriptions/{{your-subscription-ID}}/{{your-cosmos-db-resource-group}}/providers/Microsoft.DocumentDB/databaseAccounts/{{your-cosmos-db-account-name}}"

重新运行第一个请求，以监视预配状态从“正在更新”到“成功”的转换。

共享专用链接创建工作流

如果成功，返回响应 202 Accepted。创建出站专用终结点的过程是一个长期（异步）操作。它包括部署以下资源：

专用终结点，分配的专用 IP 地址处于 "Pending" 状态。专用 IP 地址是从地址空间（已分配给搜索服务特定专用索引器的执行环境的虚拟网络）获得的。获得专用终结点批准后，从 Azure AI 搜索到存储帐户的任何通信都源自专用 IP 地址和安全的专用链接通道。
适用于资源类型的专用 DNS 区域，基于组 ID。通过部署此资源，可确保对专用资源的任何 DNS 查找都利用与专用终结点关联的 IP 地址。

2 - 批准专用终结点连接

在 Azure PaaS 端已授予对专用终结点连接的批准。需要资源所有者的显式批准。以下步骤说明如何使用 Azure 门户进行批准，但下面是一些用于从 Azure PaaS 端以编程方式批准连接的链接：

在 Azure 存储上，使用专用终结点连接 - 放置
在 Azure Cosmos DB 上，使用专用终结点连接 - 创建或更新
在 Azure OpenAI 上，使用专用终结点连接 - 创建或更新

使用 Azure 门户执行以下步骤：

打开 Azure PaaS 资源的“网络”页。文本
找到列出专用终结点连接的部分。以下示例适用于存储帐户。
选择连接，然后选择“批准”。状态可能需要几分钟时间才会在 Azure 门户中更新。

批准专用终结点后，Azure AI 搜索会在为它创建的 DNS 区域中创建所需 DNS 区域映射。

虽然“网络”页上的专用终结点链接处于活动状态，但它不会解析。

选择链接会产生错误。此时会显示状态消息 "The access token is from the wrong issuer" 和 must match the tenant associated with this subscription，这是因为后端专用终结点资源是在 Microsoft 托管租户中由 Microsoft 预配的，而链接的资源（Azure AI 搜索）位于你的租户中。根据设计，你无法通过选择专用终结点连接链接来访问专用终结点资源。

请按照下一部分中的说明检查共享专用链接的状态。

3 - 检查共享专用链接状态

在 Azure AI 搜索端，可以通过重新访问搜索服务“网络”页的“共享专用访问”页来确认请求批准状态。连接状态应为“已批准”。

或者，也可以使用共享专用链接资源 - GET 获取连接状态。

az rest --method get --uri https://management.azure.com/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2024-07-01

这会返回一段 JSON，其中“properties”节下的“status”显示了连接状态。下面是存储帐户的示例。

{
      "name": "blob-pe",
      "properties": {
        "privateLinkResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/contoso/providers/Microsoft.Storage/storageAccounts/contoso-storage",
        "groupId": "blob",
        "requestMessage": "please approve",
        "status": "Approved",
        "resourceRegion": null,
        "provisioningState": "Succeeded"
      }
}

如果资源的预配状态 (properties.provisioningState) 为“Succeeded”且连接状态 (properties.status) 为“Approved”，则表示共享专用链接资源正常运行，可以将索引器配置为通过专用终结点通信。

4 - 将索引器配置为在专用环境中运行

索引器执行发生在以下两种环境之一：特定于搜索服务的专用环境，或内部用于为多个客户卸载昂贵的技能组处理的多租户环境。

执行环境是透明的，但是一旦开始构建防火墙规则或建立专用连接，就必须考虑索引器的执行。对于专用连接，请将索引器执行配置为始终在专用环境中运行。

此步骤演示如何将索引器配置为使用 REST API 在专用环境中运行。你也可以在 Azure 门户中使用 JSON 编辑器设置执行环境。

注意

你可以在批准专用终结点连接之前执行此步骤。然而，在专用终结点连接显示为已批准之前，任何尝试与安全资源（如存储帐户）进行通信的现有索引器都会最终处于暂时性故障状态，将无法创建新索引器。

如常创建数据源定义、索引和技能组（若正在使用某个技能组）。使用共享专用终结点时，这些定义中的属性不会发生任何变化。

创建一个索引器，该索引器指向在前面的步骤中创建的数据源、索引和技能组。此外，通过将索引器的 executionEnvironment 配置属性设置为 private，强制索引器在专用执行环境中运行。

{
    "name": "indexer",
    "dataSourceName": "blob-datasource",
    "targetIndexName": "index",
    "parameters": {
        "configuration": {
            "executionEnvironment": "private"
        }
    },
    "fieldMappings": []
}

成功创建索引器后，它应通过专用终结点连接到 Azure 资源。你可以使用索引器状态 API 来监视索引器的状态。

注意

如果已有现有索引器，则可将 executionEnvironment 设置为 private 或在 Azure 门户中使用 JSON 编辑器来通过 PUT API 更新它们。

5 - 测试共享专用链接

验证 Azure PaaS 资源是否拒绝来自公共 Internet 的连接（如果尚未验证）。如果它接受这种连接，请检查 Azure PaaS 资源的“网络”页中的 DNS 设置。
选择一种可以调用出站请求方案（例如将索引器连接到专用终结点）的工具。一种简单做法是使用“导入数据”向导，但你也可以尝试使用 REST 客户端和 REST API 来提高准确度。假设未同时为搜索服务配置专用连接，则可以通过公共 Internet 将 REST 客户端连接到搜索服务。
设置专用 Azure PaaS 资源的连接字符串。共享专用链接的连接字符串格式不会更改。搜索服务在内部调用共享专用链接。

对于索引器工作负荷，连接字符串位于数据源定义中。数据源的示例可能如下所示：
```
 {
   "name": "my-blob-ds",
   "type": "azureblob",
   "subtype": null,
   "credentials": {
     "connectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=..."
   }
```

对于索引器工作负荷，请记得在索引器定义中设置执行环境。索引器定义的示例可能如下所示：

"name": "indexer",
"dataSourceName": "my-blob-ds",
"targetIndexName": "my-index",
"parameters": {
   "configuration": {
       "executionEnvironment": "private"
       }
   },
"fieldMappings": []
}

运行索引器。如果索引器执行成功并且填充了搜索索引，则表示共享专用链接正常工作。

疑难解答

如果索引器创建失败并出现“数据源凭据无效”，请在调试连接之前检查共享专用链接的批准状态。如果状态为 Approved，则检查 properties.provisioningState 属性。如果是 Incomplete，则基础依赖项可能存在问题。在这种情况下，请重新发出 PUT 请求以重新创建共享的专用链接。你可能还需要重复审批步骤。
如果索引器持续或间歇性地失败，请检查索引器上的 executionEnvironment 属性。该值应设置为 private。如果你没有设置此属性，并且索引器运行在过去成功了，这是因为搜索服务自行使用了一个私有环境。如果系统承受负载，搜索服务会将处理移出多租户环境。
如果在创建共享专用链接时收到错误，请检查服务限制以验证是否低于层的配额。

后续步骤

详细了解专用终结点和其他安全连接方法：

通过