使用 API 密钥

本指南介绍了如何为 Google Cloud 应用创建 API 密钥以及如何设置 API 密钥限制。如需详细了解如何向 Google Cloud API 验证身份，请参阅身份验证概览。如需了解 Google Maps Platform API 和 SDK 的 API 密钥，请参阅 Google 地图文档。

注意：请勿将 API 密钥用于本地或生产应用，下述特定情况除外。几乎在所有情况下，您都应使用服务帐号。

API 密钥是一个简单的加密字符串，可以在调用某些不需要访问私有用户数据的 API 时使用。API 密钥对浏览器和没有后端服务器的移动应用等客户端非常有用。API 密钥用于跟踪与项目关联的 API 请求以进行配额计算和结算。

API 密钥具有重要限制，例如：

• 所有 Google Cloud 服务都允许使用服务帐号等凭据进行访问。但是，仅有限数量的 Google Cloud 服务允许只使用 API 密钥（无需同时使用其他类型的凭据）进行访问：

  • Google Cloud Natural Language API
  • Google Cloud Speech API
  • Cloud Translation API
  • Cloud Vision API
  • Cloud Endpoints API
  • Cloud Billing Catalog API
  • Cloud Data Loss Prevention API

• API 密钥不会识别发出 API 请求的用户或应用，因此您无法只将访问权限授予特定用户或服务帐号。

• 他人更容易发现和使用您的 API 密钥。

因此，我们建议改用标准身份验证流程。但是，在少数情况下，使用 API 密钥更合适。例如，如果您开发的移动应用需要使用 Google Cloud Translation API，但不需要使用后端服务器，那么 API 密钥是向该 API 验证身份的最简单方法。在大多数情况下，我们建议让您的应用与处理 Google Cloud 服务身份验证和调用的后端服务器进行通信。

创建 API 密钥

要创建 API 密钥，您必须为帐号授予当前项目的原初 Editor 角色 (roles/editor)。如需了解详情，请参阅原初角色。

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

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

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

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

您最好复制一份密钥并确保其安全。除非您使用的是之后打算删除的测试密钥，否则请添加应用和 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 密钥存储在应用的源代码树内的文件中。如果将 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 限制

要添加 HTTP 限制，请执行以下操作：

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

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

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

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

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

使用场景	限制
允许特定的网址。	添加包含确切路径的单个限制。例如： https://www.example.com/path http://www.example.com/path/path
允许单个子网域或裸网域中的任何网址。	您必须设置至少两个限制才能允许整个网域。 为网域设置限制时，不以斜杠结尾。例如： https://www.example.com http://sub.example.com http://example.com 为包含路径通配符的网域设置第二个限制。例如： https://www.example.com/* http://sub.example.com/* http://example.com/* 如果您的网域同时允许 HTTP 和 HTTPS，您必须单独添加额外限制。
允许单个网域中的任何子网域网址。	您必须至少设置两个限制。 为网域设置限制时，对子网域使用通配符，且不以斜杠结尾。例如： https://*.example.com 为包含路径通配符的网域设置第二个限制，例如： https://*.example.com/* 如果您的网域同时允许 HTTP 和 HTTPS，则您必须单独添加额外限制。

API 限制

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

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

1. 在 API 限制部分中选择限制密钥。

2. 从下拉菜单中选择您的 API 密钥需要调用的所有 API 名称。

3. 选择保存按钮。

查看现有 API 密钥

要查看现有 API 密钥，请使用 Cloud Console。导航到 Cloud Console 中的API 和服务→凭据面板后，现有 API 密钥会显示在API 密钥标题的下方。

后续步骤

• 了解如何向 Google Cloud API 验证身份。
• 了解如何为生产应用设置身份验证。
• 了解如何以最终用户身份设置身份验证。