通过

使用密钥连接到 Azure AI 搜索

  • 项目

Azure AI 搜索提供基于密钥的身份验证，你可以使用这种方式连接到搜索服务。 API 密钥是由 52 个随机生成的数字和字母组成的唯一字符串。 你可以在你的资源代码中将它指定为一个环境变量，或者指定为你的项目中的一个应用设置，然后在请求中引用该变量。 如果请求和 API 密钥都有效，则会接受对搜索服务终结点发出的请求。

默认使用基于密钥的身份验证。

你可以使用基于角色的访问控制替换它，这样就无需在代码库中使用硬编码密钥。

API 密钥的类型

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

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

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

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

在连接上使用 API 密钥

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

管理密钥用于创建、修改或删除对象。 管理密钥还用于通过 GET 获取对象定义和系统信息。

查询密钥通常会分发到发出查询的客户端应用程序。

如何在 REST 调用中使用 API 密钥：

在请求头中设置管理密钥。 不能在 URI 或请求正文中传递管理密钥。 管理密钥用于创建-读取-更新-删除操作，以及向搜索服务本身发出的请求，例如通过 LIST 列出索引或通过 GET 获取服务统计信息。

下面是对“创建索引”请求使用管理 API 密钥的示例：

### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{adminApiKey}}

    {
        "name": "my-new-index",  
        "fields": [
            {"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
            {"name": "Name", "type": "Edm.String", "searchable": true }
         ]
   }

在 POST 的请求标头或 GET 的 URI 上设置查询密钥。 查询键用于针对 index/docs 集合的操作：搜索文档、自动完成、建议或通过 GET 获取文档。

下面是对搜索文档 (GET) 请求的查询 API 密钥用法示例：

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

注意

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

API 密钥的查看或管理权限

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

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

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

查找现有密钥

可以在 Azure 门户中查看和管理 API 密钥，也可以通过 PowerShell、Azure CLI 或 REST API 来查看和管理。

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

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

显示 API 密钥的门户页的屏幕截图。

创建查询密钥

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

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

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

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

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

    查询密钥管理选项的屏幕截图。

重新生成管理员密钥

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

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

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

  3. 重新生成主密钥。

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

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

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

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

保护 API 密钥

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

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

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

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

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

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

最佳做法

  • 仅当数据泄露没有风险（例如，使用示例数据时），并且你在防火墙后操作，才使用 API 密钥。 API 密钥的暴露会对数据造成风险，还会带来未经授权使用你的搜索服务的风险。

  • 在发布之前，请始终检查代码、示例和训练材料，以确保未遗漏有效的 API 密钥。

  • 对于生产工作负荷，请切换到 Microsoft Entra ID 和基于角色的访问。 或者，如果你想要继续使用 API 密钥，请务必始终监视谁有权访问你的 API 密钥，并定期重新生成 API 密钥。

另请参阅