使用密钥身份验证连接到 Azure AI 搜索

Azure AI 搜索提供基于密钥的身份验证,你可以使用这种方式连接到搜索服务。 API 密钥是由 52 个随机生成的数字和字母组成的唯一字符串。 如果请求和 API 密钥都有效,则会接受对搜索服务终结点发出的请求。

注意

有关“密钥”术语在 Azure AI 搜索中的用法的快速说明。 本文中所述的“API 密钥”是指用于对请求进行身份验证的 GUID。 单独的术语“文档密钥”是指编制了索引的内容中用于唯一标识搜索索引中文档的唯一字符串。

API 密钥的类型

有两种类型的密钥用于对请求进行身份验证:

类型 权限级别 最大值 创建方式
管理员 对所有内容操作的完全访问权限(读写) 2 1 创建服务时,会在门户中生成两个管理密钥(称为主密钥和辅助密钥),且可按需单独重新生成 。
查询 只读访问权限,范围限定为搜索索引的文档集合 50 在服务中生成一个查询密钥。 搜索服务管理员可按需创建更多密钥。

1 由于有两个密钥,你可以在滚动其中一个密钥时,使用另一个密钥来持续访问服务。

在表面上,管理密钥与查询密钥之间没有区别。 这两个密钥都是由 52 个随机生成的字母数字字符组成的字符串。 如果无法跟踪应用程序中指定了哪种类型的密钥,可以在门户中检查密钥值

在连接上使用 API 密钥

API 密钥用于数据平面(内容)请求,例如创建或访问索引或搜索 REST API 中表示的任何其他请求。 创建服务时,API 密钥是数据平面操作的唯一身份验证机制,但如果你无法在代码中使用硬编码的密钥,可以将密钥身份验证替换为 Azure 角色或对其进行补充。

API 密钥是在客户端对搜索服务发出的请求中指定的。 在请求中传递有效的 API 密钥可证明请求来自授权客户端。 如果你要创建、修改或删除对象,则需要管理员 API 密钥。 否则,查询密钥通常会分发到发出查询的客户端应用程序。

可以在 REST API 调用的请求头中指定 API 密钥,或者在调用 Azure SDK 中的 azure.search.documents 客户端库的代码中指定 API 密钥。 如果你使用 Azure 门户执行任务,则角色分配将确定访问级别

有关在源文件中使用硬编码密钥的最佳做法包括:

密钥身份验证是内置的,因此无需执行任何操作。 默认情况下,门户将自动使用 API 密钥对请求进行身份验证。 但是,如果你禁用 API 密钥并设置角色分配,则门户将改用角色分配。

在 Azure AI 搜索中,大多数任务都可以在 Azure 门户中执行,包括创建对象、通过导入数据向导编制索引,以及通过搜索资源管理器进行查询。

注意

在请求 URI 中传递敏感数据(例如 api-key)的做法很不安全。 出于此原因, Azure AI 搜索仅接受使用查询密钥作为查询字符串中的 api-key。 作为经验法则,我们建议以请求标头的形式传递 api-key

API 密钥的查看或管理权限

API 密钥的查看和管理权限是通过角色分配传播的。 以下角色的成员可以查看和重新生成密钥:

以下角色无权访问 API 密钥:

  • 读者
  • 搜索索引数据参与者
  • 搜索索引数据读取者

查找现有密钥

可以在 Azure 门户中查看和管理 API 密钥,也可以通过 PowerShellAzure CLIREST API 来查看和管理。

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

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

Screenshot of a portal page showing API keys.

创建查询密钥

查询密钥用于对面向文档集合的操作索引中的文档进行只读访问。 搜索、筛选和建议查询都是采用查询密钥的操作。 返回系统数据或对象定义(例如索引定义或索引器状态)的所有只读操作需要管理密钥。

限制客户端应用中的访问和操作对于保护服务中的搜索资产至关重要。 对于源自客户端应用的任何查询,请始终使用查询密钥而不是管理密钥。

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

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

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

    Screenshot of the query key management options.

重新生成管理员密钥

系统将为每个服务生成两个管理密钥,以便在轮换主密钥时可以使用辅助密钥,从而实现业务连续性。

  1. 在“设置”下选择“密钥”,然后复制辅助密钥。

  2. 对于所有应用程序,更新 API 密钥设置以使用辅助密钥。

  3. 重新生成主密钥。

  4. 更新所有应用程序以使用新的主密钥。

如果无意中同时重新生成了这两个密钥,则使用这些密钥的所有客户端请求将会失败并出现“HTTP 403 禁止访问”。 但是,内容不会删除,并且不会将你永久性地锁定在系统之外。

仍然可以通过门户或以编程方式访问该服务。 管理功能是通过订阅 ID 而不是服务 API 密钥运行的,因此,即使 API 密钥不可用,这些功能也仍可用。

通过门户或管理层创建新的密钥后,只要在请求中提供这些新密钥,就会恢复对内容(索引、索引器、数据源、同义词映射)的访问权限。

保护 API 密钥

使用角色分配来限制对 API 密钥的访问。

请注意,无法使用客户管理的密钥加密来加密 API 密钥。 只能对搜索服务本身中的敏感数据(例如,索引内容或数据源对象定义中的连接字符串)进行 CMK 加密。

  1. 在 Azure 门户中导航到“搜索服务”页。

  2. 在左侧导航窗格中,选择“访问控制(IAM)”,然后选择“角色分配”选项卡 。

  3. 在“角色”筛选器中,选择有权查看或管理密钥的角色(所有者、参与者、搜索服务参与者)。 最终分配给这些角色的安全主体对搜索服务拥有密钥权限。

  4. 作为预防措施,另请检查“经典管理员”选项卡,以确定管理员和共同管理员是否拥有访问权限。

另请参阅