排查 Google Maps APIs Premium Plan 网址授权问题

Google Maps APIs Premium Plan 客户端 ID 仅限于专门授权的网址。如果您尝试在未获授权的网址中使用您的客户端 ID,将收到错误消息。

本文旨在帮助遇到该问题并需要查找需授权的确切网址的 Google Maps APIs for Work 客户。

基础知识

为了防止第三方在他们自己的网站上使用您的客户端 ID,客户端 ID 的使用范围被限制为您专门授权的网址列表。每个网址可以具体到单个网页,也可以宽泛到整个域。

要获得已获授权的网址的列表,或要授权更多网址,请执行以下操作:

  1. 登录 Google Cloud Support Portal
  2. 在左侧菜单中,点击 Maps:Manage Client ID

您一次最多可以添加 100 个网址,总共可添加 3000 个网址。如果您需要更高的限额,请联系 Google Cloud Support。

有关授权网址的详细信息,请参阅开发者指南

问题

若应用所用的网址未获得使用您的客户端 ID 的授权,则该应用将无法通过您的客户端 ID 使用 Google Maps APIs。试图使用此类应用的用户将收到错误消息,具体取决于应用尝试加载的特定 API。用户将无法使用依赖 Google Maps JavaScript API 的功能。

  • Google Maps JavaScript API 将显示以下消息:

    此页面无法显示 Google 地图元素。此网址未获得使用提供的 Google 地图客户端 ID 的授权。Error Code:UnauthorizedURLForClientIdMapError

  • 如果您使用 Google Maps JavaScript API v3.18 或更早的版本,将显示以下消息:

    Google 已对此应用停用 Google Maps APIs。此网站未获得使用提供的 Google 地图客户端 ID 的授权。如果您是此应用的所有者,可以通过开发者指南详细了解如何注册网址。

从应用中删除客户端 ID 不能有效解决问题*。如果这样做,您的这个应用将失去所有 Google Maps APIs Premium Plan 权益。这意味着您将无权享受以下服务:

  • 可靠的服务等级协议 (SLA)。
  • 客户支持。
  • 提高的网络服务限额。
  • 商业级条款和条件。
  • 工作场所内的内网应用支持。

这意味着只在内部使用、需付费以及未正确使用有效 Google Maps APIs Premium Plan 客户端 ID 的应用将不符合免费 Google Maps APIs 服务条款

解决方法

正确的解决方案是找到并授权正确的网址,以使用您的客户端 ID。

大多数情况下,您需要授权应用使用您的客户端 ID。应用通常使用模式相同的多个网址,例如,店铺定位工具可以使用 example.com/storesstores.example.com。您需要找到可以匹配您应用使用的所有网址的网址。

:授权 www.example.com不会授权 stores.example.comexample.com 的任何其他子网域。

每个网址可以具体到单个网页,也可以宽泛到整个域(包括其子网域)。有关详情,请参阅开发者指南。我们建议授权可与相当广泛的一组网址匹配的网址,前提是您将管理这些网址。

:我们建议不要授权整个网域,除非您的组织能够完全控制网域中的内容。例如,授权整个 blogspot.com 网域的结果是,每个人都可以通过该网域使用您的客户端 ID,而费用却由您来承担。更好的做法是,您可以仅授权某个特定博客(如 googlegeodevelopers.blogspot.com),或该博客中的某个特定页面。

如何查找正确的网址

通常情况下,您可以在浏览器的地址栏中找到网址。在不使用 <iframe> 标记的公共网站上,通常很容易就能找到网址。如果心存疑虑,您可以通过以下方式进行验证。

复杂应用加载 Google Maps APIs 所用的网址可能会与用户地址栏中的网址不同。如果使用 <iframe> 标记,或者加载 API 的网页网址在服务器上动态生成,然后发送至浏览器,将出现这种情况。在这些情况下,查找正确的网址需要检查从浏览器发送到 Google 服务器的特定 HTTP 请求。

需要授权的网址是浏览器发送至 Google 的 API 加载请求中,位于 Referer 标头部分的网址。每个 API 从不同的网址加载:

maps.googleapis.com 的所有请求都会发送至 maps.google.commaps-api-ssl.google.com,具体取决于应用设置为如何加载 API。因此,在查找上述请求时,路径(粗体)往往非常重要。

在浏览器中捕获 HTTP 标头

在检查上述请求中的 Referer 标头前,您必须先从浏览器捕获它们。下列多款免费工具可以帮助您在所有主流浏览器中捕获 HTTP 标头:

:您需要配置 Fiddler2 才能捕捉 HTTPS 流量。有关详情,请点击此处

如果您无法直接从浏览器捕获 HTTP 标头,可以使用网络协议分析器(如 Wireshark)尝试捕获 HTTP 流量。这款工具的操作可能比上述工具更加复杂,如果您对它不熟悉,请在网络上查看一些 Wireshark 教程

选择好工具后,请按照以下步骤查找需要授权的网址:

  1. 启动捕获工具。确保该工具从您的浏览器捕获 HTTP 请求。
  2. 将浏览器指向无法使用您的客户端 ID 加载 Google Maps APIs 的应用。您应该会收到上述错误消息之一。
  3. 停止捕获 HTTP 流量。这样将可以更轻松地检查已捕获流量。
  4. 查找尝试使用您的客户端 ID 加载 Google Maps APIs 的请求。例如,如果您的应用尝试加载 Google Maps JavaScript API,则查找如下请求:
    GET /maps/api/js?client=gme-yourclientid HTTP/1.1
  5. HTTP 请求标头会紧跟在这一行内容后面出现,没有换行符。查找如下内容:
    Referer: http://www.example.com/stores/find?zip=94043
  6. 该行中的网址就是需要授权以允许其使用您的客户端 ID 的网址。

通过浏览器中的 JavaScript 控制台

如果您在未经授权的网站中使用 API 密钥或客户端 ID,则 Google Maps JavaScript API 会在 window.console 中显示错误消息。您可以在错误消息中找到正确的网址。在控制台中,搜索如下错误消息:

Google Maps APIs error: UnauthorizedURLForClientIdMapError ...
Your site URL to be authorized: http://www.example.com/stores/find?zip-94043

如需有关如何查找错误消息的帮助,请参阅在浏览器中检查错误部分。

查找常见模式

为确保整个应用都将可以使用您的客户端 ID 加载 Google Maps APIs,您需要根据开发者指南中说明的规则,查找应用使用的所有网址的共同模式,并授权能够代表该模式的网址。

这往往非常简单,可能只是一个目录(如 example.com/stores)或子网域(如 stores.example.com),通常可以通过几个网址轻易推导出来。

在处理复杂的应用时,您可能需要对一些会显示地图、面向用户的网址重复上述步骤。但是,这样做可能太费力,并且所得到的网址集仍可能不完整。对于此类应用,其开发者可能是提供网址模式的最佳人选。