客户端 ID 迁移指南

概览

请按以下步骤开始操作：

  1. 查看当前客户端 ID 使用情况
  2. 准备 API 密钥
  3. 查看配额设置
  4. 更新代码
  5. 监控客户端 ID 流量
  6. 暂停客户端 ID
  7. 客户端 ID 自助临时重新启用

检查当前客户端 ID 用量

在开始迁移流程之前，请列出以下信息：

  • 您正在使用客户端 ID 的 Maps Platform 服务。
  • 您使用客户端 ID 的应用、网站或系统。

Google 已于 2025 年 5 月向受影响的客户发送电子邮件，通知他们客户端 ID 将被弃用。您还可以在通知电子邮件中找到此信息。

在 Cloud 控制台中，您可以在 Google 地图指标页面上查看客户端 ID 用量的最新状态

如需查看 Maps Platform 服务的列表：

  1. 在 Cloud 控制台中打开指标页面。
  2. 使用以下设置过滤用量：
    • 凭据：仅选择“project_number:<数值标识符>”。
  3. 设置以下过滤条件。
    • 分组依据：API

对于应用、网站或系统的提示：

Cloud 控制台不会显示应用、网站或系统的详细信息。不过，您可以找到一些有关客户端 ID 流量来源的提示。请按照以下步骤操作：

  1. 在 Cloud 控制台中打开指标页面。
  2. 从下拉菜单中选择一项 Maps Platform 服务。
  3. 使用以下设置过滤用量：
    • 凭据：仅选择“project_number:<数值标识符>”。
  4. 设置以下过滤条件。
    • 分组依据：平台或网域
  5. 针对需要检查流量的每项 Maps Platform 服务，从第 2 步开始重复执行。

准备 API 密钥

所有客户端 ID 都与 Google Cloud 项目相关联，使用该项目的 API 密钥可让您访问之前使用客户端 ID 访问的相同功能。我们建议您迁移到关联的项目，以免出现配额问题或缺少功能。

  1. 查找与您的客户端 ID 相关联的 Cloud 项目：
  2. 确保您的 Cloud 项目已关联有效的结算账号。
  3. 创建新的 API 密钥，用于客户端 ID 迁移。
    • 您可以重复使用 Cloud 项目中的任何现有 API 密钥。
    • 您可以使用同一 Cloud 项目中的多个 API 密钥，例如，为了区分每个 Maps Platform 服务的流量，或者区分来自不同平台（浏览器、移动应用等）的流量。如需了解有关 API 密钥管理的最佳实践，请参阅安全指南。

保护 API 密钥的安全

请务必保护您的 API 密钥，以防密钥遭到未经授权的访问。

  • 为 API 密钥设置应用限制（例如网站、IP 地址、Android 应用或 iOS 应用）。
  • 为 API 密钥设置 API 限制。

如需了解详情，请参阅 Google Maps Platform 安全指南。

对于 Maps JavaScript API、Maps Static API 和街景静态 API，您可以将客户端 ID 中的可信引荐来源网址迁移到 API 密钥限制中。您可以在 Cloud 控制台中找到可信引荐来源网址的列表。

查看配额设置

确保您的云项目具有预期的配额设置。只有在通过客户端 ID 从客户端调用 Maps JavaScript API 服务时，您才需要执行此操作。您可以在 Google 地图配额页面上查看和调整配额设置。

详细了解配额报告

提高 Maps JavaScript API 客户端服务的配额

如果您在 Maps JavaScript API 中使用以下服务，则在 API 密钥迁移后，您会发现配额用量有所增加。

查看您当前的配额配置和当前用量，并相应地调整配额限制。

  1. 检查您是否正在使用客户端 ID 调用 Maps JavaScript API 客户端服务。
    • 在 Cloud 控制台中打开指标页面。
    • 使用以下设置过滤用量：
      • 分组依据：API 方法
      • 凭据：仅选择“project_number:<数值标识符>”。
    • 然后，您会在“按 API 方法划分的流量”图表中看到方法名称及其流量的列表。

API 方法

客户端服务

要调整配额的服务

google.routes.Directions.Javascript

路线服务

Directions API

google.routes.DistanceMatrix.Javascript

距离矩阵服务

Distance Matrix API

google.maps.Elevation.Javascript

海拔服务

Elevation API

google.places.Geocoding.Javascript

地理编码服务

Geocoding API

google.places.*.Javascript，但 google.places.Geocoding.Javascript 除外

地点库

Places API
  • 如果您不使用这些 API 方法，则无需担心配额设置，因为您的客户端 ID 流量已消耗项目配额。
  • 估算客户端 ID 配额用量
    • 对于每项服务，请同时检查“每秒”和“每天”粒度。
    • “每秒”图表：将峰值流量乘以 60，即可得出每分钟所需的额外配额。
    • 每日图表：流量峰值应为每日所需的额外配额。
  • 调整相应 Maps Platform 服务的配额
    • 根据您在第 1 步中找到的方法名称，调整相应服务的配额。

更新代码

将客户端参数替换为密钥参数

将出站 GMP API 调用中的身份验证凭据从 URL&client={value} 更新为 URL&key={value}。如果您的应用使用 HTTP 访问 GMP 服务，请将其更新为使用 HTTPS。

更新了报告的渠道参数

您可以通过在 API 请求中指定渠道参数来跟踪每个渠道的用量。API 密钥仅支持渠道参数的数值。如果您在渠道参数中使用包含任何非数值的客户端 ID，请将其更新为支持的数值。

如需了解详情，请参阅 Google Maps Platform 报告。

移除 Web 服务的签名形参

对于以下 Web 服务 API，当您使用 API 密钥访问它们时，不需要签名参数。只需从 API 请求中移除签名参数即可。

  • Directions API（旧版）
  • Distance Matrix API（旧版）
  • Geocoding API
  • Elevation API
  • Time Zone API

如需了解详情，请参阅高级计划概览。

Imagery API 的签名密钥

Maps Static API 和街景 Static API 仍需要签名参数。它们接受少量不带签名的请求以供测试，但一旦在生产环境中达到阈值，就会开始失败。请将客户端 ID 的签名密钥替换为 API 密钥的签名密钥。您可以使用相同的签名算法，但需要使用另一个签名密钥。如需了解详情，请参阅使用数字签名。

监控客户端 ID 流量

部署完成后，请使用 Cloud 控制台信息中心确认流量已成功迁移。您会开始看到客户端 ID 流量减少，在按凭据分组时，该流量在信息中心内以“project_number:123456”格式显示。

暂停客户端 ID

我们强烈建议开发者在迁移后暂停客户端 ID。这样做是为了保护您的凭据免受任何意外流量的影响，并确认客户端 ID 的任何剩余使用情况都不重要（例如测试、缓存、机器人程序等），并且可以返回错误而不会造成业务影响。您可以在 Cloud 控制台中暂停客户端 ID。如需了解详情，请参阅高级计划身份验证概览。

客户端 ID 自助服务临时重新启用

由于 Google Maps Platform 客户端 ID 已于 2026 年 5 月进入分阶段弃用期，因此无法再保证服务可用性。作为预定服务终止流程的一部分，系统会定期限制访问权限。虽然服务通常会在几个小时内自动恢复，但如果需要立即恢复，您可以选择手动重新启用访问权限。

如需紧急恢复访问权限，您可以通过 Google Cloud 控制台自行重新启用账号：

如果您无法快速迁移到 API 密钥，并且希望暂时免受进一步中断的影响，请与 Google Maps Platform 支持团队联系，并提供以下详细信息：

  • 客户 ID
  • 具体使用场景
  • 目标迁移日期
  • 业务影响评估

客户端 ID 用量报告 - 来自结算报告

对于无法访问项目指标的用户（例如结算管理员，尤其是 Maps 平台合作伙伴），查看结算报告而不是项目指标会很有用。虽然结算报告存在 1-2 天的延迟，但其优势在于可以显示超过 30 天的用量和费用数据分析。

您可以通过 Google Cloud 控制台监控客户端 ID 用量，只需按照以下步骤操作即可：

  1. 前往 Google Cloud 控制台中的结算 > 报告页面。
  2. （可选，仅适用于合作伙伴）应用过滤条件以选择所需子结算账号。
  3. 按标签键 goog-maps-api-key-suffix 对报告数据进行分组。此标签显示 API 密钥的尾部字符。
  4. 通过查找缺少或为空的 goog-maps-api-key-suffix 标签来识别客户端 ID 流量，因为客户端 ID 请求不会填充此标签。
  5. 忽略不应与 API 请求关联的 SKU，例如订阅 SKU。

问题排查

如何查看我们的请求是否失败？

您可以在响应代码图表中查看错误统计信息

ApiNotActivatedMapError或REQUEST_DENIED错误

如果您未在 Cloud 项目中启用该服务，则会看到 ApiNotActivatedMapError 或 REQUEST_DENIED 错误。请按照说明启用该服务。

RefererNotAllowedMapError 个错误

如果您的来源网域未添加到 API 密钥中，您将看到 RefererNotAllowedMapError 错误。请查看“保护您的 API 密钥”部分，并将您的网域添加到 API 密钥中。

OverQuotaMapError或OVER_QUERY_LIMIT错误

如果配置的配额不足以覆盖流量，您会看到 OverQuotaMapError 或 OVER_QUERY_LIMIT。请查看“检查配额设置”部分，并相应地调整配额。

“Requests to this API must be over SSL”错误

如果您收到以下错误消息，请将 API 请求从“http://”更新为“https://”。

{
  "error_message" : "Requests to this API must be over SSL. Load the API with
  \"https://\" instead of \"http://\".",

  "results" : [],

  "status" : "REQUEST_DENIED"
}