使用 REST API 管理 Azure AI 搜索服务

项目
10/21/2024

在本文中，了解如何使用管理 REST API 创建和配置 Azure AI 搜索服务。只能保证管理 REST API 会提供对预览功能的抢先访问权限。

管理 REST API 目前以稳定的预览版形式提供。如果你要访问预览版功能，请务必设置 API 预览版。

创建或更新服务
为数据平面启用 Azure 基于角色的访问控制
强制实施客户管理的密钥策略
禁用将数据推送到外部资源的工作负载
创建查询密钥
重新生成管理密钥
列出专用终结点连接
列出搜索操作
删除搜索服务

所有管理 REST API 都有示例。如果本文未涵盖某项任务，请参阅 API 参考。

先决条件

Azure 订阅 - 创建试用版订阅。
包含 REST 客户端的 Visual Studio Code。
用于获取访问令牌的 Azure CLI。你必须是你的 Azure 订阅中的所有者或管理员。

获取访问令牌

将会通过 Microsoft Entra ID 对管理 REST API 调用进行身份验证。你需要在请求时提供访问令牌，以及创建和配置资源的权限。

你可以使用 Azure CLI 或 Azure PowerShell 创建访问令牌。

打开 Azure CLI 的命令行界面。

登录到 Azure 订阅。

az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.

获取租户 ID 和订阅 ID。如果有多个租户或订阅，请确保使用正确的那个。
```
az account show
```

获取访问令牌。

az account get-access-token --query accessToken --output tsv

你应拥有租户 ID、订阅 ID 和持有者令牌。将这些值粘贴到下一步中创建的 .rest 或 .http 文件中。

设置 Visual Studio Code

如果不熟悉 Visual Studio Code 的 REST 客户端，本部分包括设置，让你能够完成本快速入门中的任务。

启动 Visual Studio Code 并选择“扩展”磁贴。
搜索 REST 客户端并选择“安装”。
打开或创建文件扩展名为 .rest 或 .http 的文件。

为你在上一步中检索的值提供变量。

@tenantId = PASTE-YOUR-TENANT-ID-HERE
@subscriptionId = PASTE-YOUR-SUBSCRIPTION-ID-HERE
@token = PASTE-YOUR-TOKEN-HERE

通过列出订阅中的搜索服务来验证会话是否正常运行。

 ### List search services
 GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
      Content-type: application/json
      Authorization: Bearer {{token}}

选择“发送请求”。相邻窗格中应该会显示响应。如果你有现有的搜索服务，则它们会被列出。否则，该列表为空，但只要 HTTP 代码为“200 正常”，就可完成后续步骤。

HTTP/1.1 200 OK
Cache-Control: no-cache
Pragma: no-cache
Content-Length: 22068
Content-Type: application/json; charset=utf-8
Expires: -1
x-ms-ratelimit-remaining-subscription-reads: 11999
x-ms-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-correlation-request-id: f47d3562-a409-49d2-b9cd-6a108e07304c
x-ms-routing-request-id: chinanorth2:20240314T012052Z:f47d3562-a409-49d2-b9cd-6a108e07304c
Strict-Transport-Security: max-age=31536000; includeSubDomains
X-Content-Type-Options: nosniff
X-Cache: CONFIG_NOCACHE
X-MSEdge-Ref: Ref A: 12401F1160FE4A3A8BB54D99D1FDEE4E Ref B: CO6AA3150217011 Ref C: 2024-03-14T01:20:52Z
Date: Thu, 14 Mar 2024 01:20:52 GMT
Connection: close

{
  "value": [ . . . ]
}

创建或更新服务

在当前订阅下创建或更新搜索服务。此示例为搜索服务名称和区域使用变量，这些变量尚未定义。请直接提供名称，或者向集合添加新变量。

### Create a search service (provide an existing resource group)
@resource-group = my-rg
@search-service-name = my-search
PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "China North",
        "sku": {
            "name": "basic"
        },
        "properties": {
            "replicaCount": 1,
            "partitionCount": 1,
            "hostingMode": "default"
        }
      }

创建 S3HD 服务

若要创建 S3HD 服务，请使用组合 sku 和 hostingMode 属性。将 sku 设置为 standard3，将“hostingMode”设置为 HighDensity。

@resource-group = my-rg
@search-service-name = my-search
PUT https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "location": "{{region}}",
        "sku": {
          "name": "standard3"
        },
        "properties": {
          "replicaCount": 1,
          "partitionCount": 1,
          "hostingMode": "HighDensity"
        }
    }

为数据平面配置基于角色的访问

适用于：搜索索引数据参与者、搜索索引数据读取者、搜索服务参与者

在此步骤中配置搜索服务，以识别提供 OAuth2 访问令牌的数据请求上的授权头。

若要对数据平面操作使用基于角色的访问控制，请将 authOptions 设置为 aadOrApiKey 并发送请求。

若要以独占方式使用基于角色的访问控制，请跟进提出第二个请求，关闭 API 密钥身份验证，这次将 disableLocalAuth 设置为 true。

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "properties": {
            "disableLocalAuth": false,
            "authOptions": {
                "aadOrApiKey": {
                    "aadAuthFailureMode": "http401WithBearerChallenge"
                }
            }
        }
    }

强制实施客户管理的密钥策略

如果使用的是客户管理的加密，且希望搜索服务报告其合规性状态，则可以启用“encryptionWithCMK”并将“强制”设置为“启用”。

启用此策略后，如果未提供加密密钥，则创建包含敏感数据（例如数据源中的连接字符串）的对象的任何 REST 调用将失败："Error creating Data Source: "CannotCreateNonEncryptedResource: The creation of non-encrypted DataSources is not allowed when encryption policy is enforced."

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

     {
        "properties": {
            "encryptionWithCmk": {
                "enforcement": "Enabled"
            }
        }
    }

禁用将数据推送到外部资源的工作负载

Azure AI 搜索在更新知识存储、保存调试会话状态或缓存扩充内容时写入外部数据源。以下示例在服务级别禁用这些工作负载。

### disable-external-access
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

     {
        "properties": {
            "publicNetworkAccess": "Disabled"
        }
    }

删除搜索服务

### delete a search service
DELETE https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出管理员 API 密钥

### List admin keys
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

重新生成管理 API 密钥

一次只能重新生成一个管理员 API 密钥。

### Regnerate admin keys
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/regenerateAdminKey/primary?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

创建查询 API 密钥

### Create a query key
@query-key-name = myQueryKey
POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/createQueryKey/{name}?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出专用终结点连接

### List private endpoint connections
GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}/privateEndpointConnections?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出搜索操作

### List search operations
GET https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups?api-version=2021-04-01 HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

后续步骤

配置搜索服务后，接下来的步骤包括使用门户、REST API 或 Azure SDK 创建索引或查询索引。

通过