使用 API 密钥限制 API 访问权限

您可以使用 API 密钥来限制对 API 中的特定 API 方法或所有方法的访问。本页面介绍了如何设置限制以只允许拥有 API 密钥的客户端访问 API，同时还演示了如何创建 API 密钥。

如果您在 API 中设置了 API 密钥要求，则对受保护的方法、类或 API 的请求将被拒绝，除非这些请求具有在您的项目或其他项目（属于已获授权可启用您的 API 的开发者）中生成的密钥。系统不会记录创建 API 密钥时所用的项目，也不会将该项目添加到请求标头中。不过，您可以在 Endpoints 服务页面上查看与客户端关联的 Google Cloud 项目（请参阅针对特定使用方项目进行过滤）。

如需了解应在哪个 Google Cloud 项目中创建 API 密钥，请参阅共享受 API 密钥保护的 API。

限制对所有 API 方法的访问

如果要求所有 API 调用都必须提供 API 密钥，请将 api_key_required=True 添加到您的 API 修饰器。 例如：

@endpoints.api(name='echo', version='v1', api_key_required=True)
class EchoApi(remote.Service):
#...

限制对特定 API 方法的访问

如果要求对特定 API 方法的所有调用都必须提供 API 密钥，请将 api_key_required=True 添加到 API 方法修饰器。 例如：

endpoints.method(
  # This method takes an Echo message.
  ECHO_RESOURCE,
  # This method returns an Echo message.
  EchoResponse,
  path='echo',
  http_method='POST',
  name='echo_api_key',
  api_key_required=True)
def echo_api_key(self, request):
  output_content = '\n'.join([request.content] * request.n)
  return EchoResponse(content=output_content)

移除对某个方法的 API 密钥限制

要为某个 API 或 API 方法停用 API 密钥验证，请从相应 API 或方法的装饰器或注释中移除 api_key_required=True (Python) 或 apiKeyRequired = AnnotationBoolean.TRUE (Java)，然后重新编译并重新部署。

使用 API 密钥调用 API

如果 API 或 API 方法要求提供 API 密钥，请使用名为 key 的查询参数提供密钥，如以下 cURL 示例所示：

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

其中 HOST 和 API_KEY 分别是包含 API 主机名和 API 密钥的变量。将 echo 替换为您的 API 名称，将 v1 替换为您的 API 版本。

共享受 API 密钥保护的 API

API 密钥与其创建时所在的 Google Cloud 项目相关联。如果您已决定访问您的 API 需要提供 API 密钥，请回答以下几个问题，以便确定从中创建 API 密钥的 Google Cloud 项目：

  • 您是否需要区分 API 的调用者以便使用 Endpoints 的配额等功能？
  • API 的所有调用者是否都有自己的 Google Cloud 项目？
  • 您是否需要设置不同的 API 密钥限制？

在确定从中创建 API 密钥的 Google Cloud项目时，您可以下面的决策树为指导。

API 密钥决策树

授予启用 API 的权限

如果您需要区分 API 的各个调用者，并且每个调用者都有自己的 Google Cloud 项目，您可以向主账号授予在其自己的 Google Cloud 项目中启用 API 的权限。这样，您的 API 用户就可以创建自己的 API 密钥，以用于您的 API。

例如，假设您的团队创建了一个 API，供公司里的各种客户端程序内部使用，并且每个客户端程序都有各自的 Google Cloud项目。如需区分 API 的调用者，您必须在不同的 Google Cloud 项目中为每个调用者创建 API 密钥。您可以向同事授予在与相应客户端程序关联的 Google Cloud 项目中启用 API 的权限。

要允许用户创建自己的 API 密钥，请执行以下操作：

  1. 在配置了您的 API 的 Google Cloud 项目中，向每个用户授予启用您的 API 的权限。
  2. 与这些用户联系，告知他们可以在自己的 Google Cloud项目中启用您的 API 以及 创建 API 密钥。

为每个调用者单独创建一个 Google Cloud 项目

如果您需要区分 API 的调用者，且并非所有调用者都有 Google Cloud 项目，您可以为每个调用者单独创建一个 Google Cloud 项目和 API 密钥。在创建项目之前，请考虑好项目名称，以便轻松识别与该项目关联的调用者。

例如，假设您的 API 有外部客户，并且您不知道调用您的 API 的客户端程序是如何创建的。也许有些客户会使用 Google Cloud 服务并且拥有 Google Cloud 项目，而有些客户则可能并非如此。如需区分调用者，您必须为每个调用者单独创建一个 Google Cloud 项目和 API 密钥。

如需为每个调用者单独创建一个 Google Cloud 项目和 API 密钥，请执行以下操作：

  1. 为每个调用者单独创建一个项目。
  2. 在每个项目中，启用您的 API 并创建 API 密钥。
  3. 将此 API 密钥提供给对应的调用者。

为每个调用者创建一个 API 密钥

如果您不需要区分 API 的调用者，但想要添加 API 密钥限制，则可以为同一项目中的每个调用者单独创建一个 API 密钥。

要为同一项目中的每个调用者创建一个 API 密钥，请执行以下操作：

  1. 在配置了您的 API 的项目中或在启用了您的 API 的项目中，为需要遵循您所需的 API 密钥限制的每位客户创建一个 API 密钥。
  2. 将此 API 密钥提供给对应的调用者。

为所有调用者创建一个 API 密钥

如果您不需要区分 API 的调用者，也不需要添加 API 限制，但仍想施加 API 密钥要求（例如，用于阻止匿名访问），则可以创建一个 API 密钥供所有调用者使用。

要为所有调用者创建一个 API 密钥，请执行以下操作：
  1. 在配置了您的 API 的项目中或在启用了您的 API 的项目中，为需要遵循您所需的 API 密钥限制的所有调用者创建一个 API 密钥。
  2. 将该 API 密钥提供给每个调用者。

后续步骤