共用方式為

快速入门：连接到搜索服务

在本快速入门中，你将使用基于角色的访问控制（RBAC）和Microsoft Entra ID建立与Azure AI Search服务的无密钥连接。 然后，在Visual Studio Code中使用Python来与服务交互。

无密钥连接通过精细权限和基于标识的身份验证提供增强的安全性。 我们不建议使用硬编码的 API 密钥，但如果您倾向于使用，请参阅 使用密钥连接到 Azure AI 搜索。

先决条件

配置基于角色的访问

在本部分中，将在Azure AI Search服务上启用 RBAC，并为创建、加载和查询搜索对象分配必要的角色。 有关这些步骤的详细信息，请参阅 使用角色连接到 Azure AI Search。

配置访问权限：

  1. 在 Azure 门户中，转到你的搜索服务。

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

  3. 如果需要时间将客户端转换为 RBAC，请选择 “基于角色的访问控制 ”或 “两者 ”。

    Azure门户中的访问控制选项截图。

  4. 在左窗格中，选择“访问控制”（IAM）。

  5. 选择添加>添加角色分配。

    Azure 门户中用于添加角色分配的下拉菜单截图。

  6. 将 搜索服务参与者 角色分配给用户帐户或托管标识。

  7. 重复 搜索索引数据参与者的角色分配。

获取服务信息

在本部分中，检索Azure AI Search服务的订阅 ID 和终结点。 如果只有一个订阅，请跳过订阅 ID，并仅检索终结点。 可以在本快速入门指南其余部分中使用这些值。

要获取您的服务信息：

  1. 在 Azure 门户中，转到你的搜索服务。

  2. 在左窗格中，选择“ 概述”。

  3. 记下订阅 ID 和终结点。

    Azure门户中的订阅ID和终结点的截图。

登录到 Azure

在连接到 Azure AI Search 服务之前，请使用 Azure CLI 登录到包含该服务的订阅。 此步骤将建立您的 Microsoft Entra 标识，DefaultAzureCredential 在下一部分中使用它来对请求进行身份验证。

登录方法：

  1. 在本地系统上，打开命令行工具。

  2. 检查本地环境中的活动订阅和租户。

    az account show

  3. 如果活动订阅和租户对您的搜索服务无效，请运行以下命令来更新它们的值。 可以在Azure门户中的搜索服务 Overview 页上找到订阅 ID。 若要查找租户 ID，请在“概述”页上选择订阅的名称，然后找到“父管理组”值。

     az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>

注释

本部分说明了无键连接的基本Python模式。

可以使用Visual Studio Code中的Python笔记本将请求发送到Azure AI Search服务。 对于请求身份验证，请使用 Azure 标识库中的 DefaultAzureCredential 类。

若要使用Python进行连接，请使用：

  1. 在本地系统上，打开Visual Studio Code。

  2. 创建 .ipynb 文件。

  3. 创建一个代码单元格来安装azure-identity和azure-search-documents库。

    pip install azure-identity azure-search-documents

  4. 创建另一个代码单元以进行身份验证并连接到搜索服务。

    import json
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

service_endpoint = "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE"
credential = DefaultAzureCredential()
client = SearchIndexClient(endpoint = service_endpoint, credential = credential)

# List existing indexes
indexes = client.list_indexes()

for index in indexes:
   index_dict = index.as_dict()
   print(json.dumps(index_dict, indent = 2))

  5. 将service_endpoint设置为在获取服务信息中获得的值。

  6. 选择“运行全部”以运行这两个代码单元。

    输出应列出搜索服务上的现有索引（如果有），指示连接成功。

解决并排查 401 错误

如果遇到 401 错误，请按照以下故障排除步骤作：

  • 重新查看 配置基于角色的访问。 搜索服务必须启用 基于角色的访问控制 或 两者 。 订阅或资源组级别的策略可能会替代角色分配。

  • 重新访问 登录 Azure。 必须登录到包含搜索服务的订阅。

  • 请确保终结点变量包含周围的引号。

  • 如果所有其他操作都失败，请重启设备以删除缓存的令牌，然后从 登录 Azure 开始，重复本快速入门中的步骤。

在本快速入门中，你将使用基于角色的访问控制（RBAC）和Microsoft Entra ID建立与Azure AI Search服务的无密钥连接。 然后，在Visual Studio Code中使用 REST 来与服务交互。

无密钥连接通过精细权限和基于标识的身份验证提供增强的安全性。 我们不建议使用硬编码的 API 密钥，但如果您倾向于使用，请参阅 使用密钥连接到 Azure AI 搜索。

先决条件

配置基于角色的访问

在本部分中，将在Azure AI Search服务上启用 RBAC，并为创建、加载和查询搜索对象分配必要的角色。 有关这些步骤的详细信息，请参阅 使用角色连接到 Azure AI Search。

配置访问权限：

  1. 在 Azure 门户中，转到你的搜索服务。

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

  3. 如果需要时间将客户端转换为 RBAC，请选择 “基于角色的访问控制 ”或 “两者 ”。

    Azure门户中的访问控制选项截图。

  4. 在左窗格中，选择“访问控制”（IAM）。

  5. 选择添加>添加角色分配。

    Azure 门户中用于添加角色分配的下拉菜单截图。

  6. 将 搜索服务参与者 角色分配给用户帐户或托管标识。

  7. 重复 搜索索引数据参与者的角色分配。

获取服务信息

在本部分中，检索Azure AI Search服务的订阅 ID 和终结点。 如果只有一个订阅，请跳过订阅 ID，并仅检索终结点。 可以在本快速入门指南其余部分中使用这些值。

要获取您的服务信息：

  1. 在 Azure 门户中，转到你的搜索服务。

  2. 在左窗格中，选择“ 概述”。

  3. 记下订阅 ID 和终结点。

    Azure门户中的订阅ID和终结点的截图。

登录到 Azure

在连接到 Azure AI Search 服务之前，请使用 Azure CLI 登录到包含该服务的订阅。

登录方法：

  1. 在本地系统上，打开命令行工具。

  2. 检查本地环境中的活动订阅和租户。

    az account show

  3. 如果活动订阅和租户对您的搜索服务无效，请运行以下命令来更新它们的值。 可以在Azure门户中的搜索服务 Overview 页上找到订阅 ID。 若要查找租户 ID，请在“概述”页上选择订阅的名称，然后找到“父管理组”值。

     az account set --subscription <your-subscription-id>

 az login --tenant <your-tenant-id>

获取令牌

REST API 调用需要包含Microsoft Entra ID令牌。 在下一部分中，使用此令牌对请求进行身份验证。

若要获取令牌，请执行以下步骤：

  1. 使用相同的命令行工具生成访问令牌。

    az account get-access-token --scope https://search.azure.cn/.default --query accessToken --output tsv

  2. 记下令牌输出。

注释

本部分演示了无键连接的基本 REST 模式。

可以使用 Visual Studio Code中的 REST 客户端扩展将请求发送到Azure AI Search服务。 对于请求身份验证，请包含一个带有您之前生成的 Microsoft Entra ID 令牌的 Authorization 标头。

使用 REST 进行连接：

  1. 在本地系统上，打开Visual Studio Code。

  2. 创建 .rest 或 .http 文件。

  3. 将以下变量和请求粘贴到文件中。

    @baseUrl = PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE
@token = PUT-YOUR-PERSONAL-IDENTITY-TOKEN-HERE

### List existing indexes
GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
   Content-Type: application/json
   Authorization: Bearer {{token}}

  4. 将@baseUrl设置为在获取服务信息中获得的值。

  5. 将 @token 设置为在 获取令牌中获得的值。

  6. 在### List existing indexes下，选择“发送请求”。

    应收到一个 HTTP/1.1 200 OK 响应，指示与搜索服务的成功连接。

解决并排查 401 错误

如果遇到 401 错误，请按照以下故障排除步骤作：

  • 重新查看 配置基于角色的访问。 搜索服务必须启用 基于角色的访问控制 或 两者 。 订阅或资源组级别的策略可能会替代角色分配。

  • 重新访问 登录 Azure。 必须登录到包含搜索服务的订阅。

  • 请确保终结点和令牌变量没有周围的引号或额外的空格。

  • 确保令牌在请求标头中不包含 @ 符号。 例如，如果变量是 @token，则请求中的引用应为 {{token}}。

  • 如果所有其他操作都失败，请重启设备以删除缓存的令牌，然后从 登录 Azure 开始，重复本快速入门中的步骤。

相关内容

  • Last updated on