API 安全性最佳实践

对于使用 Google Maps Platform API 和 SDK 的应用和项目而言，API 密钥是必需的。为尽可能提高安全性并减少工作量，您在创建 API 密钥时应加以保护。

虽然可以在创建 API 密钥后及使用过程中为其提供保护，但因密钥使用方式不同，可能会受到不同限制。更新或替换移动应用（Android 和 iOS）中的密钥最为复杂，因为所有客户都更新应用后，密钥才能全部替换完毕。更新或替换 JavaScript 或网络服务应用中的密钥要简单得多，但更新或替换这些密钥仍需认真规划并快速完成。

更多信息部分列出了适用于各个 Google Maps Platform 产品（例如 Maps JavaScript API）的安全性实践。

限制您的 API 密钥

首次创建 API 密钥时，请通过设置一项应用限制以及一项或多项 API 限制来对密钥进行限制。

  • 应用限制：将 API 密钥的使用范围限制为特定平台（Android 或 iOS）或特定网站（公共 IP 地址和网站）。为任何一个 API 密钥只能添加一种应用限制。

  • API 限制：将 API 密钥的使用范围限制为一个或多个 Google Maps Platform API 或 SDK。系统仅会处理针对与 API 密钥关联的 API 或 SDK 发出的使用请求。对于任何给定 API 密钥，您可以根据需要指定任意数量的 API 限制。

如果您在创建 API 密钥时未采取保护措施，请另行创建 API 密钥并对其加以限制，然后使用新的 API 密钥更新所有应用。为安全起见，每个应用最好使用一个密钥，但您可以针对多个应用使用受限制的密钥，只要针对相应密钥的应用限制类型不会导致与共用该密钥的应用不兼容的问题即可。

如果您在创建 API 密钥后对其进行限制，请检查 API 密钥的使用情况，确保这些限制不会破坏任何现有应用。

  1. 前往 Google Cloud 控制台的“指标”页面。

  2. 选择显示过滤条件。

  3. 从分组依据中选择凭据。您会看到哪些 API 密钥用于哪些 Google 服务。

  4. 点击凭据。

  5. 取消选择所有凭据。

  6. 对于显示的每个密钥，请选择相应密钥，然后点击确定。

  7. 从分组依据中选择 API。您会看到应用于该密钥的 API 限制。

    通过从分组依据中选择 API 方法，您可以大致了解哪种类型的应用限制最适合某个密钥。

为 API 密钥设置应用限制

  1. 前往“凭据”页面。

  2. 选择您要设置限制的 API 密钥。系统随即会显示 API 密钥属性页面。

  3. 在密钥限制下，选择应用限制。

    选择一种限制类型，并按照限制列表提供所需信息。

    限制类型 说明
    HTTP 引荐来源网址 指定一个或多个引荐来源网站。可以使用通配符来为所有子网域授权（例如，*.google.com 接受所有以 .google.com 结尾的网站）。按原样指定 https:// 和 http://。您必须为其他类型的引荐来源网址协议使用特殊表示法。例如，将 file:///path/to/ 的格式设置为 __file_url__//path/to/*。启用引荐来源网址之后，请务必监控您的使用情况，确保与您的预期相符。支持以下引荐来源网址协议：about://, app://, applewebdata://, asset://, chrome://, content://, file://, ftp://, ionic://, local://, ms-appx://, ms-appx-web://, ms-local-stream://, prism://, qrc://, res://, saphtmlp://。
    IP 地址 指定一个 IPv4 或 IPv6 地址，或采用 CIDR 表示法的子网。由于网络服务请求会检查外部 IP 地址，并将该地址与 API 密钥限制进行比较，因此请使用服务器的公共 IP 地址。
    Android 应用 添加 SHA-1 签名证书指纹和 AndroidManifest.xml 文件中的 Android 软件包名称。
    iOS 应用 在类型下方，从列表中选择相应的 iOS 软件包标识符。

  4. 选择保存。

为 API 密钥设置 API 限制

  1. 前往“凭据”页面。

  2. 选择您要设置限制的 API 密钥。 系统会显示限制和重命名 API 密钥页面。

  3. 在API 限制下：

    • 点击限制密钥。

    • 点击选择 API 下拉列表，然后选择您想要应用通过该 API 密钥访问的 API 或 SDK。

      （如果其中未列出某个 API 或 SDK，您需要启用它。）

  4. 点击保存。

    完成此步骤后，所设限制将成为 API 密钥定义的一部分。如果您没有提供适当的详细信息或没有点击“保存”，系统将不会限制 API 密钥。（如需了解详情，请参阅您感兴趣的特定 API 或 SDK 对应的获取 API 密钥指南。）

删除未使用的 API 密钥

在删除 API 密钥之前，请确保其未在生产环境中使用。如果没有成功的流量，或许可以放心删除密钥。

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

  1. 前往“凭据”页面。

  2. 选择要删除的 API 密钥。

  3. 选择页面顶部附近的删除按钮。

  4. 在出现删除凭据对话框时，选择删除。

    删除 API 密钥的操作需要几分钟时间才能生效。生效后，使用已删除的 API 密钥的流量将遭到拒绝。

保障 API 安全的其他方式

重新生成 API 密钥时要小心谨慎

重新生成 API 密钥会创建一个具备原有密钥的所有限制的新密钥。此外，系统还会启动一个计时器，在 24 小时后停用原有 API 密钥。

在此时间段内，旧密钥和新密钥都会被接受，以便您可以迁移应用以使用新密钥。不过，此期限结束后，仍在使用旧 API 密钥的所有应用都将停止运行。

  1. 前往“API 密钥”页面。

  2. 选择还原为上一个密钥。

  3. 在还原对话框中，点击还原密钥。

回滚后，之前的“新”密钥版本会变成上一个版本，并会为此设置一个新的 24 小时停用计时器。您可以在这两个密钥值之间进行还原，直至您再次重新生成密钥。

第二次重新生成操作会覆盖原有的无效密钥值。

监控 API 使用情况

如需查看您的 API 密钥使用情况，请执行以下操作：

  1. 前往“指标”页面。

  2. 点击显示过滤条件。

  3. 从分组依据中，选择 API 方法。

  4. 在响应代码下，选择 2xx 查看针对此密钥的所有成功请求。

如果您检测到未经授权的使用，请执行以下操作：

  1. 限制您的密钥。

    如果多个应用使用相同的密钥，请迁移到多个 API 密钥，最好为每个应用使用单独的 API 密钥。

  2. 如果未经授权的使用仍然存在，请重新生成或删除受影响的密钥。

  3. 与支持团队联系。

为每个应用使用单独的 API 密钥

这可限制每个密钥的使用范围。如果 API 密钥泄露，您可以删除或重新生成受影响的密钥，而无需更新其他 API 密钥。

迁移到多个 API 密钥

如需进行迁移，以便“从多个应用使用一个 API 密钥”改为“每个应用使用一个唯一的 API 密钥”，请执行以下操作：

  1. 确定哪些应用需要新密钥。

    • 您可以控制 Web 应用的所有代码，因此这类应用最容易更新。计划更新您所有 Web 应用的密钥。
    • 更新移动应用要困难得多，因为您的客户必须先更新他们的应用，然后才能使用新密钥。

  2. 创建并限制新密钥。

    • 添加一项应用限制和至少一项 API 限制。

  3. 将新密钥添加到您的各个应用中。

    • 对于移动应用，此过程可能需要数月时间，以便所有用户更新到使用新 API 密钥的最新应用。

地图网络服务 API 或静态网络 API 应用保护方法

  • 在应用源代码以外的地方存储 API 密钥和签名密钥。如果您将 API 密钥或任何其他私密信息置于环境变量中，或添加单独存储的文件然后共享代码，那么 API 密钥或签名密钥不会包含在共享文件中。

  • 将 API 密钥或签名密钥存储在应用源代码树之外的文件中。如果您将 API 密钥或任何其他私密信息存储在文件中，请将文件保留在应用的源代码树之外，以确保密钥不会进入源代码控制系统。如果您使用公共源代码管理系统（如 GitHub），这种做法尤为重要。

网络服务 API 或静态网络 API 移动应用保护方法

更多信息

以下表格列出了每个 Google Maps Platform API、SDK 或服务的相应 API 密钥限制和 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) 最佳实践
Address Validation API “IP 地址”限制(4) Address Validation API
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 万次地图加载）。

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

4 在某些情况下，设置 IP 限制可能不切实际，例如在依赖动态 IP 地址的移动应用和云环境中。在这些情况下使用地图网络服务 API 时，请使用代理服务器和/或混淆来保护应用。

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