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

快速入门：在不使用密钥的情况下进行连接

项目
12/27/2024

将 Azure AI 搜索配置为使用 Microsoft Entra ID 身份验证和基于角色的访问控制 (RBAC)，以便使用 Jupyter 笔记本或 REST 客户端与搜索服务进行交互，以从本地系统进行连接而无需 API 密钥。

如果你已逐步学习了使用 API 密钥进行连接的其他快速入门，可以通过本快速入门了解如何切换到基于标识的身份验证，以避免出现像示例代码中使用硬编码密钥的情况。

先决条件

Azure 订阅。免费创建一个。
Azure AI 搜索，任何区域或层级，但需要“基本”或更高层级才能为 Azure AI 搜索配置托管标识。
一个命令行工具，如 PowerShell 或 Bash，以及 Azure CLI。

步骤 1：获取 Azure 订阅和租户 ID

如果你有多个订阅或租户，则需要执行此步骤。

获取搜索服务的 Azure 订阅和租户：
1. 登录到 Azure 门户并导航到搜索服务。
2. 请注意“概述”>“Essentials”中的订阅名称和 ID。
3. 现在，选择订阅名称以在下一页上显示父管理组（租户 ID）。
现在，你已知道 Azure AI 搜索所在的是哪个订阅和租户。切换到本地设备和命令提示符，并识别设备上的活动 Azure 订阅和租户：
```
az account show
```
如果活动订阅和租户与上一步中获取的信息不同，请更改订阅 ID。接下来，使用在上一步中找到的租户 ID 登录到 Azure：
```
 az account set --subscription <your-subscription-id>

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

步骤 2：为 RBAC 配置 Azure AI 搜索

登录到 Azure 门户，并导航到你的 Azure AI 搜索服务。
启用基于角色的访问控制 (RBAC)：
1. 转到“设置”>“密钥”。
2. 如果你需要时间来将客户端转换为基于角色的访问控制，请选择“基于角色的控制”或“两者”。
  
  如果选择“基于角色的控制”，请确保为自己分配下一个说明中指定的所有角色，否则将无法在 Azure 门户中或通过本地客户端完成任务。
在 Azure 门户中分配角色：
1. 导航到你的搜索服务。
2. 在左侧导航窗格中，选择“访问控制(IAM)”。
3. 选择“+ 添加” > “添加角色分配”。
4. 选择一个角色（“搜索服务参与者”、“搜索索引数据参与者”、“搜索索引数据读取者”）并将其分配给你的 Microsoft Entra 用户或组标识。
  
  对每个角色重复此操作。
  
  需要有“搜索服务参与者”和“搜索索引数据参与者”角色才能在 Azure AI 搜索中创建、加载和查询对象。有关详细信息，请参阅使用角色进行连接。

提示

稍后，如果收到身份验证失败错误，请重新检查本部分中的设置。在订阅或资源组级别可能存在替代你指定的任何 API 设置的策略。

步骤 3：从本地系统进行连接

如果尚未登录到 Azure：

az login

使用 Python 和 Jupyter 笔记本

安装 Azure 标识和 Azure 搜索库：

pip install azure-identity azure-search-documents

对 Azure AI 搜索进行身份验证和连接：

from azure.identity import DefaultAzureCredential
from azure.search.documents import SearchClient

service_endpoint = "https://<your-search-service-name>.search.windows.net"
index_name = "hotels-sample-index"

credential = DefaultAzureCredential()
client = SearchClient(endpoint=service_endpoint, index_name=index_name, credential=credential)

results = client.search("beach access")
for result in results:
    print(result)

使用 REST 客户端

多个快速入门和教程使用 REST 客户端，例如具有 REST 扩展的 Visual Studio Code。下面介绍如何从 Visual Studio Code 连接到 Azure AI 搜索。

你应该有一个 .rest 或 .http 文件（类似于快速入门：矢量搜索中所述的文件）。

生成访问令牌。

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

在文件的顶部，设置用于连接的变量，粘贴完整的搜索服务终结点和上一步中获取的访问令牌。你的变量应类似于以下示例。请注意，这些值未括在引号内。
```
@baseUrl = https://contoso.search.search.windows.net
@token = <a long GUID>
```

在 REST 调用中指定授权持有者令牌：

 POST https://{{baseUrl}}/indexes/hotels-sample-index/docs/search?api-version=2024-07-01 HTTP/1.1
   Content-type: application/json
   Authorization: Bearer {{token}}

     {
          "queryType": "simple",
          "search": "beach access",
          "filter": "",
          "select": "HotelName,Description,Category,Tags",
          "count": true
      }

排查 401 错误

检查活动订阅和租户 (az account show)，并确保其对搜索服务有效。
在 Azure 门户中检查搜索服务的“设置”和“密钥”选项，并确认服务已配置为“两者”或“基于角色的访问控制”。
仅适用于 REST 客户端：检查文件中指定的令牌和终结点，确保没有两边的引号或多余的空格。

如果所有其他操作都失败，请重启设备以移除任何缓存的令牌，然后重复本部分中的步骤，从 az login 开始。

其他配置

为出站连接配置托管标识：

为搜索服务配置系统分配的或用户分配的托管标识。
使用角色分配来授权对其他 Azure 资源的访问。

网络访问配置：

设置入站规则以根据 IP 地址接受或拒绝对 Azure AI 搜索的请求。

通过