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

本文介绍如何为从 Azure AI Search 到虚拟网络中运行的 Azure 资源的专用出站连接配置 共享的专用链接。使用共享专用链接，搜索服务将连接到虚拟网络 IP 地址，而不是公共终结点。

共享专用链接是按使用情况计费的高级功能。有关详细信息，请参阅 Azure Private Link 定价。

注意

如果要为 SQL Managed Instance 设置专用索引器连接，请参阅为 SQL Managed Instance 创建共享专用链接。

先决条件

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

Azure AI Search 服务。要求因工作负荷而异：

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

Contributor 或 Owner 角色需要同时在 Azure AI 搜索和目标 Azure 资源上，或者需要以下特定权限：

资源	权限
Azure AI 搜索	`Microsoft.Search/searchServices/sharedPrivateLinkResources/write` `Microsoft.Search/searchServices/sharedPrivateLinkResources/read` `Microsoft.Search/searchServices/sharedPrivateLinkResources/operationStatuses/read`
其他 Azure 资源	批准专用终结点连接的权限。例如，在 Azure Storage 上，需要 `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 ⁸	`cognitiveservices_account`

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

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

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

⁴Microsoft.Web/sites 资源类型用于应用服务和Azure函数。在 Azure AI Search 的上下文中，使用 Azure 函数是更可能的方案。 Azure函数通常用于托管自定义技能的逻辑。 Azure函数具有消费、高级和专用应用服务托管计划。目前不支持 App Service Environment （ASE）、Azure Kubernetes Service (AKS) 和 Azure API Management。

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

⁸与Azure AI services的连接支持共享专用链接。对于 AI 扩充，Azure AI Search 连接到 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 客户端并设置获取共享的专用链接资源。查看现有的共享专用链接以确保不会复制某个链接。每个资源和子资源组合只能有一个共享专用链接。

@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=2025-05-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

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

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

PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{rg-name}}/providers/Microsoft.Search/searchServices/{{service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2025-05-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"

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

有关入门的说明，请参阅 manage with the 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。此示例适用于NoSQL的Azure Cosmos DB。

语法区分大小写，因此请确保组 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 Search到Azure资源的任何通信都源自专用 IP 地址和安全专用链接通道。
适用于资源类型的专用 DNS 区域，基于组 ID。通过部署此资源，可确保对专用资源的任何 DNS 查找都利用与专用终结点关联的 IP 地址。

2 - 批准专用终结点连接

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

在 Azure 存储上，使用私有终结点连接 - Put
在 Azure Cosmos DB 中使用专用终结点连接 - 创建或更新

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

打开 Azure PaaS 资源的 Networking 页。text
找到列出专用终结点连接的部分。以下示例适用于存储帐户。

Azure 门户的截图，显示专用节点连接窗格。
选择连接，然后选择“批准”。在Azure门户中更新状态可能需要几分钟时间。

Azure 门户的

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

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

Azure PaaS 网络页面中专用终结点链接的截图。

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

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

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

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

Azure 门户的

或者，还可以使用 Shared Private Link Resources - 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 在专用环境中运行。还可以在Azure门户中使用 JSON 编辑器设置执行环境。

注意

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

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

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

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

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

注意

如果已有索引器，可以通过 PUT API 更新它们，方法是将 executionEnvironment 设置为 private 或使用 Azure 门户中的 JSON 编辑器。

5 - 测试共享专用链接

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

对于索引器工作负载，connection string位于数据源定义中。数据源的示例可能如下所示：
```
 {
   "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": []
}

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

何时使用共享专用链接

Azure AI Search在以下情况下对其他Azure资源进行出站调用：

索引器与受支持的数据源的连接
索引器（技能集）连接到Azure Storage，用于缓存扩充、调试会话状态或写入知识存储。
用于计费目的的索引器（技能集）与 Azure AI 服务的连接
对Azure Key Vault的加密密钥请求
对Azure Functions或类似资源的自定义技能请求

共享专用链接仅适用于Azure到Azure连接。

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

一个共享的私有链接为：

使用Azure AI Search工具、API 或 SDK 创建
Azure资源所有者批准
Azure AI Search 在与特定 Azure 资源的专用连接中进行内部使用。

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

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

使用 Azure Private Link 和Azure AI Search有两种方案。

方案一：当与 Azure 建立outbound（索引器或知识库）连接需要专用连接时，创建共享专用链接。本文介绍了此方案。
方案二：为在虚拟网络中运行的客户端的专用入站连接配置搜索。

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

限制

在评估您的情境中共享的专用链接时，请记住以下约束：

共享专用链接中使用的多种资源类型目前是作为预览版提供的。如果要连接到预览资源（Azure Database for MySQL或Azure SQL Managed Instance），请使用管理 REST API 的预览版创建共享专用链接。建议使用最新的预览 API。
索引器执行必须使用特定于你的搜索服务的专用执行环境。多租户内容处理环境不支持专用终结点连接。本文将介绍如何根据此要求完成配置设置。
查看每个层的共享专用链接资源限制。
当前不支持种类 Microsoft.CognitiveServices/accounts 的资源类型 AIServices。

疑难解答

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

后续步骤

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

Last updated on 2026-04-22

共用方式為