客户端 ID 迁移指南

概览

为了提高身份验证的安全性和可靠性，Maps Platform 客户端 ID 自 2025 年 5 月 26 日起弃用，2026 年 5 月 31 日之后无法再使用。

您必须使用 API 密钥凭据，而不是客户端 ID，来对 Google 地图 API 服务流量进行身份验证。本指南将向您介绍如何从使用客户端 ID 迁移到使用 API 密钥。

请按以下步骤开始操作：

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

检查当前客户端 ID 的使用情况

在开始迁移过程之前，请列出以下内容：

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

Google 于 2025 年 5 月向受影响的客户发送了有关客户端 ID 弃用的通知电子邮件。您也可以在通知电子邮件中找到此信息。

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

如需查看 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 密钥。
   • 您可以从同一云项目中使用多个 API 密钥，例如，为了将每项地图 Platform 服务的网络流量分开，或者将来自不同平台（浏览器、移动应用等）的网络流量分开。如需了解有关 API 密钥管理的最佳实践，请参阅 安全指南 。

保护 API 密钥的安全

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

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

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

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

查看配额设置

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

详细了解配额报告

增加 Maps JavaScript API 客户端服务的配额

警告 ：在 Maps JavaScript API 客户端服务上使用客户端 ID 不会消耗项目配额。迁移到 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 报告 。

移除网络服务的签名参数

对于以下网络服务 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。如需了解详情，请参阅专业版方案身份验证概览 。

问题排查

如何查看请求是否失败？

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

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"
}