创建和管理 Azure 认知搜索服务的 API 密钥Create and manage api-keys for an Azure Cognitive Search service

对搜索服务的所有请求都需要专为服务生成的只读 API 密钥。All requests to a search service need a read-only api-key that was generated specifically for your service. API 密钥是用于验证搜索服务终结点的访问的唯一机制,必须包含在每个请求中。The api-key is the sole mechanism for authenticating access to your search service endpoint and must be included on every request. REST 解决方案中,API 密钥通常在请求标头中指定。In REST solutions, the api-key is typically specified in a request header. .NET 解决方案中,密钥通常以配置设置的形式指定,然后在 SearchServiceClient 上作为凭据(管理密钥)或 SearchCredentials(查询密钥)传递。In .NET solutions, a key is often specified as a configuration setting and then passed as Credentials (admin key) or SearchCredentials (query key) on SearchServiceClient.

在服务预配期间,将使用搜索服务创建密钥。Keys are created with your search service during service provisioning. 可以在 Azure 门户中查看和获取密钥值。You can view and obtain key values in the Azure portal.

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

什么是 API 密钥?What is an api-key

API 密钥是随机生成的数字和字母所组成的字符串。An api-key is a string composed of randomly generated numbers and letters. 通过基于角色的权限,可以删除或读取密钥,但无法将密钥替换为用户定义的密码或使用 Active Directory 作为访问搜索操作的主要身份验证方法。Through role-based permissions, you can delete or read the keys, but you can't replace a key with a user-defined password or use Active Directory as the primary authentication methodology for accessing search operations.

使用了两种类型的密钥来访问搜索服务:管理员(只写)和查询(只读)。Two types of keys are used to access your search service: admin (read-write) and query (read-only).

密钥Key 说明Description 限制Limits
管理员Admin 授予所有操作的完全控制权限,包括管理服务以及创建和删除索引、索引器与数据源的能力。Grants full rights to all operations, including the ability to manage the service, create and delete indexes, indexers, and data sources.

创建服务时,会在门户中生成两个管理密钥(称为主密钥和辅助密钥),且可按需单独重新生成 。Two admin keys, referred to as primary and secondary keys in the portal, are generated when the service is created and can be individually regenerated on demand. 由于有两个密钥,可以在滚动其中一个密钥时,使用另一个密钥来持续访问服务。Having two keys allows you to roll over one key while using the second key for continued access to the service.

只能在 HTTP 请求标头中指定管理密钥。Admin keys are only specified in HTTP request headers. 不能在 URL 中放置管理 API 密钥。You cannot place an admin api-key in a URL.
每个服务最多有 2 个密钥Maximum of 2 per service
查询Query 授予对索引和文档的只读访问权限,通常分发给发出搜索请求的客户端应用程序。Grants read-only access to indexes and documents, and are typically distributed to client applications that issue search requests.

按需创建查询密钥。Query keys are created on demand. 可以在门户中手动创建查询密钥,或者通过管理 REST API 以编程方式创建查询密钥。You can create them manually in the portal or programmatically via the Management REST API.

可以在 HTTP 请求标头中为搜索、建议或查找操作指定查询密钥。Query keys can be specified in an HTTP request header for search, suggestion, or lookup operation. 或者,可以在 URL 中以参数形式传递查询密钥。Alternatively, you can pass a query key as a parameter on a URL. 根据客户端应用程序编写请求的方式,以查询参数的形式传递密钥可能更方便:Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:

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

在表面上,管理密钥与查询密钥之间没有区别。Visually, there is no distinction between an admin key or query key. 这两个密钥都是由 32 个随机生成的字母数字字符组成的字符串。Both keys are strings composed of 32 randomly generated alpha-numeric characters. 如果无法跟踪应用程序中指定了哪种类型的密钥,可以在门户中检查密钥值,或使用 REST API 返回值和密钥类型。If you lose track of what type of key is specified in your application, you can check the key values in the portal or use the REST API to return the value and key type.

备注

在请求 URI 中传递敏感数据(例如 api-key)被认为是不良的安全做法。It is considered a poor security practice to pass sensitive data such as an api-key in the request URI. 为此,Azure 认知搜索只接受查询字符串中 api-key 形式的查询密钥。除非必须公开索引的内容,否则应避免这样做。For this reason, Azure Cognitive Search only accepts a query key as an api-key in the query string, and you should avoid doing so unless the contents of your index should be publicly available. 作为经验法则,我们建议以请求标头的形式传递 api-keyAs a general rule, we recommend passing your api-key as a request header.

查找现有密钥Find existing keys

可以在门户中或通过管理 REST API 获取访问密钥。You can obtain access keys in the portal or through the Management REST API. 有关详细信息,请参阅管理管理员和查询 API 密钥For more information, see Manage admin and query api-keys.

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 列出订阅的搜索服务List the search services for your subscription.

  3. 选择该服务,在“概述”页上,单击“设置” >“密钥”以查看管理密钥和查询密钥。Select the service and on the Overview page, click Settings >Keys to view admin and query keys.

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

创建查询密钥Create query keys

查询密钥用于对面向文档集合的操作索引中的文档进行只读访问。Query keys are used for read-only access to documents within an index for operations targeting a documents collection. 搜索、筛选和建议查询都是采用查询密钥的操作。Search, filter, and suggestion queries are all operations that take a query key. 返回系统数据或对象定义(例如索引定义或索引器状态)的所有只读操作需要管理密钥。Any read-only operation that returns system data or object definitions, such as an index definition or indexer status, requires an admin key.

限制客户端应用中的访问和操作对于保护服务中的搜索资产至关重要。Restricting access and operations in client apps is essential to safeguarding the search assets on your service. 对于源自客户端应用的任何查询,请始终使用查询密钥而不是管理密钥。Always use a query key rather than an admin key for any query originating from a client app.

  1. 登录 Azure 门户Sign in to the Azure portal.

  2. 列出订阅的搜索服务List the search services for your subscription.

  3. 选择该服务,在“概述”页上单击“设置” >“密钥”。Select the service and on the Overview page, click Settings >Keys.

  4. 单击“管理查询密钥”。 Click Manage query keys.

  5. 使用已为服务生成的查询密钥,或创建最多 50 个新的查询密钥。Use the query key already generated for your service, or create up to 50 new query keys. 默认查询密钥未命名,但可将其他查询密钥命名以便于管理。The default query key is not named, but additional query keys can be named for manageability.

    创建或使用查询密钥

备注

查询以 C# 编写的 Azure 认知搜索索引中可以找到一个演示查询密钥用法的代码示例。A code example showing query key usage can be found in Query an Azure Cognitive Search index in C#.

重新生成管理员密钥Regenerate admin keys

系统将为每个服务生成两个管理密钥,以便在轮换主密钥时可以使用辅助密钥,从而实现业务连续性。Two admin keys are created for each service so that you can rotate a primary key, using the secondary key for business continuity.

  1. 在“设置” >“密钥”页中,复制辅助密钥。In the Settings >Keys page, copy the secondary key.
  2. 对于所有应用程序,更新 API 密钥设置以使用辅助密钥。For all applications, update the api-key settings to use the secondary key.
  3. 重新生成主密钥。Regenerate the primary key.
  4. 更新所有应用程序以使用新的主密钥。Update all applications to use the new primary key.

如果无意中同时重新生成了这两个密钥,则使用这些密钥的所有客户端请求将会失败并出现“HTTP 403 禁止访问”。If you inadvertently regenerate both keys at the same time, all client requests using those keys will fail with HTTP 403 Forbidden. 但是,内容不会删除,并且不会将你永久性地锁定在系统之外。However, content is not deleted and you are not locked out permanently.

仍可以通过门户或管理层(REST APIPowerShell 或 Azure 资源管理器)访问服务。You can still access the service through the portal or the management layer (REST API, PowerShell, or Azure Resource Manager). 管理功能是通过订阅 ID 而不是服务 API 密钥运行的,因此,即使 API 密钥不可用,这些功能也仍可用。Management functions are operative through a subscription ID not a service api-key, and thus still available even if your api-keys are not.

通过门户或管理层创建新的密钥后,只要在请求中提供这些新密钥,就会恢复对内容(索引、索引器、数据源、同义词映射)的访问权限。After you create new keys via portal or management layer, access is restored to your content (indexes, indexers, data sources, synonym maps) once you have the new keys and provide those keys on requests.

保护 API 密钥Secure api-keys

通过门户或 Resource Manager 界面(PowerShell 或命令行接口)以限制访问,从而保护密钥安全。Key security is ensured by restricting access via the portal or Resource Manager interfaces (PowerShell or command-line interface). 如前所述,订阅管理员可以查看和重新生成所有 API 密钥。As noted, subscription administrators can view and regenerate all api-keys. 作为预防措施,查看角色分配以了解谁有权访问管理密钥。As a precaution, review role assignments to understand who has access to the admin keys.

  • 在服务仪表板中,依次单击“访问控制(IAM)”和“角色分配”选项卡可查看服务的角色分配。In the service dashboard, click Access control (IAM) and then the Role assignments tab to view role assignments for your service.

以下角色的成员可以查看和重新生成密钥:所有者、参与者和搜索服务参与者Members of the following roles can view and regenerate keys: Owner, Contributor, Search Service Contributors

备注

如果要实现针对搜索结果的、基于标识的访问,可创建安全筛选器按标识来细化结果,由此去除请求者不应具有访问权限的那些文档。For identity-based access over search results, you can create security filters to trim results by identity, removing documents for which the requestor should not have access. 有关详细信息,请参阅安全筛选器使用 Active Directory 进行保护For more information, see Security filters and Secure with Active Directory.

另请参阅See also