从 Azure AI 搜索为 SQL 托管实例创建共享专用链接

2025-08-13

本文介绍如何在 Azure AI 搜索中配置索引器，以便与虚拟网络中运行的 SQL 托管实例建立专用连接。专用连接通过共享专用链接和 Azure 专用链接进行。

在与托管实例的专用连接上，该实例的完全限定域名 (FQDN) 必须包含 DNS 区域。目前，只有 Azure AI 搜索管理 REST API 提供接受 DNS 区域规范的 dnsZonePrefix 参数。

尽管你可以直接调用管理 REST API，但使用 Azure CLI az rest 模块从命令行发送管理 REST API 调用会更方便。本文结合使用 Azure CLI 和 REST 来设置专用链接。

注意

本文介绍如何在 Azure 门户中获取属性和确认步骤。但是，在为 SQL 托管实例创建共享专用链接时，请务必使用 REST API。尽管“网络”选项卡将 Microsoft.Sql/managedInstances 列为一个选项，但 Azure 门户目前不支持 SQL 托管实例使用的扩展 URL 格式。

先决条件

Azure CLI
Azure AI 搜索、基本或更高版本。如果你正在使用 AI 扩充和技能组，请使用“标准 2”(S2) 或更高的层。有关详细信息，请参阅服务限制。
Azure SQL 托管实例，配置为在虚拟网络中运行。
你应该对 Azure AI 搜索和 SQL 托管实例至少拥有参与者权限。
Azure SQL 托管实例连接字符串。共享专用链接目前不支持托管标识。连接字符串必须包含用户名和密码。

注意

共享专用链接可通过 Azure 专用链接定价计费，费用根据使用量来开具发票。

1 - 检索连接信息

在本部分，请从主机名和连接字符串获取 DNS 区域。

在 Azure 门户中，找到 SQL 托管实例对象。
在“概述”选项卡上，找到“主机”属性。复制 FQDN 的“DNS 区域”部分，以便在下一步骤中使用。 DNS 区域是 SQL 托管实例域名的一部分。例如，如果 SQL 托管实例的 FQDN 为 my-sql-managed-instance.a1b22c333d44.database.chinacloudapi.cn，则 DNS 区域为 a1b22c333d44。
在“连接字符串”选项卡上，复制 ADO.NET 连接字符串，以便在后续步骤中使用。在测试专用连接时，需要使用此字符串建立数据源连接。

有关连接属性的详细信息，请参阅创建 Azure SQL 托管实例。

2 - 创建请求的正文

使用文本编辑器为共享专用链接创建 JSON。
```
{
    "name": "{{shared-private-link-name}}",
    "properties": {
        "privateLinkResourceId": "/subscriptions/{{target-resource-subscription-ID}}/resourceGroups/{{target-resource-rg}}/providers/Microsoft.Sql/managedInstances/{{target-resource-name}}",
        "dnsZonePrefix": "a1b22c333d44",
        "groupId": "managedInstance",
        "requestMessage": "please approve"
    }
}
```
为共享专用链接提供有意义的名称。共享专用链接将与其他专用终结点一起显示。 “shared-private-link-for-search”之类的名称可以提示你如何使用该专用链接。

在“dnsZonePrefix”中粘贴你在前面步骤中检索到的 DNS 区域名称。

编辑“privateLinkResourceId”，用有效值替换占位符。提供有效订阅 ID、资源组名称和托管实例名称。
在本地将该文件保存为 create-pe.json（或使用其他名称，在下一步骤中请记得更新 Azure CLI 语法）。
在 Azure CLI 中，键入 dir 以记下该文件的当前位置。

3 - 创建共享专用链接

在命令行中，使用 az login 登录到 Azure。
如果你有多个订阅，请确保使用所需的订阅：az account show。

若要设置订阅，请使用 az account set --subscription {{subscription ID}}
调用 az rest 命令以使用 Azure AI 搜索的管理 REST API。

由于 SQL 托管实例的共享专用链接支持目前仍作为预览版提供，因此需要使用管理 REST API 预览版。请使用 2021-04-01-preview 或更高版本的预览版 API 执行此步骤。建议使用最新的预览版 API 版本。
```
az rest --method put --uri https://management.chinacloudapi.cn/subscriptions/{{search-service-subscription-ID}}/resourceGroups/{{search service-resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/sharedPrivateLinkResources/{{shared-private-link-name}}?api-version=2025-05-01-preview --body @create-pe.json
```
提供Azure AI 搜索资源的订阅 ID、资源组名称和服务名称。

提供在 JSON 正文中指定的共享专用链接名称。

如果你从当前文件位置导航到了别处，请提供 create-pe.json 文件的路径。可以在命令行中键入 dir 以确认该文件位于当前目录。
运行命令。

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

可以在 Azure 门户中检查共享专用链接的状态。在搜索服务页上的“设置”>“属性”下向下滚动，以查找共享专用链接资源并查看 JSON 值。当配置状态从“待处理”更改为“成功”时，可以继续进行下一步。

4 - 批准专用终结点连接

在 SQL 托管实例端，资源所有者必须批准你创建的专用连接请求。

在 Azure 门户中，打开托管实例的安全性>专用终结点连接。
找到列出专用终结点连接的部分。
选择连接，然后选择“批准”。状态可能需要几分钟时间才会在 Azure 门户中更新。

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

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

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

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

现在可以配置索引器及其数据源，以使用托管实例的出站专用连接。

本文假设有一个 REST 客户端，因此使用 REST API。

像平时为 Azure SQL 所做的那样创建数据源定义。默认情况下，托管实例侦听端口 3342，但在虚拟网络上侦听端口 1433。

提供前面复制的连接字符串，并将初始目录设置为数据库名称。

POST https://myservice.search.azure.cn/datasources?api-version=2024-07-01
 Content-Type: application/json
 api-key: admin-key
 {
     "name" : "my-sql-datasource",
     "description" : "A database for testing Azure AI Search indexes.",
     "type" : "azuresql",
     "credentials" : { 
         "connectionString" : "Server=tcp:contoso.a1b22c333d44.database.chinacloudapi.cn,1433;Persist Security Info=false; User ID=<your user name>; Password=<your password>;MultipleActiveResultsSets=False; Encrypt=True;Connection Timeout=30;Initial Catalog=<your database name>"
        },
     "container" : { 
         "name" : "Name of table or view to index",
         "query" : null (not supported in the Azure SQL indexer)
         },
     "dataChangeDetectionPolicy": null,
     "dataDeletionDetectionPolicy": null,
     "encryptionKey": null
 }

创建索引器定义，将索引器 executionEnvironment 设置为“private”。

索引器执行发生在专属于搜索服务的私有执行环境中，或者是在 Azure 托管的多租户环境中，用于分担多个客户的昂贵技能集处理。通过专用终结点连接时，索引器执行环境必须是专用的。

 POST https://myservice.search.azure.cn/indexers?api-version=2024-07-01
  Content-Type: application/json
  api-key: admin-key
    {
     "name": "indexer",
     "dataSourceName": "my-sql-datasource",
     "targetIndexName": "my-search-index",
     "parameters": {
         "configuration": {
             "executionEnvironment": "private"
         }
     },
     "fieldMappings": []
     }

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

可以在 Azure 门户中或使用索引器状态 API 监视索引器的状态。

可以使用 Azure 门户中的搜索浏览器来检查索引的内容。

7 - 测试共享专用链接

如果你在上一步骤中运行了索引器并且成功为托管实例中的内容编制了索引，则测试已经成功。但是，如果索引器失败或索引中没有内容，则你可以修改对象，并通过选择可以从索引器调用出站请求的任何客户端来重复测试。

一种简单的做法是在 Azure 门户中运行索引器，但你也可尝试使用 REST 客户端和 REST API 来提高精度。假设未同时为搜索服务配置专用连接，则可通过公共 Internet 将 REST 客户端连接到 Azure AI 搜索。

下面是有关测试的几项提醒：

如果使用 REST 客户端，请使用管理 REST API 和 2021-04-01-Preview API 版本创建共享专用链接。使用搜索 REST API 和稳定的 API 版本创建和调用索引器与数据源。
可以使用导入数据向导创建索引器、数据源和索引。但是，生成的索引器没有正确的执行环境设置。
可以在 Azure 门户中编辑数据源和索引器 JSON 以更改属性，包括执行环境和连接字符串。
可以在 Azure 门户中重置和重新运行索引器。重置对于此场景非常重要，因为这会强制对所有文档进行完全的重新处理。
可以使用搜索浏览器来检查索引的内容。

共用方式為