API 密钥最佳做法

对于使用 Google Maps Platform API 和 SDK 的应用和项目而言，API 密钥是必需的。本文档介绍了 API 密钥的预期用途、如何像保护其他凭据一样保护这些密钥，以及哪些限制适合您的项目。

什么是 API 密钥？

API 密钥是以项目为中心的凭据，具有以下两种用途：

  • 项目识别。
    识别调用相关 API 或 SDK 的应用或项目。
  • 项目授权。
    检查调用方应用是否获得了调用相关 API 或 SDK 的权限，并在项目中启用了相关 API 或 SDK。

创建 API 密钥后，该密钥即与项目相关联。通过识别调用方项目，API 密钥可将使用情况信息与该项目相关联，还有助于确保拒绝来自其他项目的调用。

保护 API 密钥

您应该保护应用中的API 密钥，针对您应用所使用的所有 Google Maps Platform 产品。想要保护 API 密钥，您可以指定限制以及实施适合您的应用所用 Google Maps Platform API 的最佳做法。公开泄露不安全的凭据可能导致意外使用，进而可能使您的帐号产生预料之外的费用。

以下做法介绍了有助于保护 API 密钥的策略。API 密钥限制和最佳做法部分列出了适合各个 Google Maps Platform 产品（如 Maps JavaScript API）的做法。

  • 限制您的 API 密钥。为了最有效地保护 API 密钥，您可以将其使用范围限制为特定 IP 地址、引荐来源网址或移动应用以及特定 API，因为这样做可以显著降低密钥泄露产生的影响。

    您可以通过以下方法在控制台中为密钥设置指定的应用和 API 限制：打开“凭据”页面，然后使用所需设置创建新的 API 密钥，或修改 API 密钥的设置。如需了解完整详情，请参阅限制 API 密钥。

  • 为不同的应用使用独立的 API 密钥。这可限制每个密钥的使用范围。如果 API 密钥泄露，您可以删除并撤消受影响的密钥，而无需更新其他 API 密钥。
  • 删除不需要的 API 密钥。

    如需删除 API 密钥，请执行以下操作：

    1. 访问“凭据”面板。
    2. 选择要删除的 API 密钥。
    3. 点击页面顶部附近的删除按钮。
    4. 在出现删除凭据弹出式窗口时，点击删除。

  • 重新生成 API 密钥时要小心谨慎。如果您的应用从使用旧 API 密钥改为使用重新生成的新 API 密钥所需的时间超过 24 小时，未更新的实例将会损坏，因为它们引用了旧密钥，这些旧密钥将在重新生成密钥 24 小时后销毁。

    重新生成 API 密钥后，会出现以下情况：

    • 通过重新生成流程得到新的密钥。
    • 新密钥接受旧密钥的所有限制。
    • 开始计时，旧密钥会在 24 小时候之后销毁。

  • 监控 API 密钥的使用是否存在异常。如果您发现未经授权的使用，请轮替密钥并通知 Google。

    在轮替密钥之前，请将与该密钥关联的限制复制到一个文件中以保留这些限制。

  • 对于使用地图网络服务 API 或静态网络 API 的应用，请采用以下方法保护应用和 API 密钥：

    • 不要直接在代码中嵌入 API 密钥或签名密钥。不要直接在应用的代码中嵌入 API 密钥或任何其他隐私信息，而应将它们放在环境变量或包含文件中，这些文件与大部分代码分开存储在应用源代码库以外的位置。然后，如果您共享代码，API 密钥或签名密钥将不会包含在共享文件中。
    • 不要将 API 密钥或签名密钥存储在应用源代码树内的文件中。如果您将 API 密钥或任何其他隐私信息存储在文件中，请将文件保留在应用的源代码树之外，这有助于确保密钥或其他隐私信息不会进入源代码控制系统。如果您使用公共源代码管理系统（如 GitHub），这种做法尤为重要。
    • 检查代码之后再公开发布。确保您的代码不包含 API 密钥、签名密钥或任何其他隐私信息，然后再公开代码。

  • 对于使用网络服务 API 或静态网络 API 的移动应用，请考虑采用以下一种或多种方法进一步保护 API 密钥或签名密钥：

限制 API 密钥

API 密钥是凭据，您应谨慎管理它们。您至少要遵循下面的建议来保证密钥的安全，并确保设置适当的限制来降低 API 密钥泄露产生的影响。

您可以通过指定应用限制或者一项或多项 API 限制来限制 API 密钥。

应用限制：将 API 密钥的使用范围限制为特定网站（IP 地址和网站）或特定平台（Android 和 iOS）。您最多可以从该类别中选择一项限制（请参阅 Google Maps Platform API（按平台））。

API 限制：将 API 密钥的使用范围限制为一个或多个 Google Maps Platform API 或 SDK。系统会处理针对与 API 密钥关联的 API 或 SDK 发出的使用请求。针对未与 API 密钥关联的 API 或 SDK 发出的使用请求将会失败。对于一个 API 密钥，您可以根据需要指定任意数量的 API 限制。请确保与 API 密钥关联的 API 或 SDK 支持为该 API 密钥设置的应用限制。

为 API 密钥设置应用限制

  1. 访问“凭据”面板。
  2. 选择您要设置限制的 API 密钥。系统随即会显示 API 密钥属性页面。
  3. 在“密钥限制”下，选择应用限制。
    选择一种限制类型，并按照限制列表提供所需信息。
    限制类型 说明
    HTTP 引荐来源

    接受来自您提供的一系列网站的请求。

    在类型下方，指定一个或多个引荐来源网站。可以使用通配符来命名类似的网站。例如，指定 *.google.com 表示接受所有以 google.com 结尾的网站，例如 https://developers.google.com。

    IP 地址

    接受来自您提供的一系列网络服务器 IP 地址的请求。

    在类型下方，指定一个 IPv4 或 IPv6 地址，或采用 CIDR 表示法的子网（例如 192.168.0.0/22）。如果您需要输入其他条目，在您添加完上一个条目后，系统会显示一个新框。

    Android 应用

    添加您的软件包名称和 SHA-1 签名证书指纹，以将 API 的使用范围限制为您的 Android 应用。

    在类型下方，添加 SHA-1 签名证书指纹和 AndroidManifest.xml 文件中的 Android 软件包名称。

    iOS 应用

    接受来自 iOS 应用（具有您提供的软件包标识符）的请求。

    在类型下方，从列表中选择相应的 iOS 软件包标识符。
  4. 点击保存。
    完成此步骤后，所设限制将成为 API 密钥定义的一部分。如果您没有提供适当的详细信息或没有点击“保存”，系统将不会限制 API 密钥（如需了解详情，请参阅您感兴趣的特定 API 或 SDK 对应的获取 API 密钥指南）。

为 API 密钥设置 API 限制

  1. 转到“凭据”面板。
  2. 选择您要设置限制的 API 密钥。
    系统会显示“限制和重命名 API 密钥”页面。
  3. 在“API 限制”下：
    • 点击限制密钥。
    • 点击选择 API 下拉列表，然后选择您想要应用通过该 API 密钥访问的 API 或 SDK（如果其中未列出某个 API 或 SDK，您需要启用它）。
  4. 点击保存。
    完成此步骤后，所设限制将成为 API 密钥定义的一部分。如果您没有提供适当的详细信息或没有点击“保存”，系统将不会限制 API 密钥（如需了解详情，请参阅您感兴趣的特定 API 或 SDK 对应的获取 API 密钥指南）。

API 密钥限制和最佳做法

下面的表格列出了适合每个 Google Maps Platform API、SDK 或服务的 API 密钥限制和最佳做法。

使用 Maps JavaScript API、Maps Embed API 或 Maps Static API 的网站

API/SDK/服务 应用限制(1) API 限制(1) 最佳做法
Maps JavaScript API(2) “HTTP 引荐来源”限制 Maps JavaScript API
路线服务、Maps JavaScript API “HTTP 引荐来源”限制 Directions API、Maps JavaScript API
距离矩阵服务、Maps JavaScript API “HTTP 引荐来源”限制 Distance Matrix API、Maps JavaScript API
海拔服务、Maps JavaScript API “HTTP 引荐来源”限制 Elevation API、Maps JavaScript API
地理编码服务、Maps JavaScript API “HTTP 引荐来源”限制 Geocoding API、Maps JavaScript API
Places Library、Maps JavaScript API “HTTP 引荐来源”限制 Places API、Maps JavaScript API
Maps Embed API “HTTP 引荐来源”限制 Maps Embed API
Maps Static API “HTTP 引荐来源”限制 Maps Static API
Street View Static API “HTTP 引荐来源”限制 Street View Static API

使用网络服务的应用和服务器

API/SDK/服务 应用限制(1) API 限制(1) 最佳做法
Directions API “IP 地址”限制(4) Directions API
Distance Matrix API “IP 地址”限制(4) Distance Matrix API
Elevation API “IP 地址”限制(4) Elevation API
Geocoding API “IP 地址”限制(4) Geocoding API
Geolocation API “IP 地址”限制(4) Geolocation API
Places API(5) “IP 地址”限制(4) Places API
Roads API “IP 地址”限制(4) Roads API
Time Zone API “IP 地址”限制(4) Time Zone API

Android 应用

API/SDK/服务 应用限制(1) API 限制(1) 最佳做法
Maps SDK for Android “Android”限制 Maps SDK for Android
Places SDK for Android “Android”限制 Places API

iOS 应用

API/SDK/服务 应用限制(1) API 限制(1) 最佳做法
Maps SDK for iOS “iOS”限制 Maps SDK for iOS
Places SDK for iOS “iOS”限制 Places API

1 您可以将不受限制的 API 密钥与任何 Google Maps Platform API 或 SDK 搭配使用。但是，我们强烈建议您限制 API 密钥，尤其是在以下情况下：

  • 测试环境将要或已经对外公开。
  • 使用 API 密钥的应用已准备好在生产环境中使用。

2 对于移动应用，请考虑使用原生的 Maps SDK for Android 和 Maps SDK for iOS。

3 对于 Maps Static API 和 Street View Static API，除了 API 密钥之外，您还需要提供数字签名才能超过每日配额（2.5 万次地图加载）。

注意：用于签名的共享密钥至少需要与地图网络服务 API 所用的 API 密钥具有相同的安全级别。

此外，如果您需要为图片请求进行动态签名，请在服务器端进行。如果您的应用依靠客户端输入来生成静态图片，请采用以下一种或多种方法保护应用：

如果您要对请求进行签名，还要检查您希望每天允许的未签名请求数量，并相应地调整未签名请求的配额。

4 设置 IP 限制可能不切实际，例如在依赖动态 IP 地址的移动应用和云环境中。在这些情况下使用地图网络服务 API 时，请采用以下一种或多种方法保护您的应用：

5 对于移动应用，请考虑使用原生的 Places SDK for Android 和 Places SDK for iOS。