通过

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

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

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

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

Prerequisites

配置基于角色的访问

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

配置访问权限：

  1. 登录到 Azure 门户 并选择搜索服务。

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

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

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

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

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

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

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

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

获取服务信息

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

要获取您的服务信息：

  1. 登录到 Azure 门户 并选择搜索服务。

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

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

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

登录到 Azure

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

登录方法：

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

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

    az account show

  3. 如果活动订阅和租户对搜索服务无效，请更改变量。 可以在 Azure 门户中的搜索服务概述页上检查订阅 ID。 可以通过点击进入订阅来检查租户 ID。 在 Azure 门户中，租户 ID 称为 父管理组。 记下对搜索服务有效的值，并运行以下命令来更新本地环境。

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

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

注释

本部分演示了无键连接的基本 Python 模式。 如需全面指南，请参阅特定的快速入门或教程，例如快速入门：在 Azure AI 搜索中使用智能体检索。

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

若要使用 Python 进行连接，请执行以下作：

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

  2. 创建 .ipynb 文件。

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

    pip install azure-identity azure-search-documents

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

    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 搜索服务的无密钥连接。 然后使用 Visual Studio Code 中的 REST 与服务交互。

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

Prerequisites

配置基于角色的访问

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

配置访问权限：

  1. 登录到 Azure 门户 并选择搜索服务。

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

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

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

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

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

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

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

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

获取服务信息

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

要获取您的服务信息：

  1. 登录到 Azure 门户 并选择搜索服务。

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

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

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

登录到 Azure

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

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

    az account show

  2. 如果活动订阅和租户对搜索服务无效，请更改变量。 可以在 Azure 门户中的搜索服务概述页上检查订阅 ID。 可以通过点击进入订阅来检查租户 ID。 在 Azure 门户中，租户 ID 称为 父管理组。 记下对搜索服务有效的值，并运行以下命令来更新本地环境。

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

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

获取令牌

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

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

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

  2. 生成访问令牌。

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

  3. 复制令牌输出。

注释

本部分演示了无键连接的基本 REST 模式。 如需全面指南，请参阅特定的快速入门或教程，例如快速入门：在 Azure AI 搜索中使用智能体检索。

可以使用 Visual Studio Code 中的 REST 客户端扩展将请求发送到 Azure AI 搜索服务。 为了对请求进行身份验证，需要包含一个 Authorization 标头，并使用之前生成的 Microsoft Entra ID 令牌。

使用 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 错误，请按照以下故障排除步骤作：

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

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

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

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

  • 如果所有其他方法都失败，请重启设备以删除缓存的令牌，然后重复本快速入门中的步骤，首先从获取令牌开始。

相关内容