您可以使用 API 密钥来限制对 API 中的特定 API 方法或所有方法的访问。本页面介绍如何限制为只允许拥有 API 密钥的客户端访问 API,同时还演示了如何创建 API 密钥。
Extensible Service Proxy (ESP) 使用 Service Control API 来验证 API 密钥及其与项目中已启用的 API 之间的关联。如果您在 API 中设置了 API 密钥要求,则对受保护的方法、类或 API 的请求将被拒绝,除非这些请求具有在您的项目或其他项目(属于已获授权可启用您的 API 的开发者)中生成的密钥。系统不会记录创建 API 密钥时所用的项目,也不会将其添加到请求标头中。不过,您可以按照针对特定使用方项目进行过滤中所述,在 Endpoints > 服务页面上查看与客户端关联的 Google Cloud 项目。
如需了解应在哪个 Google Cloud 项目中创建 API 密钥,请参阅共享受 API 密钥保护的 API。
默认情况下,在 gRPC 服务中,访问所有 API 方法都需要 API 密钥。您可以停用整个 API 或特定方法的 API 密钥要求。要执行此操作,请按照以下步骤,在服务配置中添加 usage 部分,并配置规则和选择器。
限制或授予对所有 API 方法的访问权限
要指定访问您的 API 不需要 API 密钥,请执行以下操作:
在文本编辑器中打开项目的 gRPC 服务配置文件,然后查找或添加
usage
部分。在
usage
部分中指定allow_unregistered_calls
规则,如下所示。selector
中的通配符"*"
表示该规则适用于 API 中的所有方法。usage: rules: # All methods can be called without an API Key. - selector: "*" allow_unregistered_calls: true
撤消对某个方法的 API 密钥限制
如需为特定方法停用 API 密钥验证(即使您已限制对该 API 的访问权限),请执行以下操作:
在文本编辑器中打开项目的 gRPC 服务配置文件,然后查找或添加
usage
部分。在
usage
部分中指定allow_unregistered_calls
规则,如下所示。selector
表示该规则仅适用于指定方法(在本例中为ListShelves
)。usage: rules: # ListShelves method can be called without an API Key. - selector: endpoints.examples.bookstore.Bookstore.ListShelves allow_unregistered_calls: true
使用 API 密钥调用 API
对 API 的调用会有所不同,具体取决于您是从 gRPC 客户端还是从 HTTP 客户端调用 API。
gRPC 客户端
如果某方法需要 API 密钥,则 gRPC 客户端需要将密钥值作为 x-api-key
元数据与其方法调用一起传递。
Python
Java
Go
Node.js
HTTP 客户端
如果您使用 Cloud Endpoints 来实现 gRPC 的 HTTP 转码功能,则 HTTP 客户端可以将密钥作为查询参数发送,具体方式与其在处理 OpenAPI 服务时的方式一样。
共享受 API 密钥保护的 API
API 密钥与其创建时所在的 Google Cloud 项目相关联。如果您已决定访问您的 API 需要提供 API 密钥,请回答以下几个问题,以便确定从中创建 API 密钥的 GCP 项目:
在确定从中创建 API 密钥的 Google Cloud 项目时,您可以下面的决策树为指导。
授予启用 API 的权限
如果您需要区分 API 的各个调用者,并且每个调用者都有自己的 Google Cloud 项目,您可以向主账号授予在其自己的 Google Cloud 项目中启用 API 的权限。这样,您的 API 用户就可以创建自己的 API 密钥,以用于您的 API。
例如,假设您的团队创建了一个 API,供公司内部的各种客户端程序使用,并且每个客户端程序都有各自的 Google Cloud 项目。如需区分您的 API 的各调用者,您必须在不同的 Google Cloud 项目中为每个调用者创建 API 密钥。您可以向同事授予在与相应客户端程序关联的 Google Cloud 项目中启用 API 的权限。
要允许用户创建自己的 API 密钥,请执行以下操作:
- 在配置 API 的 Google Cloud 项目中,向每个用户授予启用 API 的权限。
- 与这些用户联系,告知他们可以在其自己的 Google Cloud 项目中启用您的 API 以及创建 API 密钥。
为每个调用者单独创建一个 Google Cloud 项目。
如果您需要区分 API 的调用者,但并非所有调用者都有 Google Cloud 项目,您可以为每个调用者单独创建一个 Google Cloud 项目和 API 密钥。在创建项目之前,请考虑好项目名称,以便轻松识别与该项目关联的调用者。
例如,假设您的 API 有外部客户,并且您不知道调用您的 API 的客户端程序是如何创建的。也许有些客户端会使用 Google Cloud 服务并且拥有 Google Cloud 项目,而有些客户端则可能并非如此。如需区分调用者,您必须为每个调用者单独创建一个 Google Cloud 项目和 API 密钥。
如需为每个调用者单独创建一个 Google Cloud 项目和 API 密钥,请执行以下操作:
为每个调用者创建一个 API 密钥
如果您不需要区分 API 的调用者,但想要添加 API 密钥限制,则可以为同一项目中的每个调用者单独创建一个 API 密钥。
要为同一项目中的每个调用者创建一个 API 密钥,请执行以下操作:
为所有调用者创建一个 API 密钥
如果您不需要区分 API 的调用者,也不需要添加 API 限制,但仍想施加 API 密钥要求(例如,用于阻止匿名访问),则可以创建一个 API 密钥供所有调用者使用。
要为所有调用者创建一个 API 密钥,请执行以下操作:- 在配置了您的 API 的项目中或在启用了您的 API 的项目中,为所有调用者创建一个 API 密钥。
- 将该 API 密钥提供给每个调用者。