Maps JavaScript API:获取 API 密钥或客户端 ID

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

选择身份验证方法

如需使用 Maps JavaScript API,请执行以下操作:

  • 拥有高级计划许可的客户可以使用 API 密钥客户端 ID 对请求进行身份验证。
  • 拥有旧版许可的客户必须使用客户端 ID 对请求进行身份验证。

下面汇总了每种身份验证方法可用的工具和报告:

  • 使用 API 密钥进行身份验证(高级计划许可)
    通过使用 API 密钥来对请求进行身份验证,您可以:
    • 在 Google Cloud Console 的 API 页面上管理您的所有 API。
    • Cloud Console 中访问实时使用情况数据和 30 天的历史使用情况数据。
    • 向请求添加 channel 参数,以便查看更详细的使用情况报告。
    • Cloud Console 中查看使用情况报告(包含 30 天以上的数据)。
  • 使用客户端 ID 进行身份验证(高级计划许可或旧版许可)
    通过使用客户端 ID 来对请求进行身份验证,您可以:
    • 向请求添加 channel 参数,以便查看更详细的使用情况报告。
    • Cloud Console 中查看使用情况报告(包含 30 天以上的数据)。
    • 为 Maps JavaScript API 使用地图分析工具。

如需了解详情,请参阅面向高级计划客户提供的报告

使用 API 密钥进行身份验证

创建 API 密钥

API 密钥是唯一标识符,用于对与您的项目相关联的请求进行身份验证,以便您使用相关产品和执行结算。您必须至少有一个与您的项目相关联的 API 密钥。

如需创建 API 密钥,请执行以下操作:

  1. 在 Cloud Console 中,打开项目选择器页面,选择或创建要向其添加 API 密钥的 Google Cloud 项目。

    转到项目选择器页面

    注意:如需拥有对计划中的功能的完整访问权限,高级计划客户应使用与其高级计划帐号相关联的项目。购买许可时,您会收到如下格式的高级计划资产名称:gme-[company] > proj-[number] ([type])。为确保您访问的是正确的项目,请通过 console.cloud.google.com/project/number(将 number 替换为您的项目编号)以项目所有者身份登录控制台。您可以在欢迎邮件中找到项目所有者。

  2. 依次转到 Google Maps Platform > 凭据页面。

    转到“凭据”页面

  3. 凭据页面上,依次点击创建凭据 > API 密钥
    已创建的 API 密钥对话框会显示您新创建的 API 密钥。
  4. 点击关闭
    新的 API 密钥位于凭据页面的 API 密钥下。
    (请务必在实际使用之前限制 API 密钥。)

向您的应用添加 API 密钥

您必须在每个 Google Maps Platform 请求中都添加一个 API 密钥。在以下示例中,将 YOUR_API_KEY 替换为您的 API 密钥。

<script async defer src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap"
type="text/javascript"></script>

对于使用 API 密钥的请求,必须使用 HTTPS;对于使用客户端 ID 的请求,建议使用 HTTPS。对于在请求中包含用户位置等敏感用户数据的应用,也必须使用 HTTPS。

限制 API 密钥

通过限制 API 密钥,您可以确保只能使用您的 API 密钥发出已授权的请求,从而提高应用安全性。我们强烈建议您按照相关说明为您的 API 密钥设置限制。如需了解详情,请参阅 API 安全性最佳做法

如需限制 API 密钥,请执行以下操作:

  1. 依次转到 Google Maps Platform > 凭据页面。

    转到“凭据”页面

  2. 选择您要设置限制的 API 密钥。系统随即会显示 API 密钥属性页面。
  3. 密钥限制下,设置以下限制:
    • 应用限制:
      1. 若要接受来自您提供的一系列网站的请求,请从应用限制列表中选择 HTTP 引荐来源网址(网站)
      2. 指定一个或多个引荐来源网址网站。例如,指定 *.google.com 表示接受所有以 google.com 结尾的网站,例如 https://developers.google.com

        注意:若要将 file:// 引荐来源网址添加到密钥限制中,需要使用特殊的表示法。首先将“file://”部分替换为“__file_url__”,然后再将其添加到密钥限制中。例如,“file:///path/to/”的格式应为“__file_url__//path/to/*”。启用 file:// 引荐来源网址之后,建议您定期检查使用情况,以确保与您的预期相符。

    • API 限制:
      1. 点击限制密钥
      2. 选择 API 下拉列表中选择 Google Maps Platform。如果其中未列出 Google Maps Platform,您需要启用它。
      3. 如果您的项目使用 Places Library,请一并选择 Places API。同样,如果您的项目在 JavaScript API 中使用其他服务(路线服务距离矩阵服务海拔服务和/或地理编码服务),您还必须启用相应服务并在此列表中选择相应 API。
  4. 点击保存以完成更改。

使用客户端 ID 进行身份验证

购买 Google Maps Platform 高级计划许可后,您将收到 Google 发送的一封欢迎电子邮件,其中包含您的客户端 ID,您可以用来访问 Google Maps Platform 高级计划的各种报告和工具

所有客户端 ID 都以 gme- 为前缀。以下是典型客户端 ID 的格式。

gme-[company] > proj-[number] ([type])

您可以结合使用客户端 ID 与网址注册(而非 API 密钥),通过 Maps JavaScript API 对请求进行身份验证。

注意:此客户端 ID 不是密钥,并且只能由您授权的网址使用。详细了解如何注册授权网址

在加载 API 时指定客户端 ID

以下代码展示了如何在加载 Maps JavaScript API 时用您自己的客户端 ID 替换 YOUR_CLIENT_ID。

  <script async defer
  src="https://maps.googleapis.com/maps/api/js?client=YOUR_CLIENT_ID&v=quarterly&callback=initMap"></script>

您必须通过附加 v=quarterly 参数来指定发布版本(也称为功能稳定版本)或早期版本。使用实验性版本的应用不在 Google Maps Platform 高级计划服务等级协议 (SLA) 的涵盖范围内。

注意:如果您之前使用 API 密钥进行身份验证,现在要改用客户端 ID,则必须在加载 API 前移除 key 参数。如果同时包含客户端 ID 和 API 密钥,API 将无法加载

注册授权网址

为了防止第三方在他们自己的网站上使用您的客户端 ID,我们设置了限制,只有您专门授权的一系列网址才能使用您的客户端 ID。

如需查看您已授权的网址或授权更多网址,请执行以下操作:

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

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

以下注意事项适用于已获授权的网址:

域名或 IP 地址不必设置为可公开访问。
例如,http://myintranethttp://192.168.1.1 是有效条目。
指定网域的所有子网域也将获得授权。
例如,如果 http://example.com 获得授权,http://www.example.com 也会获得授权。反之则不成立:如果 http://www.example.com 获得授权,http://example.com 不一定会获得授权。
已获授权的路径的所有子路径也将获得授权。
例如,如果 http://example.com 获得授权,http://example.com/foo 也会获得授权。此外,由于指定网域的子网域也会获得授权,因此 http://sub.example.com/bar 也将获得授权。
路径区分大小写。
例如,http://www.example.com/ThisPath/http://www.example.com/thispath/ 不是同一个路径。
您可以将有效网址限制为使用特定端口的网址。
例如,如果指定 http://example.com:8080/foohttp://example.com 就不会获得授权。
HTTP 和 HTTPS 协议被视为不同的网址。
例如,如果 https://example.com 获得授权,http://example.com 不一定会获得授权。

上述所有规则将应用到每个授权,因此,您应仔细规划授权。例如,因为指定路径的所有子路径以及所有子网域都会获得授权,所以您最终可能会授权了一些原本不打算授权的页面。例如:

授权 http://example.com/ 也将授权 http://sub.example.com/path

如需了解详情,请参阅排查 Google Maps Platform 高级计划的网址授权问题