使用 REST API 管理 Azure AI 搜索服务
在本文中,了解如何使用管理 REST API 创建和配置 Azure AI 搜索服务。 只能保证管理 REST API 会提供对预览功能的抢先访问权限。
管理 REST API 目前以稳定的预览版形式提供。 如果你要访问预览版功能,请务必设置 API 预览版。
所有管理 REST API 都有示例。 如果本文未涵盖某项任务,请参阅 API 参考。
先决条件
获取访问令牌
将会通过 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=2024-07-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=2024-07-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=2024-07-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=2024-07-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=2024-07-01 HTTP/1.1
Content-type: application/json
Authorization: Bearer {{token}}
{
"properties": {
"encryptionWithCmk": {
"enforcement": "Disabled",
"encryptionComplianceStatus": "Compliant"
},
}
}
禁用将数据推送到外部资源的工作负载
Azure AI 搜索在更新知识存储、保存调试会话状态或缓存扩充内容时写入外部数据源。 以下示例在服务级别禁用这些工作负载。
### disable-external-access
PATCH https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2024-07-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=2024-07-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=2024-07-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=2024-07-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=2024-07-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=2024-07-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}}