排查 Google Maps Platform 高级计划的网址授权问题

在 Google Cloud Console 中的什么位置管理客户端 ID

高级计划客户端 ID 管理功能即将从支持门户迁移到 Cloud Console 上的 Google 地图“凭据”页面,位于服务帐号部分下方。

“凭据”页面上新的“客户端 ID”区域

注意:Google Maps Platform 高级计划不再开放注册,也不再提供给新客户。

Google Maps Platform 高级计划客户端 ID 仅可用于获得专门授权的网址。如果您尝试在未获授权的网址中使用您的客户端 ID,将收到错误消息。

本文面向的就是遇到此问题,并需要查找需获得授权的确切网址的 Google Maps Platform 高级计划客户。

基础知识

为了防止第三方在他们自己的网站上使用您的客户端 ID,我们设置了限制:只有部分网址能使用您的客户端 ID,且这些网址需要获得您的授权。每个网址可以具体到单个网页,也可以宽泛到整个网域。

若要获取您已授权的网址列表,或要授权更多网址,请转到凭据页面,然后滚动到客户端 ID 部分。

您一次最多可添加 100 个网址。一个客户端 ID 最多可与 3000 个已授权网址关联。如果您希望自己的应用在超过 3000 个位置托管 Google 地图内容,应改为使用 API 密钥。

您还可参阅开发者指南,了解更多为网址授权的相关信息。

问题

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

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

    此页面无法显示 Google 地图元素。此网址未获得相关授权,无法使用提供的 Google 地图客户端 ID。错误代码:UnauthorizedURLForClientIdMapError

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

    Google 已禁止此应用使用 Google Maps Platform。此网址未获得相关授权,无法使用提供的 Google 地图客户端 ID。如果您是此应用的所有者,可以参阅开发者指南详细了解如何注册网址。

从应用中移除客户端 ID 不能有效解决问题*。如果这样做,您将失去该应用的所有 Google Maps Platform 高级计划特权。这意味着您将失去以下特权:

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

这意味着,标准 Google Maps Platform 服务条款不适用于只在内部使用或需要付费的,且未使用有效 Google Maps Platform 高级计划客户端 ID 的应用。

解决方法

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

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

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

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

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

如何查找正确的网址

通常情况下,您可以在浏览器的地址栏中找到网址。在不使用 <iframe> 标记的公共网站上,通过这种方法通常可以轻松找到网址。如有疑问,您可以通过以下方式进行验证。

复杂的应用加载 Google Maps Platform 的网址可能与用户地址栏中的网址不同。如果使用 <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 Platform 的应用。您应该会收到上述错误消息之一。
  3. 停止捕获 HTTP 流量。这样可以更轻松地检查已捕获流量。
  4. 查找尝试使用您的客户端 ID 加载 Google Maps Platform 的请求。例如,如果您的应用尝试加载 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,Maps JavaScript API 会在 window.console 中写入错误消息。您可以在错误消息中找到正确的网址。在控制台中,搜索如下错误消息:

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

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

查找常用格式

为确保整个应用都能使用您的客户端 ID 加载 Google Maps Platform,您需要按照开发者指南中说明的规则在应用所用的所有网址中找到常用格式,并授权能代表此格式的网址。

格式通常非常简单,可能只是一个目录(如 example.com/stores)或子网域(如 stores.example.com),一般通过几个网址即可轻松推断出来。

在处理复杂的应用时,您可能需要对一些面向用户且会显示地图的网址重复上述步骤。不过,这可能会非常麻烦,而且得到的一系列网址可能仍然不完整。对于此类应用,其开发者可能是提供网址格式的最佳人选。