新功能Product Score、4T Segmentation、Price War 和 Broken Size 现已上线。查看新功能
Feedance
文章

修复 Google Content API 410 错误:将 Feed 管道迁移到 Merchant API

Content API for Shopping 已开始返回 410 错误。找出剩余调用、映射到 Merchant API,并在 Merchant Center 中验证商品。

Cagdas PolatCagdas Polat
阅读时长 3 分钟
修复 Google Content API 410 错误:将 Feed 管道迁移到 Merchant API

Google 的 Content API for Shopping 已于 2026 年 8 月 18 日停用。自 9 月 1 日起,未获批延期的项目发出的请求会间歇性地以 HTTP 410 失败,这些端点将于 2027 年初完全关闭(Google 的停用通知)。如果某个脚本、插件或内部连接器仍在通过旧 API 将您的商品推送到 Merchant Center,其中部分更新已经在被丢弃。

本指南面向自行维护这条数据管道的开发者和 Feed 负责人。读完后,您将能够找出所有剩余的 Content API 调用,将每个调用映射到对应的 Merchant API 方法,创建新 API 所需的数据源,并在 Merchant Center 中确认商品和价格仍在正常写入。

如何判断您是否受到停用影响

这种失败很容易被忽视,因为它是间歇性的。Google 将错误响应体记载为 410,其消息以 “Content API for Shopping was sunset on August 18, 2026” 开头,并包含您的 Google Cloud 项目 ID、项目编号和一个帮助中心链接。请在集成日志中搜索该字符串以及 shoppingcontent.googleapis.com。

在有人查看日志之前,通常会先出现三种症状:

  • 价格或库存状态的变更延迟数小时才到达 Google,或者只在部分运行中到达。
  • 每日任务报告大部分批次成功,但有少数批次失败。
  • Merchant Center 显示的是过时数据,而您的店铺显示的是正确价格。

最后一种症状还有第二种可能的原因,即 Google 自身的自动商品更新覆盖了您的值。我们在 阻止 Google 悄悄覆盖您 Feed 中的价格和库存状态 一文中单独介绍了这一点。请先排除 410 错误,因为确认它们的成本更低。

第 1 步:清点旧 API 的所有调用方

Google 自己的建议是检查应用代码中对 Content API 端点的直接调用。实际上,这些调用藏在四个地方:店铺平台的 Google 插件、前任开发者编写的自定义脚本、Feed 或 ERP 中间件,以及某人多年前设置定时运行的 Google Ads 脚本或 Apps Script。

建立一份简短的登记表,每个调用方占一行。记录它的作用、它使用哪个 Google Cloud 项目进行认证,以及负责人是谁。项目 ID 很重要,因为延期和 410 消息都与它绑定。

调用方发送内容负责人行动
店铺插件完整商品目录,每天平台供应商询问其目前使用哪个 API 版本
库存脚本价格和库存,每小时您的开发者迁移到 Merchant API
Feed 管理工具优化后的 Feed工具供应商要求对方书面确认已完成迁移

如果连接由供应商管理,您要做的是询问,而不是重建。Productsup 和 Feedonomics 都已发布迁移说明,成熟的供应商应该早已完成迁移。向清单上的每个供应商提出同样的问题,并保留他们的答复。

第 2 步:决定是否需要延期

Google 为需要更多时间的组织提供了 Content API 延期申请表。获批的延期可在批准的时间窗口内保护项目免受计划中的错误响应影响,但不会延续到 2027 年初的最终下线之后。Google 并未说明哪些组织符合条件。

请使用以下决策规则。如果每个调用方都能在几周内完成迁移和测试,就跳过延期,把时间花在迁移上。如果某个调用方属于已确认迁移但尚未排期的供应商,则只为该项目申请延期。延期只是缓冲,而不是计划。

第 3 步:将每个调用映射到对应的 Merchant API 方法

Merchant API 将原来的单体 API 拆分为多个子 API,并在 URL 中标注版本(/products/v1/)。v1 版本于 2025 年 7 月正式发布,v1beta 已于 2026 年 2 月 28 日停用,因此请基于 v1 构建,忽略您找到的任何 v1beta 教程(Merchant API 版本说明)。

Content APIMerchant API变化
products.insertproductInputs.insert需要 dataSource 查询参数
products.updateproductInputs.patch对单个商品输入进行持久更新
products.deleteproductInputs.delete需要 dataSource 参数
products.get / listproducts.get / list返回处理后的商品,只读
productstatuses.get / listproducts.get / list状态现已成为 Product 资源的一部分
custombatch并行异步调用不存在 customBatch 方法
datafeedsdataSources每个数据源对应一个 Feed 标签和一种语言

来源:Google 的 商品迁移映射 和 数据源映射。概念上的转变在于区分 ProductInput 和 Product:前者是您写入的原始数据,后者是您只能读取的处理结果。处理后的商品由一个主输入加上任意补充输入,在 Feed 规则运行后构建而成(商品概览)。

第 4 步:在插入任何内容之前创建 API 数据源

这是导致大多数首次迁移失败的步骤。Content API 会在您首次插入时自动创建一个 “Content API” 数据源,而 Merchant API 不会。Google 指出,您必须创建至少一个 API 类型的数据源,而且 Products 子 API 只能写入该类型的数据源(数据源迁移)。

现在,每个数据源对应 feedLabel 和 contentLanguage 的单一组合。如果您之前通过一个多目标 Feed 同时以土耳其语服务土耳其、以英语服务阿联酋,那么现在需要分别创建数据源。通过 Data Sources 子 API 或在 Merchant Center 中创建它们,然后在每次写入时使用生成的资源名称,格式为 accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}。

第 5 步:重写请求负载(附实例)

三项字段变化导致了大部分错误。价格从十进制字符串改为整数 micros,一百万 micros 等于一个货币单位。商品属性移入 productAttributes 对象。targetCountry 被 feedLabel 取代,而 channel 则被取消。

旧的商品标识符如下所示,新标识符使用波浪号并去掉了 channel:

Content API:  online:en:US:SKU12345
Merchant API: en~US~SKU12345

Google 自己的指南中用作示例的商品输入如下(通过 POST https://merchantapi.googleapis.com/products/v1/accounts/{ACCOUNT_ID}/productInputs:insert?dataSource=accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID} 插入):

{
  "offerId": "SKU12345",
  "contentLanguage": "en",
  "feedLabel": "US",
  "productAttributes": {
    "title": "Classic Cotton T-Shirt",
    "link": "https://www.example.com/p/SKU12345",
    "imageLink": "https://www.example.com/img/SKU12345.jpg",
    "availability": "IN_STOCK",
    "price": { "amountMicros": "15990000", "currencyCode": "USD" },
    "condition": "NEW",
    "gtins": ["9780007350896"]
  }
}

与旧结构对比:"price": {"value": "15.99", "currency": "USD"} 变为 amountMicros 和 currencyCode,库存状态变为枚举值,因此 in stock 变为 IN_STOCK。来源:Google 的添加和管理商品指南。

以土耳其里拉为例,1,249.90 TRY 对应 "amountMicros": "1249900000"。请基于最小货币单位用整数运算计算 micros,而不是用浮点数相乘,否则您会发出 1249899999,然后困惑于价格为何差了一丝。

当多个任务写入同一商品时,还要使用新的 versionNumber 字段。它可以防止请求乱序到达时,较旧的更新覆盖较新的更新。

第 6 步:替换批处理,并从商品中读取状态

不存在 customBatch。请用并行异步请求替代它,限制并发数,然后只重试失败的请求。为每个报价保留结果日志,以免部分失败悄无声息地变成过时的商品目录。

对于状态,请停止调用 productstatuses,改为读取处理后的 Product,其中包含了状态。Google 指出,从插入或更新到最终商品可用之间可能会有几分钟的延迟,因此写入后立即读取并不能用来判断是否失败。

第 7 步:在关闭旧路径之前进行验证

先在一小部分低风险数据上运行新路径,例如一个 Feed 标签中的 50 件商品。然后使用以下清单评估切换情况。在停用旧调用方之前,每一项都应为 “是”。

  • 调用方使用您登记的项目进行认证,并且连续七天没有返回 410。
  • 您服务的每个 Feed 标签与语言组合都有对应的 API 数据源。
  • 对于测试数据,处理后的商品在价格、库存状态和链接上与您的权威数据源一致。
  • 没有其他程序仍在从旧数据源写入相同的报价 ID。
  • 失败的报价会被记录并重试,而不是被丢弃。
  • 登记表上所有由供应商管理的调用方都已提供书面迁移确认。

第四项值得特别关注。同一报价 ID 存在第二个写入方,例如旧调用方和新的 API 数据源,就会导致值相互冲突。请确定每件商品由哪个数据源负责,并移除另一个。

本指南的局限

本文基于 Google 公开发布的文档撰写,我们并未迁移过您的代码库。有几方面内容不在本文范围内。Google 没有说明延期的资格条件,因此我们无法告诉您某个项目是否会获批。商品概览除了 “几分钟” 之外没有记载具体的时间,因此任何更严格的延迟预期都需要您自己测量。本地库存、区域库存、促销和评价各自都有 Merchant API 子资源,本文并未涵盖它们的映射。

如果您根本不想自己负责 API 集成,那么托管式 Feed 平台是比重写更好的答案。Productsup 和 Feedonomics 都发布了 Merchant API 迁移指南,对于数据模型特殊的企业团队来说,二者可能都比我们的方案更合适。专门针对 Google Shopping,我们自己的方案介绍见 Google Merchant Center 集成页面。

常见问题

Content API for Shopping 还能用吗?

已无法可靠使用。Google 表示,它已于 2026 年 8 月 18 日停用;自 2026 年 9 月 1 日起,没有有效延期的请求开始间歇性地以 HTTP 410 失败;所有端点将于 2027 年初关闭。

Content API 410 错误显示什么内容?

消息以 “Content API for Shopping was sunset on August 18, 2026” 开头。响应中包含您的 GCP 项目 ID、项目编号和一个帮助中心链接,据此可以知道需要迁移或延期的是哪个项目。

我可以通过延期获得更多时间吗?

Google 提供了 Content API 延期申请表。获批的延期只在批准的时间窗口内保护您的项目免受计划中的错误影响,并且不会超过 2027 年初的下线时间。

为什么 productInputs.insert 要求提供 dataSource?

Merchant API 的写入操作必须归属于明确的数据源。与旧 API 不同,它不会在您首次插入时创建 “Content API” 数据源,因此您必须创建一个 API 类型的数据源并传入其资源名称。

如何在 Merchant API 中发送价格?

使用整数字符串形式的 amountMicros 和 ISO 4217 格式的 currencyCode。一百万 micros 等于一个货币单位,因此 15.99 USD 即为 15990000。

Merchant API 支持批处理吗?

不存在 customBatch 方法。Google 的建议是使用异步并行调用,这意味着您应自行添加并发限制和针对每个报价的重试机制。

productstatuses 去哪了?

状态现在是处理后的 Product 资源的一部分。使用 products.get 或 products.list 读取,并记住处理可能比插入滞后几分钟。

我应该基于哪个 Merchant API 版本构建?

基于 v1 构建,该版本于 2025 年 7 月正式发布。v1beta 版本已于 2026 年 2 月 28 日停用,因此针对它编写的教程将无法使用。

检查 Google 实际看到的内容

迁移完成后,最快的检查方法是将您的源 Feed 与 Merchant Center 处理后的结果进行比较。使用我们的 免费商品 Feed 审核工具 检测您的线上 Feed,获取完整度和质量评分,并在下一个广告周期之前修复它标记出的所有问题。

想请人帮您把把关?我们会与您一起审查 feed,并在下次提交前指出其中的缺口。
免费诊断
Cagdas Polat
作者
Cagdas Polat

Feedance 联合创始人,凭借计算机工程师与营销人的双重背景推动数据分析洞察。他专注于将数据转化为可落地的策略,致力于帮助品牌在数字化领域实现显著增长。

LinkedIn

看看哪些
商品真正带来收益。

连接您的 feed 和 GA4,我们会在您自己的商品目录上展示 Product Score、4T、Price War 和 Broken Size。