使用 API 密钥

本指南介绍了如何为 GCP 应用创建 API 密钥以及如何设置 API 密钥限制。如需详细了解如何对 GCP API 进行身份验证，请参阅身份验证概览。如需了解如何为 Google 地图设置 API 密钥，请参阅 Google 地图文档。

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

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

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

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

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

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

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

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

创建 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 密钥标题的下方。

后续步骤

• 了解如何对 GCP API 进行身份验证。

• 了解如何为生产应用设置身份验证。

• 了解如何以最终用户身份设置身份验证。