使用密钥连接到 Azure AI 搜索

如何在 REST 调用中使用 API 密钥：

在请求头中设置管理密钥。 不能在 URI 或请求正文中传递管理密钥。 管理密钥用于创建-读取-更新-删除操作，以及向搜索服务本身发出的请求，例如通过 LIST 列出索引或通过 GET 获取服务统计信息。

下面是对“创建索引”请求使用管理 API 密钥的示例：

### Create an index
POST {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

在 POST 的请求标头或 GET 的 URI 上设置查询密钥。 查询键用于针对 index/docs 集合的操作：搜索文档、自动完成、建议或通过 GET 获取文档。

下面是对搜索文档 (GET) 请求的查询 API 密钥用法示例：

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2025-09-01&api-key={{queryApiKey}}

如何在 PowerShell 中使用 API 密钥：

使用以下语法在请求头中设置 API 密钥：

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

可以在快速入门：使用 REST API 在 PowerShell 中创建 Azure AI 搜索索引中找到演示如何对各种操作使用 API 密钥的脚本示例。

如何在 Azure 门户中使用 API 密钥：

密钥身份验证适用于数据平面操作，例如索引和查询。 默认情况下，它已启用。 但是，如果你禁用 API 密钥并设置角色分配，则 Azure 门户会改用角色分配。

1. 登录到 Azure 门户并查找你的搜索服务。

2. 在“设置”下，选择“密钥”以查看管理密钥和查询密钥。

1. 安装 Az.Search 模块：

   Install-Module Az.Search
   

2. 返回管理密钥：

   Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
   

3. 返回查询密钥：

   Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>
   

使用以下命令分别返回管理密钥和查询 API 密钥：

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

在管理 REST API 中使用列出管理密钥或列出查询密钥返回 API 密钥。

必须具有有效的角色分配才能返回或更新 API 密钥。 有关使用 REST API 满足角色要求的指导，请参阅使用 REST API 管理 Azure AI 搜索服务。

POST https://management.chinacloudapi.cn/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2025-05-01

1. 登录到 Azure 门户并查找你的搜索服务。

2. 在“设置”下，选择“密钥”以查看 API 密钥。

3. 在“管理查询密钥”下，使用已为服务生成的查询密钥，或创建新的查询密钥。 默认查询密钥未命名，但生成的其他查询密钥可命名以便于管理。

   

可在创建或删除查询密钥中找到演示 API 密钥用法的脚本示例。

可在创建或删除查询密钥中找到演示查询密钥用法的脚本示例。

在管理 REST API 中使用创建查询密钥。

必须具有有效的角色分配才能创建或管理 API 密钥。 有关使用 REST API 满足角色要求的指导，请参阅使用 REST API 管理 Azure AI 搜索服务。

POST https://management.chinacloudapi.cn/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2025-05-01