Google Maps Platform 安全指南

对于使用 Google Maps Platform API 和 Google Maps Platform SDK 的应用和项目，您必须使用 API 密钥或 OAuth（如果支持的话）来防范未经授权的使用行为和扣款。如果您使用的是 API 密钥，为了尽可能提高安全性，请在创建 API 密钥时对其加以限制。以下是有关如何限制 API 密钥的最佳实践。

除了施加应用和 API 密钥限制之外，还应遵循适用于特定 Google Maps Platform 产品的所有安全性实践。例如，参阅下文建议的应用限制和 API 限制部分中的 Maps JavaScript API 相关内容。

如果您的 API 密钥已在使用中，请参阅下文如果您要限制或重新生成正在使用的 API 密钥部分中的建议。

如需详细了解数字签名，请参阅数字签名指南。

建议的最佳实践

为了提高安全性并避免因未经授权的使用行为而产生费用，请遵循以下 API 安全性最佳实践（适用于所有 Google Maps Platform API、Google Maps Platform SDK 或 Google Maps Platform 服务）：

限制您的 API 密钥

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

删除未使用的 API 密钥

查看您的 API 密钥的使用情况

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

针对使用静态 Web API 的网站的其他建议

保护使用静态 Web API 的应用

针对使用 Web 服务的应用的其他建议

保护使用 Web 服务的应用

针对 iOS 和 Android 移动应用的其他建议

保护使用 Web 服务或静态 Web API 的移动应用

如果您要限制或重新生成正在使用的 API 密钥

  • 在更改 API 密钥之前，请先查看您的 API 密钥的使用情况。如果您要在开始使用密钥后添加限制，那么这一步尤为重要。

  • 更改密钥后，根据需要使用新的 API 密钥更新所有应用。

  • 如果您的 API 密钥目前没有被滥用，您可以按照自己的节奏，让应用改用多个新的 API 密钥，同时保持原始 API 密钥不变，直到仅存在一种类型的流量，这时您就可以通过设置应用限制来针对这种流量进行 API 密钥限制。如需获取进一步的说明，请参阅改用多个 API 密钥。

    持续监控 API 密钥的使用情况，直到发现特定 API、平台类型和网域弃用旧 API 密钥后，再选择限制或删除旧密钥。如需了解详情，请参阅报告和监控以及指标。

  • 如果您的 API 密钥已被泄露，那么您需要更快速地采取行动，以确保您的 API 密钥安全无虞并阻止滥用行为。在 Android 和 iOS 应用中，要等到用户更新其应用后，才能更换密钥。JavaScript 或 Web 服务应用中密钥的更新或更换要简单得多，但仍需认真规划并快速完成。

    如需了解详情，请参阅处理未经授权使用 API 密钥的行为。

限制您的 API 密钥

最好是始终使用应用限制以及一项或多项 API 限制来对您的 API 密钥加以限制。若要查看按 API、SDK 或 JavaScript 服务建议的限制，请参阅下文中建议的应用限制和 API 限制。

  • 应用限制：您可以将 API 密钥的适用范围限定为特定平台（Android 或 iOS 应用）、特定网站（针对客户端应用），或者特定 IP 地址或 CIDR 子网（针对发出 Web 服务 REST API 调用的服务器端应用）。

    限制密钥时，您可以根据想要授权的类型，添加一项或多项应用限制。一旦设置了应用限制，就只有这些来源可以提出请求。

  • API 限制：您可以限制 API 密钥能够用于哪些 Google Maps Platform API、Google Maps Platform SDK 或 Google Maps Platform 服务。设置 API 限制后，请求只能发送给您指定的 API 和 SDK。对于任何给定的 API 密钥，您可以根据需要指定任意数量的 API 限制。可用 API 列表中包含已为项目启用的所有 API。

为 API 密钥设置应用限制

  1. 在 Google Cloud 控制台中，打开 Google Maps Platform 的“凭据”页面。

  2. 选择您要设置限制的 API 密钥。

  3. 在密钥限制下的“修改 API 密钥”页面中，选择设置应用限制。

    “修改 API 密钥”页面

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

    限制类型 说明
    网站 指定一个或多个引荐来源网站。
    • https 和 http 是普遍支持的引荐来源网址 URI scheme。
    • 请始终提供完整的引荐来源网址 URI，包括协议 scheme、主机名和可选端口（例如 https://google.com）。
    • 您可以使用通配符来为所有子网域授权。例如，指定 https://*.google.com 表示接受所有以 .google.com 结尾的网站。请注意，如果指定 www.domain.com，它将充当通配符 www.domain.com/*，并为该主机名上的任何子路径授权。
    • 授权完整路径引荐来源网址（例如 https://google.com/some/path）时务必要小心谨慎，因为默认情况下，目前大多数的浏览器都会去除跨源请求中的路径。
    IP 地址 指定一个或多个 IPv4 或 IPv6 地址，或采用 CIDR 表示法的子网。IP 地址必须与 Google Maps Platform 服务器观测到的来源地址一致。如果您使用网络地址转换 (NAT)，则该地址通常对应于您计算机的公共 IP 地址。
    Android 应用 添加您要授权的每个 Android 应用的 Android 软件包名称（来自 AndroidManifest.xml 文件）和 SHA-1 签名证书指纹。如果您使用 Play 应用签名来提取签名证书指纹，请参阅与 API 提供商合作。如果您自行管理签名密钥，请参阅对应用进行自签名或适用于您的构建环境的说明。
    iOS 应用 添加您要授权的每个 iOS 应用的软件包标识符。

    如需获取应用限制方面的建议，请参阅建议的应用限制。

  5. 选择保存。

为 API 密钥设置 API 限制

  1. 在 Google Cloud 控制台中，打开 Google Maps Platform 的“凭据”页面。

  2. 选择您要设置限制的 API 密钥。

  3. 在 API 限制下的“修改 API 密钥”页面中，执行以下操作：

    • 选择限制密钥。

    • 打开选择 API，然后选择您想让应用通过该 API 密钥访问的 API 或 SDK。

      如果所需的某个 API 或 SDK 未列出，您需要启用它。如需了解详情，请参阅如何启用一个或多个 API 或 SDK。

    在“修改 API 密钥”页面，对 API 设置限制

  4. 选择保存。

    完成此步骤后，所设限制将成为 API 密钥定义的一部分。请务必提供适当的详细信息并选择保存，以保存您设置的 API 密钥限制。如需了解详情，请参阅文档中与您感兴趣的特定 API 或 SDK 对应的获取 API 密钥指南。

如需了解建议的 API 限制，请参阅建议的 API 限制。

查看您的 API 密钥的使用情况

如果您要在创建 API 密钥后对其加以限制，或者想查看密钥正在使用哪些 API，以便对它们设置限制，您需要查看 API 密钥的使用情况。您可以按以下步骤操作，了解使用 API 密钥的服务和 API 方法。如果您发现除 Google Maps Platform 服务以外，还存在其他使用 API 密钥的情况，请进行调查，以确定是否需要添加更多限制来避免不必要的使用行为。您可以使用 Google Maps Platform Cloud 控制台 Metrics Explorer，来帮助确定要应用于您的 API 密钥的 API 限制和应用限制：

确定哪些 API 在使用您的 API 密钥

借助以下指标报告，您可以确定哪些 API 正在使用您的 API 密钥。借助这些报告完成下列操作：

  • 查看 API 密钥的使用方式
  • 发现异常使用情况
  • 帮助确认某个未使用的密钥是否可以放心删除。如需了解如何删除 API 密钥，请参阅删除未使用的 API 密钥。

应用 API 限制时，请使用这些报告创建要授权的 API 列表，或验证自动生成的 API 密钥限制建议。如需详细了解建议的限制，请参阅采用建议的限制。如需详细了解如何使用 Metrics Explorer，请参阅使用 Metrics Explorer 创建图表。

  1. 前往 Google Cloud 控制台的 Metrics Explorer 页面。

  2. 登录并选择您要检查的 API 密钥的项目。

  3. 前往 Metrics Explorer 页面，查看您的 API 类型：

    • 对于使用除 Maps Embed API 以外任何 API 的 API 密钥：请前往 Metrics Explorer 页面。

    • 对于使用 Maps Embed API 的 API 密钥：请前往 Metrics Explorer 页面。

  4. 检查每个 API 密钥：

    1. 选择添加过滤条件。

    2. 选择标签“credential_id”。

    3. 选择您要检查的密钥对应的值。

    4. 注意有哪些 API 目前在使用此 API 密钥，并确认使用情形是否符合预期。

    5. 完成上述操作后，选择有效的过滤条件所在行末尾的移除过滤条件 ，以删除额外的过滤条件。

  5. 针对其余的密钥重复上述操作。

  6. 将您的 API 密钥限制为仅用于目前正在使用的 API。

  7. 如果发现未经授权的使用行为，请参阅处理未经授权使用 API 密钥的行为。

使用 Metrics Explorer 选择正确的应用限制类型

在您完成验证并采取所有必要的措施，确保您的 API 密钥仅用于目前使用的 Google Maps Platform 服务后，还要确保针对该 API 密钥设置了正确的应用限制。

如果您的 API 密钥具有建议的 API 密钥限制，请应用这些限制。如需了解详情，请参阅采用建议的 API 密钥限制。

如果您的 API 密钥没有相关限制建议，请使用 Metrics Explorer，根据报告的 platform_type 确定要应用的应用限制类型：

  1. 前往 Google Cloud 控制台的 Metrics Explorer 页面。

  2. 登录并选择您要检查的 API 的项目。

  3. 前往此 Metrics Explorer 页面：Metrics Explorer。

  4. 检查每个 API 密钥：

    1. 选择添加过滤条件。

    2. 选择标签“credential_id”。

    3. 选择您要检查的密钥对应的值。

    4. 完成上述操作后，选择有效的过滤条件所在行末尾的移除过滤条件 ，以删除额外的过滤条件。

  5. 针对其余的密钥重复上述操作。

  6. 查看过您的 API 密钥适用的平台类型后，针对相应 platform_type 采用应用限制：

    PLATFORM_TYPE_JS
    针对密钥应用网站限制。
    PLATFORM_TYPE_ANDROID
    针对密钥应用 Android 应用限制。
    PLATFORM_TYPE_IOS
    针对密钥应用 iOS 应用限制。
    PLATFORM_TYPE_WEBSERVICE
    您可能需要对密钥应用 IP 地址限制，才能实现有效限制。如需了解适用于 Maps Static API 和 Street View Static API 的更多选项，请参阅保护使用静态 Web API 的应用。如需了解有关 Maps Embed API 的详细说明，请参阅使用 Maps Embed API 的网站。
    我的 API 密钥同时用于多个平台类型
    仅凭单个 API 密钥无法妥善保护您的流量。您需要改用多个 API 密钥。如需了解详情，请参阅改用多个 API 密钥。

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

这种做法可限制每个密钥的适用范围。如果某个 API 密钥泄露，您可以删除或重新生成受影响的密钥，而无需更新其他 API 密钥。您最多可以为每个项目创建 300 个 API 密钥。如需了解详情，请参阅有关 API 密钥的限制。

为安全起见，每个应用最好使用一个 API 密钥，但您可以针对多个应用使用受限制的密钥，前提是它们使用相同类型的应用限制。

采用建议的 API 密钥限制

对于某些项目所有者和编辑者，Google Cloud 控制台会根据其 Google Maps Platform 使用情况和活动，建议对不受限制的 API 密钥设置特定的 API 密钥限制。

如果有可用的建议，相应建议将作为预填充的选项显示在 Google Maps Platform“凭据”页面上。

可能导致您看不到建议或看到不完整建议的原因

  • 您（还）在 Google Maps Platform 之外的服务上使用相应 API 密钥。如果您在其他服务上使用该密钥，那么在采纳任何建议之前，请先完成以下操作：

    1. 确认在 Google Cloud 控制台的 Metrics Explorer 中看到的 API 使用情况都是合法的。

    2. 手动将缺失的服务添加到待授权的 API 列表中。

    3. 为添加到 API 列表中的服务手动添加所有缺失的应用限制。如果添加的其他服务需要不同类型的应用限制，请参阅改用多个 API 密钥。

  • 您的 API 密钥未用于客户端 SDK 或 API。

  • 您将 API 密钥用于最近 60 天内无人使用的低流量应用或网站。

  • 您最近创建了一个新密钥，或者最近在新应用中部署了一个现有密钥。如果是这种情况，您只需再多等几天，让系统更新建议即可。

  • 您将 API 密钥用于应用限制类型互相冲突的多个应用，或是将同一 API 密钥用于太多不同的应用或网站。无论是哪种情况，我们都建议您改用多个密钥。如需了解详情，请参阅改用多个 API 密钥。

可能导致建议在图表中不显示的原因

  • 您的应用或网站仅在非常短的时间内发送了大量流量。在这种情况下，请从图表视图切换为表格，或者选择显示两者，因为使用情况仍可在图例中看到。如需了解详情，请参阅切换图表的完整图例。

  • 您的流量来自 Maps Embed API。有关说明，请参阅确定哪些 API 在使用您的 API 密钥。

  • 来自应用或网站的流量不在 Google Cloud 控制台 Metrics Explorer 中的可用日期范围内。

  1. 在 Google Cloud 控制台中，打开 Google Maps Platform 的“凭据”页面。

  2. 选择采用建议的限制（如果有）。

    采用建议的限制

    注意：如果您未看到任何建议的限制，请参阅为 API 密钥设置 API 限制，以设置适当的限制。

  3. 选择查看 API 使用情况，确认在哪些服务上使用了相应 API 密钥。如果您看到 Google Maps Platform 之外的服务，请暂停并人工审核上面的建议步骤。查看采用建议的 API 密钥限制部分开头的问题排查步骤。

  4. 仔细检查预填充的限制是否与您希望使用 API 密钥的网站和应用相匹配。

    最佳实践：记录并移除与您的服务没有任何关联的应用或 API 限制。如果由于存在意料之外的依赖项而导致操作中断，那么您可以重新添加必需的应用或 API。

    • 如果您发现建议中明显缺少某个应用、网站或 API，请手动添加，或等待几天，以便系统更新建议。

    • 如果您需要建议方面的进一步帮助，请与支持团队联系。

  5. 选择采用。

如果您的应用在采用建议后被拒，该怎么办？

如果您发现应用或网站在采用限制后被拒，请在 API 响应错误消息中查找您需要添加的应用限制。

对于客户端 SDK，请参阅下文：

如需查看所需的 API 限制，请参阅确定哪些 API 在使用您的 API 密钥。

如果您无法确定要应用哪些限制，请执行以下操作：

  1. 记录当前限制以供将来参考。
  2. 在调查问题期间暂时移除相应限制。您可以根据查看您的 API 密钥的使用情况中的步骤，查看不同时间的使用情况。
  3. 可以视需要与支持团队联系。

删除未使用的 API 密钥

在删除 API 密钥之前，请确保其未在生产环境中使用。如果没有成功的流量，或许可以放心删除密钥。如需了解详情，请参阅查看您的 API 密钥的使用情况。

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

  1. 在 Google Cloud 控制台中，打开 Google Maps Platform 的“凭据”页面。

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

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

  4. 在删除凭据页面上，选择删除。

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

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

重新生成 API 密钥会创建一个具备旧密钥所有限制的新密钥。此外，该流程还会启动一个计时器，在 24 小时后删除旧 API 密钥。

在这段时间内，系统会同时接受旧密钥和新密钥，以便您让应用改用新密钥。不过，此时间段结束后，仍在使用旧 API 密钥的所有应用都将停止运行。

在重新生成 API 密钥之前：

  • 请先按照限制您的 API 密钥中所述的方法尝试限制您的 API 密钥。

  • 如果由于应用限制类型有冲突而无法限制您的 API 密钥，请按照改用多个 API 密钥中所述的方法改用多个新（受限）密钥。这样您就可以掌控改用流程，并安排改用新 API 密钥的时间。

如果前面的建议不可行，而且您必须重新生成 API 密钥以防范未经授权的使用，请按照以下步骤操作：

  1. 在 Google Cloud 控制台中，打开 Google Maps Platform 的“凭据”页面。

  2. 打开您想要重新生成的 API 密钥。

  3. 在页面顶部，选择重新生成密钥。

  4. 选择更换密钥。

注意：如有必要，您可以将重新生成的任何密钥回滚到之前的版本。针对回滚，没有任何时间限制。

若要回滚重新生成的密钥，请按以下步骤操作：

  1. 在 Google Cloud 控制台中，打开 Google Maps Platform 的“凭据”页面。

  2. 打开您要回滚的 API 密钥。

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

  4. 在还原对话框中，选择还原密钥。

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

再次重新生成的密钥会覆盖原有的无效密钥值。

改用多个 API 密钥

若要从“多个应用使用一个 API 密钥”改为“每个应用使用一个唯一的 API 密钥”，请执行以下操作：

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

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

  2. 创建并限制新密钥：添加一项应用限制以及至少一项 API 限制。如需了解详情，请参阅建议的最佳实践。

  3. 将新密钥添加至您的应用：对于移动应用，必须等到所有用户都更新到使用新 API 密钥的最新应用，这项流程才算完成，因此可能需要花费数月的时间。

保护使用静态 Web API 的应用

静态 Web API（例如 Maps Static API 和 Street View Static API）类似于 Web 服务 API 调用。

您可以使用简单的 HTTPS REST API 调用上述两种 API，并且您通常会在服务器上生成 API 请求网址。但是，静态 Web API 不会返回 JSON 响应，而是会生成一个图像，您可以将该图像嵌入到已生成的 HTML 代码中。更重要的是，调用 Google Maps Platform 服务的通常是最终用户客户端，而不是服务器。

使用数字签名

建议您除了 API 密钥之外，始终使用数字签名。此外，请检查您希望每天允许的未签名请求数量， 调整未签名请求的配额 。

如需详细了解数字签名，请参阅数字签名指南。

保护您的签名密钥

为了保护静态 Web API，请勿将您的 API 签名密钥直接嵌入到代码或源代码树中，或将其暴露在客户端应用中。为了保护您的签名密钥安全无虞，请遵循下列最佳实践：

  • 在服务器端而不是客户端对请求进行签名。如果您在客户端通过 JavaScript 进行签名，那么您会将密钥暴露给访问您网站的所有用户。因此，对于动态生成的图像，请始终在传送网页时在服务器端生成已签名的 Maps Static API 和 Street View Static API 请求网址。对于静态 Web 内容，您可以使用 Cloud 控制台中 Google Maps Platform 凭据页面上的立即对网址进行签名 widget。

  • 将签名密钥存储在应用的源代码和源代码树以外的位置。如果您将签名密钥或任何其他私密信息置于单独存储的环境变量或包含文件中，然后再共享您的代码，那么签名密钥不会包含在共享文件中。如果您将签名密钥或任何其他私密信息存储在文件中，请将文件存放在应用的源代码树之外，以确保签名密钥不会进入您的源代码控制系统。如果您使用公共源代码管理系统（如 GitHub），这种预防措施尤为重要。

在使用 Web 服务的应用中保护您的 API 密钥

将 API 密钥存储在应用的源代码或源代码树之外。如果您将 API 密钥或任何其他信息置于单独存储的环境变量或包含文件中，然后再共享代码，那么 API 密钥不会包含在共享文件中。如果您使用公共源代码管理系统（如 GitHub），这种做法尤为重要。

在使用 Web 服务或静态 Web API 的移动应用中，保护您的 API 密钥和签名密钥

若要保护移动应用，请使用安全的密钥库或安全的代理服务器：

  • 将 API 密钥或签名密钥存储在安全的密钥库中。此步骤会增加直接从应用中爬取 API 密钥和其他私密数据的难度。

  • 使用安全的代理服务器。您可以通过代理服务器与适当的 Google Maps Platform API 进行互动。如需详细了解如何使用代理服务器，请参阅代理体验：将代理服务器与 Google Data API 客户端库配合使用。

    • 在代理服务器上构建您的 Google Maps Platform 请求。请勿允许客户端通过代理中继任意 API 调用。

    • 在代理服务器上对 Google Maps Platform 响应进行后续处理，并过滤掉客户端不需要的数据。

处理未经授权使用 API 密钥的行为

如果您检测到未经授权使用 API 密钥的行为，请执行以下操作来解决该问题：

  1. 限制密钥：如果您在多个应用中使用了相同的密钥，请改用多个 API 密钥，并为每个应用使用单独的 API 密钥。如需了解详情，请参阅：

  2. 仅在您无法对密钥进行限制时重新生成密钥。在继续操作前，请仔细阅读重新生成 API 密钥时要小心谨慎部分。

  3. 如果您仍有疑问或需要帮助，请与支持团队联系。

建议的应用限制和 API 限制

以下各部分针对各个 Google Maps Platform API、Google Maps Platform SDK 或 Google Maps Platform 服务提供了适当的应用限制和 API 限制建议。

建议的 API 限制

以下 API 限制指南适用于整个 Google Maps Platform：

  • 将您的 API 密钥限制为仅适用于您想要应用该 API 密钥的 API，以下情况除外：

    • 如果您的应用使用的是 Places SDK for Android 或 Places SDK for iOS，请为 Places API 提供相应授权。

    • 如果您的应用使用的是 Maps JavaScript API，请始终授权该 API 使用密钥。

    • 如果您还使用以下任意 Maps JavaScript API 服务，那么您还应额外为以下 API 提供相应授权：

    服务 API 限制
    路线服务 (Maps JavaScript API) Directions API
    距离矩阵服务 (Maps JavaScript API) Distance Matrix API
    海拔服务 (Maps JavaScript API) Elevation API
    地理编码服务 (Maps JavaScript API) Geocoding API
    地点库 (Maps JavaScript API) Places API

部分示例：

  • 您使用的是 Maps SDK for Android 和 Places SDK for Android，因此您将 Maps SDK for Android 和 Places API 纳入到 API 限制范围中。

  • 您的网站使用的是 Maps JavaScript API 的海拔服务和 Maps Static API，因此您针对以下所有 API 添加了 API 限制：

    • Maps JavaScript API
    • Elevation API
    • Maps Static API

建议的应用限制

使用 Maps JavaScript API 或静态 Web API 的网站

对于使用 Maps JavaScript 服务或静态 Web API 的网站，请采用 Websites 应用限制。

适用于使用以下 JavaScript 服务和 API 的网站：

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

2 另外，还可以参阅保护使用 Web 服务或静态 Web API 的移动应用。

使用 Maps Embed API 的网站

尽管使用 Maps Embed API 是免费的，您仍应对任何已使用的 API 密钥加以限制，以防止密钥在其他服务中遭到滥用。

最佳实践：创建一个单独的 API 密钥以供 Maps Embed API 使用，并限定此密钥仅适用于 Maps Embed API。此限制足以确保密钥安全无虞，防止在任何其他 Google 服务中未经授权使用此密钥。

如果您无法创建 Maps Embed API 专属的 API 密钥，请使用 Websites 应用限制来保护您的密钥。

使用 Web 服务的应用和服务器

对于使用 Web 服务的应用和服务器，请采用 IP addresses 应用限制。

适用于使用以下 API 的应用和服务器：

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

Android 应用

对于 Android 应用，请采用 Android apps 应用限制。 适用于使用以下 SDK 的应用和服务器：

此外，通过使用 Secrets Gradle 插件从本地文件注入密钥，而不是将其存储在 Android 清单中，可以防止意外地将 API 密钥签入到版本控制中。

iOS 应用

对于 iOS 应用，请采用 iOS apps 应用限制。 适用于使用以下 SDK 的应用和服务器：