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

项目
11/18/2024

本文介绍如何在 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 列为一个选项，但门户目前不支持 SQL 托管实例使用的扩展 URL 格式。

先决条件

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

注意

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

1 - 检索连接信息

检索托管实例的 FQDN，包括 DNS 区域。 DNS 区域是 SQL 托管实例域名的一部分。例如，如果 SQL 托管实例的 FQDN 为 my-sql-managed-instance.00000000000.database.chinacloudapi.cn，则 DNS 区域为 00000000000。

在 Azure 门户中，找到 SQL 托管实例对象。
在“概述”选项卡上，找到“主机”属性。复制 FQDN 的 DNS 区域部分，以便在下一步骤中使用。
在“连接字符串”选项卡上，复制 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=2024-06-01-preview --body @create-pe.json
```
提供Azure AI 搜索资源的订阅 ID、资源组名称和服务名称。

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

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

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

4 - 批准专用终结点连接

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

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

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

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

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

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

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

对于此步骤，可以使用导入数据向导，但生成的索引器对于此场景无效。需要按照此步骤所述修改索引器 JSON 属性，使其符合此场景。然后，需要重置并重新运行索引器，以使用更新的索引器全面测试管道。

本文假设有一个 REST 客户端，并使用 REST API 来方便查看所有属性。如前所述，对索引器和数据源的 REST API 调用使用的是搜索 REST API，而不是用于创建共享专用链接的管理 REST API。这两个 REST API 的语法和 API 版本不相同。

像平时为 Azure SQL 所做的那样创建数据源定义。对于托管实例，连接字符串的格式略有不同，但其他属性与配置数据源到 Azure SQL 数据库的连接的方式相同。

提供之前复制的连接字符串并指定初始目录。

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.public.0000000000.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
 }

创建索引器定义，将索引器执行环境设置为“专用”。

索引器执行发生在特定于搜索服务的专用环境中，或者发生在内部用于为多个客户卸载昂贵的技能集处理的多租户环境中。通过专用终结点连接时，索引器执行环境必须是专用的。

 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 客户端连接到搜索服务。

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

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

通过