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

使用 API 密钥进行 Azure 认知搜索身份验证

认知搜索提供基于密钥的身份验证作为其主要身份验证方法。 对于搜索服务终结点的入站请求(例如创建或查询索引的请求),API 密钥是你唯一的正式身份验证选项。 一些出站请求方案(尤其是涉及索引器的方案)可以使用 Azure Active Directory 标识和角色。

注意

Azure 基于角色的访问控制 (RBAC) 对搜索终结点的入站请求现在处于预览状态。 可以使用此预览版功能来补充或替换搜索索引请求中的 API 密钥。

API 密钥在服务创建时生成。 在请求中传递有效的 API 密钥可证明请求来自授权客户端。 密钥有两种类型。 管理密钥:传达对服务的写入权限,还授予查询系统信息的权限。 查询密钥:传达读取权限,应用可以使用该密钥查询特定索引。

在连接到搜索服务时,所有请求都必须包含专门为你的服务生成的 API 密钥。

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

门户页上的“检索设置”>“密钥”部分

什么是 API 密钥?

API 密钥是由随机生成的数字和字母组成的唯一字符串,随每个请求传递到搜索服务。 如果请求本身和密钥都是有效的,则服务将接受该请求。

使用了两种类型的密钥来访问搜索服务:管理员(只写)和查询(只读)。

密钥 说明 限制
管理员 授予所有操作的完全控制权限,包括管理服务以及创建和删除索引、索引器与数据源的能力。

创建服务时,会在门户中生成两个管理密钥(称为主密钥和辅助密钥),且可按需单独重新生成 。 由于有两个密钥,可以在滚动其中一个密钥时,使用另一个密钥来持续访问服务。

只能在 HTTP 请求标头中指定管理密钥。 不能在 URL 中放置管理 API 密钥。
每个服务最多有 2 个密钥
查询 授予对索引和文档的只读访问权限,通常分发给发出搜索请求的客户端应用程序。

按需创建查询密钥。

可以在 HTTP 请求标头中为搜索、建议或查找操作指定查询密钥。 或者,可以在 URL 中以参数形式传递查询密钥。 根据客户端应用程序编写请求的方式,以查询参数的形式传递密钥可能更方便:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2020-06-30&api-key=[query key]
每个服务 50 个密钥

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

注意

在请求 URI 中传递敏感数据(例如 api-key)的做法很不安全。 为此,Azure 认知搜索只接受查询字符串中 api-key 形式的查询密钥。除非必须公开索引的内容,否则应避免这样做。 作为经验法则,我们建议以请求标头的形式传递 api-key

查找现有密钥

可以在门户中获取访问密钥,也可以通过 PowerShellAzure CLIREST API 来获取。

  1. 登录 Azure 门户

  2. 列出适用于订阅的搜索服务

  3. 选择该服务,在“概述”页上,单击“设置”>“密钥”以查看管理密钥和查询密钥。

    门户页上的“查看设置”>“密钥”部分

创建查询密钥

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

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

  1. 登录 Azure 门户

  2. 列出适用于订阅的搜索服务

  3. 选择该服务,在“概述”页上单击“设置”>“密钥”。

  4. 单击“管理查询密钥”。

  5. 使用已为服务生成的查询密钥,或创建最多 50 个新的查询密钥。 默认查询密钥未命名,但可将其他查询密钥命名以便于管理。

    创建或使用查询密钥

注意

DotNetHowTo 中可以找到一个演示查询密钥用法的代码示例。

重新生成管理员密钥

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

  1. 在“设置”>“密钥”页中,复制辅助密钥。
  2. 对于所有应用程序,更新 API 密钥设置以使用辅助密钥。
  3. 重新生成主密钥。
  4. 更新所有应用程序以使用新的主密钥。

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

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

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

保护 API 密钥

角色分配可读取和管理密钥的人员。 以下角色的成员可以查看和重新生成密钥:所有者、参与者和搜索服务参与者。 读者角色无权访问 API 密钥。

订阅管理员可以查看和重新生成所有 API 密钥。 作为预防措施,查看角色分配以了解谁有权访问管理密钥。

  1. 在 Azure 门户中导航到“搜索服务”页。
  2. 在左侧导航窗格中,选择“访问控制(IAM)”,然后选择“角色分配”选项卡 。
  3. 将“范围”设置为“此资源”以查看服务的角色分配 。

另请参阅