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

项目
09/09/2024

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

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

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

注意

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

何时使用共享专用链接

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

索引器或搜索引擎连接到 Azure OpenAI 以进行文本到矢量的嵌入
与受支持的数据源的索引器连接
将索引器（技能组）连接到 Azure 存储以缓存扩充内容、调试会话状态或写入知识存储
对 Azure 密钥保管库发出加密密钥请求
对 Azure Functions 或类似资源发出自定义技能请求

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

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

共享专用链接：

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

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

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

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

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

本文将介绍第一个方案。

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

限制

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

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

先决条件

基本层或更高层的 Azure AI 搜索。如果你使用的是 AI 扩充和技能集，则该级别必须是标准 2 (S2) 或更高版本。有关详细信息，请参阅服务限制。
以下受支持资源类型列表中的某个 Azure PaaS 资源，配置为在虚拟网络中运行。
同时在 Azure AI 搜索和数据源上具有的权限：
- 在 Azure PaaS 资源上，必须具有批准专用终结点连接的权限。例如，如果正在使用 Azure 存储帐户作为数据源（例如 Blob 容器、Azure 文件共享、Azure 表），则需要 Microsoft.Storage/storageAccounts/privateEndpointConnectionsApproval/action。
- 在搜索服务中，必须具有对共享专用链接资源的读写权限和读取操作状态的权限：
  - Microsoft.Search/searchServices/sharedPrivateLinkResources/write
  - Microsoft.Search/searchServices/sharedPrivateLinkResources/read
  - Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read

支持的资源类型

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

资源类型	子资源（或组 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`

¹ 如果 Azure 存储和 Azure AI 搜索位于同一区域，则会通过 Microsoft Azure 主干网来与存储建立连接，这意味着，共享专用链接对于此配置是冗余的。但是，如果你已经为 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 的连接。目前不支持在 Azure AI Studio 模型目录中嵌入模型或 Azure AI 视觉多模式 API 的共享专用链接。

1 - 创建共享专用链接

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

下面是一些提示：

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

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

登录到 Azure 门户并查找你的搜索服务。
在左侧导航窗格上的“设置”下，选择“网络”。
在“共享专用访问”页上，选择“+ 添加共享专用访问”。
选择“连接到我的目录中的 Azure 资源”或“按资源 ID 连接到 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://management.chinacloudapi.cn/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://management.chinacloudapi.cn/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 AI 搜索会在为它创建的 DNS 区域中创建所需 DNS 区域映射。

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

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

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

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

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

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

az rest --method get --uri https://management.chinacloudapi.cn/subscriptions/{subscription_id}/resourceGroups/contoso/providers/Microsoft.Search/searchServices/contoso-search/sharedPrivateLinkResources/blob-pe?api-version=2020-08-01

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

{
      "name": "blob-pe",
      "properties": {
        "privateLinkResourceId": "/subscriptions/{subscription_id}/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 在专用环境中运行。你也可在门户中使用 JSON 编辑器设置执行环境。

注意

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

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

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

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

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

注意

若已具备现有索引器，你可将 executionEnvironment 设置为 private或在门户中使用 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。如果你没有设置此属性，并且索引器运行在过去成功了，这是因为搜索服务自行使用了一个私有环境。如果系统承受负载，搜索服务会将处理移出标准环境。
如果在创建共享专用链接时收到错误，请检查服务限制以验证是否低于层的配额。

后续步骤

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

通过