Google Maps APIs for Work 启动前检查单

此页面仅适用于拥有旧版 Maps APIs for Work 或 Maps API for Business 许可的客户。此页面不适用于拥有新版 Google Maps APIs Premium Plan2016 年 1 月上市发售)的客户。

  1. 确保您的团队可以获取必要资源
    1. 接收 Google Maps APIs for Work 欢迎信
    2. 访问和使用 Google Cloud Support Portal
    3. 订阅相关的通知 Feed
    4. 随时拨打支持热线
  2. 应用优化
    1. 配置防火墙以允许访问 Google Maps APIs 服务
    2. 通过 SSL 加载 API
    3. 在您的 SSL 域名中使用客户端 Maps API
    4. 选择正确的 API 版本
    5. 优化页面查看消耗
    6. 客户端与服务器端设计:挑选适合您的用例的设计
    7. 网络服务配额和管理
    8. 负载测试
  3. 从免费服务迁移到 Google Maps APIs for Work 实现
    1. 域名授权
    2. 集成您的客户端 ID
    3. 利用加密密钥签署网络服务请求
    4. 跟踪应用消耗和 channel 参数
    5. 从您的 API 请求中移除过时参数

确保您的团队可以获取必要资源

接收 Google Maps APIs for Work 欢迎信

为何重要:欢迎信是您的 Google Maps APIs for Work 启动工具包,也可能是您的应急工具包。它包含您的客户端 ID 和加密密钥等重要信息,您开始使用 Google Maps APIs 时需要使用这些信息。欢迎信还包含联系 Google Cloud Support 团队所需的信息,便于您在使用任意 Google Maps APIs 的过程中遇到任何技术问题时与我们联系。

访问和使用 Google Cloud Support Portal

为何重要:支持门户让您可以获取众多信息,例如消耗报告、新闻 Feed 和有用的开发者资源。更重要的是,支持门户还允许您向 Google Maps APIs 支持团队提交支持案例,便于您在开发或启动期间遇到任何技术问题时与我们联系。您可以通过以下网址访问支持门户:

https://google.secure.force.com/

在启动前,请花一定的时间为负责应用维护的所有开发者启用支持门户访问权限。如果您遇到技术问题,访问支持门户将带来双重优势:既可以让您团队的成员联系支持,又能让我们的支持团队与贵组织中相应的利益干系人联系。例如,如果我们检测到异常流量或行为(这些最终可能会对您的应用造成破坏),支持团队可能需要联系贵组织。确保我们能够联系相应的开发者可以防止您的服务出现中断,避免出现意外。如果您无法访问支持门户,请通过下面的链接请求访问权限:

请求 Google Cloud Support Portal 帐号

订阅相关的通知 Feed

为何重要:为了确保您及时掌握 Google Maps APIs 最新的开发和变更信息,我们建议您订阅相关的通知 Feed。您应为自己使用的 API 订阅 Google Geo 开发者博客和相关的通知性 Google 网上论坛,下面的链接介绍了订阅方式:

https://developers.google.com/maps/faq#notify

现在,请花一点时间为您正在使用或计划使用的 API 订阅通知论坛。您还可以订阅下面的 RSS Feed:

http://google.force.com/services/xml/MapsRSS

来接收 Google Maps APIs 支持团队的动态。

随时拨打支持热线

1-877-355-5787(美国客户),+1 404-978-9282(美国以外的客户)

为何重要:热线是您通过电话联系 Google Cloud Support Portal 的方式。请将此页面加入书签,方便您查找最新的支持热线号码。请注意,尽管欢迎您利用支持热线向我们的团队报告技术问题,但这种方式仅用于停机和服务不可用的情况。我们的优先级别在下面的网页中进行了相关定义:

https://support.google.com/work/answer/184028

应用优化

配置防火墙以允许访问 Google Maps APIs 服务

为何重要:Google Maps APIs 服务使用各种域名,其中一些不属于 *google.com 域名。如果您使用限制性防火墙,则允许访问每个 Maps API 服务使用的域名显得至关重要。如果您的防火墙不允许访问这些域名,那么 API 请求将失败,这会中断您应用的正常工作。您可以在 Support Portal 中找到每个 Maps API 所用域名的完整列表:

  1. 登录 Google Cloud Support Portal
    只有具有 Google Maps APIs Premium Plan或者旧版 Google Maps APIs for Work 或 Google Maps for Business 许可的客户才能使用 Support Portal。
  2. 导航到 Resources 标签。
  3. 选择 List of domains used by the Google Maps APIs family
  4. 允许您的应用访问列示的域名。

我们不建议通过 IP 地址管理防火墙限制,因为与这些域名关联的 IP 不是静态 IP。

:Google Maps APIs 服务分别为入站和出站流量使用端口 80 (http) 和 443 (https)。这些服务还需要 GET、POST、PUT、DELETE 和 HEAD 请求。配置您的防火墙,以便允许通过这些端口传输流量和允许请求,具体取决于 API 和用例。

通过 SSL 加载 API

为何重要:通过 SSL 加载 Maps JavaScript APIWeb Service API图像 API 的应用应从 https://maps.googleapis.com 执行加载,而不是从旧主机名 https://maps-api-ssl.google.com 加载。

在您的 SSL 域名中使用客户端 Maps API

为何重要:将客户端 API 与 SSL 域名搭配使用时,明确授权您的 HTTPS 域名非常有必要,这样可以确保您的请求不被拒绝。请注意,授权 http://yourdomain.com 不会自动启用其 SSL 等效网址域名 https://yourdomain.com。您可以通过以下方式在 Google Cloud Support Portal 中查看已获授权的域名列表:从左侧导航菜单中选择 Maps:Manage Client ID 链接。要对将 API 与 SSL 域名搭配使用时遇到的错误进行问题排查,我们鼓励您先检查页面有无元素通过 HTTP 加载。另请参阅我们的排查 Google Maps APIs for Work 实现的授权问题一文。

选择正确的 API 版本

为何重要:在开发您的应用前,务必了解哪些版本的 API 已经弃用。在已弃用版本不可用之后,使用非弃用版本的 API 开发应用将节省您整体的开发时间和成本。

另外也要了解 API 的版本控制策略,以免在您的环境中意外使用不正确版本的 API:

https://developers.google.com/maps/documentation/javascript/versions

例如,尽管可能适合在您的开发/测试环境中使用 Nightly(即,实验性)版本的 API,但是我们强烈反对在生产环境中使用 Nightly 版本。我们的 SLA 仅适用于稳定版本的 API,因此,您在生产环境中仅应使用稳定版本。

优化页面查看消耗

为何重要:如果您并不总是在自己的网站上显示 Google 地图,为什么还要付费呢?作为更高效使用页面查看次数的最佳做法,我们建议当您实际显示地图时在这些页面上异步加载 Maps API。这会显著减少您的应用消耗的已购买页面查看次数。请记住,加载 API 的页面每次刷新时,它都会引起一次页面查看。因此,在设计您的应用时,我们建议您的加载 API 的网站仅在绝对需要时才启动页面刷新。

客户端与服务器端设计:挑选适合您的用例的设计

为何重要:选择客户端还是服务器端方式是一个架构决策,对应用的稳定性和可扩展性特别重要。总体来说,应为离线的(即,在应用外部)记录前处理和后处理使用服务器端方式。相应地,应为与用户交互的应用部分(即,实时处理用户提交的请求)使用客户端方式。

应使用客户端方式但却部署了服务器端方式是超出配额并继而中断应用工作的首要原因。我们强烈建议您先查阅地理编码策略文档,然后再设计或启动依赖于服务器端调用的应用。

网络服务配额和管理

为何重要:默认情况下,网络服务配额设置为每 24 小时 100,000 次查询。如需了解具体到各个 API 的更详细配额划分,请参阅使用限制文档。要确认您的客户端 ID 可以使用多少配额,请提交一个支持案例。在启动服务之前,务必了解不同的配额相关错误(例如,OVER_QUERY_LIMITUser Rate Limit Exceeded),并在您的应用中设置相应逻辑,以便在您超出配额时响应此类错误。请先阅读 Google Maps APIs 网络服务的使用限制一文。了解和实现这些概念将大大降低您的应用超出允许的配额、被 Google 阻止和/或中断工作的几率。

负载测试

为何重要:使用实时 Google 服务进行负载测试将使您的应用超出允许的配额并被 Google 阻止。

Google Maps APIs 可以处理数量庞大的请求;2012 年,追踪圣诞老人每秒处理 1,600,000 次请求。因此,不需要使用 Google 服务进行负载测试。相比之下,对您的应用进行负载测试应确保您的应用可以应对大量的请求,而不超出 Maps API 的配额。示例:如果您的 Google Maps Geocoding API 配额为 20 QPS(每秒查询数),对您的应用进行负载测试应确保您的应用可以处理 600 QPS,而不会向 Google Maps Geocoding API 发送超过 20 QPS。

为了安全地实现此目标,请仅使用模拟(假)API 进行负载测试 - 这种服务可以吸收大量请求并通过有效响应回复请求,而涉及 Google Maps APIs。因此,您可以对您的应用进行负载测试,而不会冒着被 Google Maps APIs 阻止的风险。

请参阅下面一个模拟 API 示例,它作为一个小型 Google App 引擎应用实现: https://github.com/googlemaps/js-v2-samples/blob/gh-pages/mock_maps_apis/。您可以将此示例上传到您自己的 App 引擎应用(在您于 https://appengine.google.com/ 上注册一个之后),并使您的应用在该处发送请求,而不是发送到 maps.googleapis.com。

一般情况下,默认(免费)的 App 引擎配额应当足够对您的应用进行负载测试,并且远远超出 Maps API 网络服务的配额。请确保您的应用设置正确的 User-Agent 标头以启用响应压缩。这对确保有效使用带宽非常关键,对处理大量纯文本 (JSON/XML) 响应的 App 引擎应用也特别重要。如果您需要更高的 App 引擎应用配额,您也可以启用收费,尽管很少需要这样做。

将您的 API 从免费服务迁移到 Google Maps APIs for Work 许可

域名授权

为何重要:为了防止未经授权的网站使用您的客户端 ID,Google Maps JavaScript API 需要您通过我们的支持团队为将要利用您的客户端 ID 的所有网站授权全部域名。如果被授权使用您的客户端 ID 的网址与试图使用您的客户端 ID 的网站之间不匹配,您的网站将无法通过您的客户端 ID 使用 API。您可以随时授权域名,因此,请确保在启动前为您所有的网站授权域名。

Google Street View Image APIGoogle Static Maps API 既可以在客户端方式也可以在服务器端方式中使用,两种情况都会引起页面查看。因此,这些 API 要求您使用自己的加密密钥签署您的请求,以及授权利用这些 API 的任何域名。这样可以确保您的应用合理计费(按照我们的服务条款)、获得支持并纳入我们的 SLA。

您可以通过以下方式在 Google Cloud Support Portal 中查看已获授权的域名列表:从左侧导航菜单中选择 Maps:Manage Client ID 链接。

有关授权问题,我们建议您先查阅排查 Google Maps APIs for Work 实现的授权问题一文,然后再提交案例。

集成您的客户端 ID(例如 &client=gme-yourclientid

为何重要:您可以为自己的应用做的最重要事情之一是确保在您的请求中包含“&client=gme-yourclientid”。您可以在欢迎信中找到您的唯一客户端 ID,欢迎信已发送至贵组织的主要联系人。客户端 ID 将您的请求标识为 Google Maps APIs for Work 请求。您必须在自己的应用中包含您的客户端 ID 才能使用特定于 Google Maps APIs for Work 的任何功能。要获得技术支持和确保您的应用在我们的 SLA 涵盖范围内,也需要包含您的客户端 ID。

利用加密密钥(例如 vNIXE0xscrmjlyV-12Nj_BvUPaw=)签署网络服务请求

为何重要:您的私有加密密钥用于生成签名,此签名可以告知 Google 您的请求来自受信任的源。您可以在欢迎信中找到您的加密密钥,欢迎信已发送给贵组织的主要联系人。作为一名 Google Maps APIs for Work 客户,我们的网络服务要求您使用自己的加密密钥签署您的请求。这会为您的请求增加一层保险,更好地保护与您的客户端 ID 关联的配额。

请注意:加密密钥用于生成签名。请勿将其作为签名本身追加到您的请求中。您的加密密钥类似于 ATM PIN 号码。它可以用作一种访问您的帐号的身份验证方式,并且绝不能与不受信任的源分享或向后者显示。我们的服务器将拒绝未正确签署的 Google Maps APIs for Work 网络服务请求,因此,您的应用在启动前正确签署请求至关重要(注意,Google Maps Geocoding API v2 当前不需要签名)。请参阅我们的网址签名文档:

https://developers.google.com/maps/premium/previous-licenses/webservices/auth

跟踪应用消耗和 channel 参数

为何重要channel 参数是一个可选参数,利用此参数,您可以通过向自己的每一个应用分配不同的渠道来跟踪您的客户端 ID 下的消耗情况。不需要向您的客户端 ID 注册 channel 参数。将 channel 参数添加到您的 API 请求后,消耗数据将在实现的 1-2 天后开始出现在您的支持门户消耗报告中。您可以选择在何处实现您的渠道以及如何聚合您的消耗数据。请在启动前确定您的应用是否应集成 channel 参数以跟踪消耗情况:

https://developers.google.com/maps/premium/previous-licenses/clientside/quota#reporting

channel 参数必须使用下面的格式:

  • 必须是一个 ASCII 字母数字字符串。
  • 接受句点 (.)、下划线 (_) 和连字符 (-) 字符。
  • channel 参数不区分大小写;大写、大小写混合及小写的 channel 参数都将合并成它们对应的小写形式。例如,CUSTOMER 渠道的消耗数据将与 customer 渠道的消耗数据组合。

您最多可以为每个客户端 ID 实现 2,000 个不同的渠道。

要使用 channel 参数,请将此参数连同用于传递客户端 ID 的 client 参数一起包含在请求网址中。

请注意,channel 参数必须为按应用静态分配的值。此参数不得动态生成,也不得用于跟踪各个用户。

从您的 API 请求中移除过时参数(例如“&key=ABQIAAAA…”参数)

为何重要:为了正确加载 Google Maps JavaScript API,您必须包含您的客户端 ID。您还必须移除任何 key 参数。如果您的请求包含客户端 ID 和密钥,它将失败。

请参阅 Google Maps APIs for Work 指南,了解如何按 API 正确格式化 Google Maps APIs for Work 请求的完整信息:https://developers.google.com/maps/premium/previous-licenses/