概览
为提高身份验证安全性和可靠性，自 2025 年 5 月 26 日起，Maps Platform 客户端 ID 已废弃，并且自 2026 年 5 月 31 日起将无法再使用。
您必须使用 API 密钥凭据（而非客户端 ID）对 Google Maps API 服务流量进行身份验证。本指南介绍了如何从使用客户端 ID 迁移到使用 API 密钥。
请按以下步骤开始操作：
查看当前客户端 ID 用量
在开始迁移流程之前，请列出以下内容：
- 您使用客户端 ID 使用的 Google Maps Platform 服务。
- 您使用客户 ID 的应用、网站或系统。
Google 已于 2025 年 5 月向受影响的客户发送了关于客户 ID 弃用的通知电子邮件。您也可以在通知电子邮件中找到此信息。
在 Cloud 控制台中，您可以在 Google 地图“指标”页面上查看客户端 ID 使用情况的最新状态
如需查看 Maps Platform 服务列表：
- 在 Cloud 控制台中打开指标页面。
- 使用以下设置过滤您的使用情况：
- 凭据：仅选择“project_number:<numerical identifier>”。
- 设置以下过滤条件。
- 分组依据：API
对于应用、网站或系统的提示：
Cloud Console 不会显示您的应用、网站或系统的详细信息。不过，您可以找到一些有关客户端 ID 流量来源的提示。请按照以下步骤操作：
- 在 Cloud 控制台中打开指标页面。
- 从下拉菜单中选择一项 Maps Platform 服务。
- 使用以下设置过滤您的使用情况：
- 凭据：仅选择“project_number:<numerical identifier>”。
- 设置以下过滤条件。
- 分组依据：平台或网域
- 针对您需要检查流量的每项 Google 地图平台服务，从第 2 步重复上述操作。
准备 API 密钥
所有客户端 ID 都与 Google Cloud 项目相关联，使用该项目中的 API 密钥可让您访问之前使用客户端 ID 访问的相同功能。我们建议您迁移到关联的项目，以免出现配额问题或缺少功能。
- 查找与您的客户端 ID 关联的 Cloud 项目：
- 确保您的 Cloud 项目已关联到有效的结算账号。
- 创建新的 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 和 Street View Static API，您可以将客户端 ID 中的可信引荐来源迁移到 API 密钥限制。您可以在 Cloud 控制台中找到可信引荐来源列表。
查看配额设置
确保您的 Cloud 项目具有预期的配额设置。只有在您通过客户端 ID 调用 Maps JavaScript API 客户端服务时，才需要执行此操作。您可以在 Google 地图配额页面上查看和调整配额设置。
Maps JavaScript API 客户端服务的配额增加
如果您在 Maps JavaScript API 上使用以下服务，则会在 API 密钥迁移后看到配额用量增加。
查看您当前的配额配置、当前用量，并相应地调整配额限制。
- 检查您是否在使用带有客户端 ID 的 Maps JavaScript API 客户端服务。
- 在 Cloud 控制台中打开指标页面。
- 使用以下设置过滤您的使用情况：
- 分组依据：API 方法
- 凭据：仅选择“project_number:<numerical identifier>”。
- 然后，您会在“按 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。
移除了 Web 服务的签名参数
对于 Web 服务 API (*)，使用 API 密钥访问这些 API 时无需签名参数。请仅从 API 请求中移除签名参数。
- Directions API（旧版）
- Distance Matrix API（旧版）
- Geocoding API
- Elevation API
- Time Zone API
如需了解详情，请参阅高级计划概览。
Imagery API 的签名密钥
Maps Static API 和 Street View Static API 仍需要签名参数。它们会接受少量未签名的请求以进行测试，但一旦在生产环境中达到阈值，就会开始失败。将签名密钥从客户端 ID 的签名密钥替换为 API 密钥的签名密钥。您可以使用相同的签名算法，但需要使用其他签名密钥。如需了解详情，请参阅使用数字签名。
监控客户端 ID 流量
部署完成后，使用 Cloud 控制台信息中心确认流量是否已成功迁移。您会开始看到客户端 ID 流量有所减少。如果按凭据对信息中心进行分组，则客户端 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。查看“查看配额设置”部分，并相应地调整配额。
“对此 API 的请求必须通过 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"
}