Google Merchant API 迁移实战手册（Start Your Migration）：子 API 排期顺序、ProductInput 读写分离与防“Offer Stealing”指南

Google Merchant API 迁移实战手册（Start Your Migration）：子 API 排期顺序、ProductInput 读写分离与防“Offer Stealing”指南

系列文章导航

1. 系列一：《Google Merchant API 架构指南：替代 Content API for Shopping、2026 年停用时间表与模块化升级方案》
2. 系列二（本文）：《Google Merchant API 迁移实战手册（Start Your Migration）：子 API 排期顺序、ProductInput 读写分离与防“Offer Stealing”指南》
3. 系列三：《Google Merchant API 认证与 GCP 项目架构指南：取消 GMC 后台直接发证、registerGcp 开发者注册与零停机切换》
4. 系列四：《Google Merchant API 高并发代码重构实战：移除 custombatch、优化 gRPC 100 并发流上限与动态配额管理》

第一章：官方四步迁移路线与子 API 排期顺序

Merchant API 与 Content API v2.1 支持在同一个 GMC 生产账号下双轨并行（Hybrid Coexistence），因此无需停机一次性切换全部代码。团队可以保留存量旧接口运行，每次只上线验证一个子模块。

各子模块之间存在严格的上下游依赖关系，Google 官方推荐按以下顺序排期：

第二章：Products 模块重构：ProductInput 与 Product 读写分离

新版 Merchant API 采用命令查询职责分离（CQRS）设计，将商品拆分为两个独立资源。

2.1 写入端：accounts.productInputs（持久化原始输入）

• 接口职责：代表商家提交给指定数据源（Data Source）的原始商品数据。所有写入操作（insert、patch 和 delete）均针对 productInputs 执行。
• 持久化与版本控制：通过 productInputs 提交的商品数据采用持久化存储（Persistent），同时支持传入单调递增的 versionNumber 防止分布式乱序覆盖。若传入版本号低于服务端已存版本号，服务端会拒绝旧消息。
• 必填参数 ?dataSource=...：执行 insert、patch 或 delete 时，URL 查询字符串必须携带目标数据源完整路径，例如： POST https://merchantapi.googleapis.com/products/v1/accounts/123456/productInputs:insert?dataSource=accounts/123456/dataSources/987654
• 字段结构变化：标题、描述、链接、价格（amountMicros）、GTIN 和库存状态等标准商品字段，统一放入 productAttributes: { ... } 对象内

  自定义属性则放在顶层 customAttributes 数组中。
• 继承广告历史数据的条件：迁移时必须保持 offerId、contentLanguage 与 feedLabel 与旧版完全一致（区分大小写）。只要这组三元键不变，Shopping 与 PMax 系列积累的历史点击率和转化率即可延续，购物车毛利归因（CwCD）数据也不会中断。同时请用 Shopify GTM 与 Web Pixel 转化代码生成器核验前端像素，确保上报的商品 ID 与 Feed 一致。

2.2 读取端：accounts.products（只读合成视图与内嵌状态）

• 接口职责：纯只读接口（Read-Only，仅提供 get 与 list）。productInputs 写入后，Google 后台会异步合并主数据源、补充数据源（Supplemental Data Sources）与后台属性转换规则，耗时数秒至数分钟，最终生成供消费者和广告系统调用的 Product 实体。
• 原 productstatuses 接口的去向：旧版独立的 productstatuses 服务已移除，审批状态直接内嵌至 Product.productStatus 字段。现在调用一次 products.get 或 products.list（单页上限 pageSize=1000），即可同时读取合成后的商品属性与各渠道过审状态，并获取 itemLevelIssues 逐条拒登错误码（排查方法详见《Google Ads 产品状态诊断与跨系列重叠排查指南》）。
• 历史纯线下 Feed 标记 legacyLocal：若旧版账号中仍有遗留的 local:en:US:SKU1 纯线下数据源商品，合成后的 Product 资源会带有 legacyLocal: true 标记，资源名中也会包含 legacy_local 前缀。官方建议将其逐步迁移至统一的线上商品加 LocalInventory 架构。

第三章：DataSources 迁移重点：防范“Offer Stealing（商品抢占）”

3.1 “Offer Stealing（商品数据源抢占）”的触发机制

在旧版 Content API 中，调用 products.insert 无需指定 Feed ID，Google 会自动将商品写入默认的 Content API 主数据源。许多卖家账号中会同时存在两个数据源：

• 数据源 A：存量旧版默认 API 主数据源，运营已在后台为其配置了 20 条标题拼接与 Custom Label 分层规则。
• 数据源 B：开发测试 Merchant API 时新建的另一个 Primary API Data Source。

切换到新版 productInputs.insert?dataSource=数据源 B 时，如果未核实该 SKU 原先归属数据源 A，直接往数据源 B 写入相同的 en~US~offerId，数据源 B 就会将该商品的归属权从数据源 A 抢走（Steal）。一旦发生抢占，数据源 A 上配置的自定义标签、促销映射与属性加工规则都会对该 SKU 失效，直接打乱广告系列分流。

3.2 防抢占三步排查流程与三种数据源选型

1. 第 1 步：只读盘点存量数据源 调用 GET https://merchantapi.googleapis.com/datasources/v1/accounts/{ACCOUNT_ID}/dataSources，列出账号下全部 Primary 与 Supplemental 数据源。旧版 Content API 创建的默认 API Feed，在新版 dataSources.list 中已自动转为标准 API Primary DataSource，无需重复新建。
2. 第 2 步：在本地 ERP 或 PIM 数据库回填 dataSource 字段 调用 products.list 遍历存量商品，读取每件商品返回的 dataSource 属性，将 offerId 与原属 dataSource 资源名的映射关系写入本地商品表。后续日常更新时，严格按原属 dataSource 执行 productInputs:patch。
3. 第 3 步：新业务按规模选择 DataSource 结构
   • 单主数据源（Single Primary Data Source）：适合单站点、全量商品共用同一语言和国家标签的独立站，维护成本低。
   • 多主数据源（Multiple Primary Data Sources）：适合美、欧、英、日多站点独立运营的品牌，每个市场单独配置对应的 contentLanguage 与 feedLabel 主数据源。
   • 主数据源加 API 补充数据源（Primary + Supplemental API Data Source）：适合使用 Shopify 官方应用同步商品的卖家。保持主数据源由 Shopify 应用托管不动，另建一个补充数据源（Supplemental Data Source），用自研 Merchant API 脚本按 offerId 挂载实时毛利标签（customLabel0～customLabel4）或促销标签，避免干扰 Shopify 原生同步。
   • 人工规则迁移提示：若确定废弃旧数据源并迁往新数据源，需注意 GMC 后台界面配置的 Attribute Rules（属性转换规则）不支持通过 API 自动复制。切流前请由运营在 GMC 后台手动为新数据源补齐规则。

第四章：Reports 报表与 MCQL 语法变更：去掉前缀并统一 snake_case

如果 BI 团队通过旧版 reports.search 抽取商品曝光、点击与价格基准数据，迁移到 POST https://merchantapi.googleapis.com/reports/v1/accounts/{ACCOUNT_ID}/reports:search 时，需修改以下三处 MCQL 语法：

新旧 MCQL 查询代码对照