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

2025-09-19

了解如何使用管理 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 创建访问令牌。
1. 打开 Azure CLI 的命令行界面。
2. 登录到 Azure 订阅。如果有多个租户或订阅，请确保选择正确的项。
```
az cloud set -n AzureChinaCloud
az login
# az cloud set -n AzureCloud   //means return to Public Azure.
```
3. 获取租户 ID 和订阅 ID。
```
az account show
```
4. 获取访问令牌。
```
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 的文件。

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

@tenant-id = PUT-YOUR-TENANT-ID-HERE
@subscription-id = PUT-YOUR-SUBSCRIPTION-ID-HERE
@token = PUT-YOUR-TOKEN-HERE

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

 ### List search services
 GET https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/providers/Microsoft.Search/searchServices?api-version=2025-05-01  HTTP/1.1
      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 = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

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

升级服务

某些 Azure AI 搜索功能仅适用于新服务。

### Upgrade a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/upgrade?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

更改定价层

如果需要更多或更少的容量，可以切换到其他定价层。目前，您只能在基本和标准（S1、S2 和 S3）层之间切换。使用属性 sku 指定新层。

### Change pricing tiers
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

    {
        "sku": {
            "name": "standard2"
        }
    }

创建 S3HD 服务

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

### Create an S3HD service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PUT https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourceGroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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。

### Configure role-based access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

PATCH https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-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."

### Enforce a customer-managed key policy
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

禁用语义排序器

默认情况下，语义排名器在免费计划中启用，每月最多允许 1,000 个请求免费。可以在服务级别锁定该功能，以防止使用。

### Disable semantic ranker
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

     {
        "properties": {
            "semanticSearch": "Disabled"
        }
    }

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

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

### Disable external access
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

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

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

删除搜索服务

### Delete a search service
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

DELETE https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出管理员 API 密钥

### List admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/listAdminKeys?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

重新生成管理 API 密钥

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

### Regnerate admin keys
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

POST https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/regenerateAdminKey/primary?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

创建查询 API 密钥

### Create a query key
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
@query-key = PUT-YOUR-QUERY-KEY-NAME-HERE

POST https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/createQueryKey/{query-key}?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出专用终结点连接

### List private endpoint connections
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE

GET https://management.chinacloudapi.cn/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service}}/privateEndpointConnections?api-version=2025-05-01  HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}

列出搜索操作

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

后续步骤

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

通过