使用 API 密钥

本主题向应用开发者介绍了如何将 API 密钥与 Google Cloud API 配合使用。API 密钥是一个简单的加密字符串，用于标识没有任何主帐号的应用。这些密钥对于匿名访问公开数据非常有用，并且可用于将 API 请求与您的项目相关联，以进行配额计算和结算。

如需详细了解如何向 Google Cloud API 进行身份验证并确定常见场景的最佳身份验证策略，请参阅身份验证概览。如需详细了解如何将 API 密钥用于 Google Maps Platform API 和 SDK，请参阅 Google Maps Platform 文档。

自行试用

如果您是 Google Cloud 新手，请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

免费开始使用

管理 API 密钥

我们建议您使用 Cloud Console 管理 API 密钥。导航到 Cloud Console 中的 API 和服务 → 凭据页面。您的 API 密钥会显示在 API 密钥部分中。在此页面上，您可以创建 API 密钥，定义 API 密钥限制，轮替 API 密钥字符串，以及执行其他操作。

创建 API 密钥

如需在项目中创建 API 密钥，用户必须拥有项目的 Editor 基本角色 (roles/editor)。如需了解详情，请参阅基本角色。

如需创建 API 密钥，请执行以下操作：

  1. 导航至 Cloud Console 中的 API 和服务→凭据面板。

  2. 选择创建凭据，然后从下拉菜单中选择 API 密钥。

    您新建的密钥将显示在已创建 API 密钥对话框中。

    API 密钥是一个包含大写字母、小写字母、数字和短划线的长字符串，例如 a4db08b7-5729-4ba9-8c08-f2df493465a1。

您应该复制一份密钥，并确保其安全。除非您使用的是之后打算删除的测试密钥，否则请添加应用和 API 密钥限制。

使用 API 密钥

将 API 密钥作为查询参数传递给 REST API 调用，格式如下。将 API_KEY 替换为您的 API 密钥。

key=API_KEY

例如，为针对 documents.analyzeEntities 发出的 Cloud Natural Language API 请求传递 API 密钥：

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

保护 API 密钥

当您在应用中使用 API 密钥时，请确保其在存储和传输期间均安全无虞。公开泄露凭据可能会导致您的帐号遭盗用，这可能会使您的帐号产生预料之外的费用。为帮助确保 API 密钥的安全，请遵循以下最佳做法：

  • 不要直接在代码中嵌入 API 密钥。嵌入代码中的 API 密钥可能会被意外泄露给公众。例如，您可能忘记从共享的代码中移除密钥。您可以将 API 密钥存储在环境变量或应用的源代码树之外的文件中，而不是将 API 密钥嵌入应用中。

  • 不要将 API 密钥存储在应用的源代码树内的文件中。如果将 API 密钥存储在文件中，请将文件保留在应用的源代码树之外，这有助于确保密钥最终不会进入源代码控制系统。 如果您使用公共源代码管理系统（如 GitHub），这种做法尤为重要。

  • 设置应用和 API 密钥限制。 通过添加限制，您可以降低 API 密钥被盗用时造成的影响。

  • 删除不需要的 API 密钥以最大限度地减少遭到攻击的风险。

  • 定期重新生成 API 密钥。您可以在“凭据”页面中，针对每个密钥点击重新生成密钥，从而重新生成 API 密钥。然后，更新您的应用以使用新生成的密钥。生成替换密钥后，旧密钥将在 24 小时后失效。

  • 公开发布代码前，先检查您的代码，确保您的代码不包含 API 密钥或任何其他私密信息，然后再公开代码。

应用 API 密钥限制

默认情况下，API 密钥不受限制。不受限制的密钥会带来安全方面的问题，因为任何人都可以随时随地使用此类密钥。对于生产应用，您应该同时设置应用限制和 API 限制。

如需添加 API 密钥限制，请执行以下操作：

  1. 导航至 Cloud Console 中的 API 和服务→凭据面板。

  2. 选择现有 API 密钥的名称。

添加应用限制

应用限制用于指定哪些网站、IP 地址或应用可以使用 API 密钥。您应根据应用类型添加应用限制。每个 API 密钥只能设置一种限制类型。

根据您的应用需求选择限制类型。

  • 无仅用于测试目的。

  • 针对在网络浏览器上运行的 API 客户端使用 HTTP 引荐来源网址，这样一来，只有指定的页面才可以调用 API。这些类型的应用会公开显示其 API 密钥，因此我们建议您改用服务帐号。如需查看相关示例，请参阅下面的添加 HTTP 限制部分。

  • IP 地址用于限制只有某些 IP 地址可以访问 API 密钥。

  • Android 应用用于 Android 应用。此选项需要添加软件包名称和 SHA-1 签名证书指纹。

  • iOS 应用用于 iOS 应用。此选项需要至少添加一个 iOS 软件包标识符，以限制只有特定 iOS 软件包可以调用 API。

添加 HTTP 限制

Web 应用使用的 API 密钥应具有 HTTP 限制。如需添加 HTTP 限制，请执行以下操作：

  • 在应用限制部分中选择 HTTP 引荐来源网址（网站）。

  • 在网站限制部分至少输入一个限制。

  • 如果您的网域同时支持 HTTP 和 HTTPS，则必须单独添加这两个限制。

  • 您可以选择对子网域和/或路径使用通配符 (*)。

下表显示了从限制性最高到限制性最低的示例场景和限制。我们建议您使用适合自己使用场景的限制性最高的示例。

使用场景 限制
允许特定的网址。

添加包含确切路径的单个限制。例如：

  • https://www.example.com/path
  • http://www.example.com/path/path
允许单个子网域或裸网域中的任何网址。

您必须设置至少两个限制才能允许整个网域。

  1. 为网域设置限制时，不以斜杠结尾。例如：
    • https://www.example.com
    • http://sub.example.com
    • http://example.com
  2. 为包含路径通配符的网域设置第二个限制。例如：
    • https://www.example.com/*
    • http://sub.example.com/*
    • http://example.com/*
  3. 如果您的网域同时允许 HTTP 和 HTTPS，您必须单独添加额外限制。
允许单个网域中的任何子网域网址。

您必须至少设置两个限制。

  1. 为网域设置限制时，对子网域使用通配符，且不以斜杠结尾。例如：
    • https://*.example.com
  2. 为包含路径通配符的网域设置第二个限制，例如：
    • https://*.example.com/*
  3. 如果您的网域同时允许 HTTP 和 HTTPS，您必须单独添加额外限制。

添加 API 限制

API 限制用于指定可以使用 API 密钥调用哪些 API。生产应用使用的所有 API 密钥都应具有 API 限制。

要设置 API 限制，请执行以下操作：

  1. 在 API 限制部分中，点击限制密钥。

  2. 从下拉列表中选择您的 API 密钥将用于访问的所有 API。

  3. 点击保存。

每个项目的限制

您可以为每个项目创建 300 个 API 密钥。这是系统限制，不能通过配额提升请求进行更改。

如果需要更多 API 密钥，则应将它们拆分到多个项目中。

后续步骤