Google Merchant API 认证与 GCP 项目配置指南：IAM 发证、registerGcp 注册与零停机切换

Google Merchant API 认证与 GCP 项目配置指南：IAM 发证、registerGcp 注册与零停机切换

Google Merchant API 迁移系列导航

1. 系列一（架构与停用时间表）：《Google Merchant API 架构解析：取代 Content API for Shopping、2026 停用时间表与模块化升级指南》
2. 系列二（迁移排期与读写分离）：《Google Merchant API 迁移手册（Start Your Migration）：子 API 排期、ProductInput 读写分离与防 Offer Stealing 指南》
3. 系列三（本篇，认证与 GCP 架构）：《Google Merchant API 认证与 GCP 项目配置指南：IAM 发证、registerGcp 注册与零停机切换》
4. 系列四（高并发与配额治理）：《Google Merchant API 高并发代码重构：替代 custombatch、突破 gRPC 100 并发流限制与动态配额治理》

第一章：存量密钥复用与 GCP 新凭证配置流程

旧版 GMC 后台创建的 Service Account JSON 密钥仍然有效，可以直接复用。你只需在该密钥所属的 GCP 项目中补做两步：启用 Merchant API 服务，再执行一次 registerGcp 注册。

如果要为新独立站或新 ERP 服务创建认证凭证，请按 Google Cloud Console 的 4 个步骤操作：

第二章：developerRegistration:registerGcp 前置条件与排障

启用 API 并配置好 GMC 用户权限后，你需要使用该 GCP 项目的凭证发起一次开发者注册请求。你可以在下方的 GCP 认证架构与错误码排障模拟器中选择实际场景（单独立站直连、MCA 代理商多子账户、双 GCP 零停机切换、401 与 409 报错自检），生成对应的执行命令：

# Verify all GCP project numbers currently linked to your primary GMC:
GET https://merchantapi.googleapis.com/accounts/v1/accounts/4321009/developerRegistration
Authorization: Bearer {NEW_PROJECT_ACCESS_TOKEN}

# Expected Response (multiple simultaneous GCP projects supported):
{
  "name": "accounts/4321009/developerRegistration",
  "gcpIds": ["123456789012", "987654321098"]
}

2.1 调用 registerGcp 的 5 项前置条件

缺少以下任一条件，注册请求都会失败：

1. 使用正式生产 GMC 账号（Production Account Only）：旧版遗留的测试沙盒账号（Test Accounts）不支持调用 registerGcp。
2. 完成网站声明与验证（Verified & Claimed Website）：未绑定有效独立站域名的空壳 GMC 账号无法通过校验。关于第一方域名与代码信号配置，可参考 《Google 官方数据优势最佳实践（Data Strength）》。
3. 调用方在目标 GMC 具备 ADMIN 角色：Standard 权限用户调用 registerGcp 会触发 403 PERMISSION_DENIED。
4. developerEmail 填写真人或团队 Google 账号邮箱：请求体中的 {"developerEmail": "[email protected]"} 用于接收 API 破坏性变更、配额告警与合规通知。严禁填写以 .gserviceaccount.com 结尾的服务账号邮箱，否则接口直接返回 400 INVALID_ARGUMENT。
5. 预留 5 分钟生效延迟与 14 天邮件确认窗口：registerGcp 返回 200 OK 后，全球网关路由同步约需 5 分钟，建议脚本等待 5 分钟后再启动大规模商品同步。若填入的 developerEmail 尚非该 GMC 账号成员，系统会发送关联邀请邮件，收件人必须在 14 天内点击接受验证。

2.2 registerGcp 请求与响应示例

调用成功后，接口会返回 DeveloperRegistration 资源对象，其中包含已绑定的 gcpIds 项目编号列表。此后你可随时请求 GET https://merchantapi.googleapis.com/accounts/v1/accounts/123456789/developerRegistration 核验注册状态。

第三章：绑定配比规则：1 GMC : N GCP 与 1 GCP : 1 主 GMC

拥有多个品牌 GMC 的集团卖家，或管理上百个客户 GMC 的代投机构，在设计云架构时常遇到 409 ALREADY_EXISTS (DUPLICATE_PROJECT_REGISTRATION) 报错。设计前需明确以下两条绑定规则：

3.1 多子品牌集团与多租户 SaaS 的架构方案

管理数十个子品牌或服务上百个商家客户时，不要新建上百个 GCP 项目，也严禁对 MCA 子账户（Sub-account）调用 registerGcp。官方推荐以下两种多租户架构：

1. 多品牌集团、CSS 与代投机构（MCA 高级账户模式）：只需将 1 个核心 GCP 项目注册到集团顶层的 MCA（Multi-Client Account，多客户高级父账户）上。注册完成后，该 GCP 项目的凭证即可直接读写该 MCA 下的全部子账户（例如直接请求 accounts/{SUB_ACCOUNT_ID}/productInputs:insert），无需也不能对子账户单独执行 registerGcp。
2. 第三方电商 SaaS 插件与 ERP 服务商（OAuth 跨租户授权模式）：将 SaaS 官方 GCP 项目注册到你公司自己的主开发者 GMC 账号上，建立平台级开发者身份，并在合作伙伴属性中按实际角色声明为 Marketplace、Agency、CSS、Brand 或 POS 集成商。随后通过标准 OAuth 2.0 授权流，或让外部商家将你的服务账号加入其 GMC 用户列表，这 1 个已注册的 GCP 项目即可访问外部授权商家的 GMC 数据，无需调用外部商家账号的 registerGcp。

第四章：大型团队双 GCP 零停机切换与解绑方案

如果线上 Content API 仍运行在历史遗留的旧 GCP 项目中，你可以趁本次升级迁移到权限清晰的新 GCP 项目，同时保持线上广告与库存同步零中断。Google 官方文档《Manage and transition GCP projects》提供了两种迁移路径与两个排障接口。

4.1 两种 GCP 迁移方案选型

• 方案一：原地升级（Keep Existing GCP Project）。适合现有 GCP 项目归属清晰、IAM 权限受控的团队。直接在原项目开启 merchantapi.googleapis.com 并执行 registerGcp，新旧代码共用同一个 GCP 项目并行过渡，改动最小。
• 方案二：双 GCP 隔离切换（Dual-GCP Zero-Downtime Cutover）。适合大型卖家按模块灰度迁移，分为 4 步：
  1. 保留旧 GCP 项目不动，继续运行存量 Content API v2.1 任务

     若复杂场景需申请过渡支持，旧项目标识也保持不变。
  2. 新建生产级 GCP 项目，开启 Merchant API，配置最小权限服务账号，并将新 GCP 项目调用 registerGcp 注册到主 GMC 账号。
  3. 按模块灰度切流，依次将商品更新、库存同步和报表拉取切往新 GCP 项目。客户端埋点可同步参考 《Google Tag 与 GTM 架构重构指南》 与 追踪与归因专栏。
  4. 待旧 GCP 项目的 Content API 流量降为 0 后，停用旧密钥并下线旧项目。

4.2 绑定关系反查与安全解绑接口

联调遇到 409 DUPLICATE_PROJECT_REGISTRATION 却不确定当前 GCP 项目绑定了哪个 GMC 账号时，可使用以下两个接口处理：

• 反查绑定关系：请求 GET https://merchantapi.googleapis.com/accounts/v1/accounts:getAccountForGcpRegistration，无需传入 Account ID。网关会根据当前请求凭证所属的 GCP 项目，直接返回已绑定的主 GMC 账号资源名（如 accounts/99887766）。
• 安全解绑与 24 小时缓冲期（unregisterGcp）：若需将 GCP 项目从旧 GMC 主账号迁往新 GMC 主账号，先对旧账号调用 POST .../accounts/{OLD_ID}/developerRegistration:unregisterGcp。解绑后系统提供约 1 天（24 小时）的缓冲宽限期，防止在途请求突然报错，同时立即释放该 GCP 项目以绑定新主账号。