使用密钥连接到 Azure AI 搜索

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

2. 在左窗格中，选择“设置>”以查看管理员和查询密钥。

   

运行以下命令，分别返回管理员和查询 API 密钥。 有关 REST 的帮助，请参阅 使用 REST API 管理 Azure AI 搜索服务。

1. 返回管理密钥：

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

2. 返回查询密钥：

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

参考：管理密钥 - 获取、 查询密钥 - 按搜索服务列出

使用用于 Python 的 Azure SDK 以编程方式检索 API 密钥。 安装管理 SDK：

pip install azure-mgmt-search azure-identity

运行以下代码以返回管理员和查询 API 密钥：

import os
from azure.identity import DefaultAzureCredential
from azure.mgmt.search import SearchManagementClient

# Set up variables
subscription_id = os.environ["AZURE_SUBSCRIPTION_ID"]
resource_group = "your-resource-group"
search_service_name = "your-search-service"

# Create the management client
credential = DefaultAzureCredential()
client = SearchManagementClient(credential, subscription_id)

# Get admin keys
admin_keys = client.admin_keys.get(resource_group, search_service_name)
print(f"Primary admin key: {admin_keys.primary_key}")
print(f"Secondary admin key: {admin_keys.secondary_key}")

# Get query keys
query_keys = client.query_keys.list_by_search_service(resource_group, search_service_name)
for key in query_keys:
    print(f"Query key '{key.name}': {key.key}")

Reference：SearchManagementClient | AdminKeys | QueryKeys

运行以下命令，分别返回管理员和查询 API 密钥。 有关 PowerShell 的帮助，请参阅 使用 PowerShell 管理 Azure AI 搜索服务。

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 密钥。 有关 Azure CLI 的帮助，请参阅 使用 Azure CLI 管理 Azure AI 搜索服务。

1. 返回管理密钥：

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

2. 返回查询密钥：

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

回想一下，密钥身份验证默认已启用，并支持数据平面作，例如索引和查询。

但是，如果你禁用 API 密钥并设置角色分配，则 Azure 门户会改用角色分配。

在请求头中设置管理密钥。 不能在 URI 或请求正文中传递管理密钥。

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

@baseUrl=https://my-demo-search-service.search.azure.cn
@adminApiKey=aaaabbbb-0000-cccc-1111-dddd2222eeee

### 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}}

最佳做法是将 API 密钥设置为环境变量，但为简单起见，此示例将其显示为字符串。 该示例使用查询 API 密钥来进行查询操作。

# Import libraries
from azure.search.documents import SearchClient
from azure.core.credentials import AzureKeyCredential
from azure.identity import DefaultAzureCredential, AzureAuthorityHosts

# Variables for endpoint, keys, index
search_endpoint: str = "https://<Put your search service NAME here>.search.azure.cn/"
credential = AzureKeyCredential("Your search service query key")
index_name: str = "hotels-quickstart-python"

# Set up the client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Run the query
results =  search_client.search(query_type='simple',
    search_text="*" ,
    select='HotelName,Description,Tags',
    include_total_count=True)

print ('Total Documents Matching Query:', results.get_count())
for result in results:
    print(result["@search.score"])
    print(result["HotelName"])
    print(result["Tags"])
    print(f"Description: {result['Description']}")

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

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

使用变量存储完全限定的查询。

$url = '<YOUR-SEARCH-SERVICE>/indexes/hotels-quickstart/docs?api-version=2025-09-01&search=attached restaurant&searchFields=Description,Tags&$select=HotelId,HotelName,Tags,Description&$count=true'

将请求发送到搜索服务：

Invoke-RestMethod -Uri $url -Headers $headers | ConvertTo-Json

有关其他作的更多脚本示例，请参阅 快速入门：使用 REST API 在 PowerShell 中创建 Azure AI 搜索索引。

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

2. 在左窗格中，选择“设置>”以查看 API 密钥。

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

   

在管理 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

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

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