你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

注释

Azure AI 搜索可通过Azure门户、REST API 和Azure SDK获取。它也是 Foundry IQ 的基础；Foundry IQ 是一个托管式知识层，可将企业内容转化为供 Microsoft Foundry 门户中的智能体使用的、可复用且具备权限感知能力的知识库。

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

管理 REST API 在稳定且预览版中可用。如果要访问预览功能，请务必设置预览 API 版本。

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

所有管理 REST API 都有示例。如果本文未介绍任务，请参阅 API 参考。

提示

如果使用 CURL 调用管理 REST API，请确保将内容类型标头设置为 application/json： -H "Content-Type: application/json"。或者，如果要嵌入 JSON，可以使用 --JSON 标志。

先决条件

具有活动订阅的Azure帐户。免费创建帐户。
包含 REST 客户端的 Visual Studio Code。
Azure CLI获取访问令牌，如以下步骤中所述。你必须是Azure订阅中的所有者或管理员。

管理 REST API 调用通过Microsoft Entra ID进行身份验证。必须在请求和权限上提供访问令牌才能创建和配置资源。除了Azure CLI，还可以使用 Azure PowerShell 创建访问令牌。
1. 打开Azure CLI的命令行界面。
2. 登录到Azure订阅。如果有多个租户或订阅，请确保选择正确的租户或订阅。
```
az login
```
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 并选择 Extensions 磁贴。
搜索 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.azure.com/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: WESTUS2: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.azure.com/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": "North Central US",
        "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.azure.com/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.azure.com/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.azure.com/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 访问令牌的数据请求上的授权头。

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

若要专门使用基于角色的访问控制，请在第二个请求中将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.azure.com/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"
                }
            }
        }
    }

配置机密计算

机密计算是用于数据使用保护的可选计算类型。配置后，搜索服务将部署在机密 VM（DCasv5 或 DCesv5）而不是标准 VM 上。此计算类型还会对可计费用层级产生10%的附加费。有关详细信息，请参阅定价页。

对于日常使用，不需要机密计算。我们仅建议此计算类型符合严格的法规、合规性或安全要求。有关详细信息，请参阅机密计算用例。

计算类型在搜索服务的生存期内是固定的。若要永久配置机密计算，请将 computeType 属性设置为新服务上的 confidential。

### Configure confidential computing
@resource-group = PUT-YOUR-RESOURCE-GROUP-NAME-HERE
@search-service = PUT-YOUR-SEARCH-SERVICE-NAME-HERE
PUT https://management.azure.com/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": "basic"
        },
        "properties": {
            "computeType": "confidential"
        }
    }

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

如果使用客户管理的加密，如果希望搜索服务报告其符合性状态，则可以启用“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.azure.com/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"
            }
        }
    }

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

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

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

PATCH https://management.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/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.azure.com/subscriptions/{{subscription-id}}/resourcegroups?api-version=2021-04-01  HTTP/1.1
  Content-type: application/json
  Authorization: Bearer {{token}}

后续步骤

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

反馈

此页面是否有帮助？

Last updated on 2026-07-03