迁移产品

Merchant API 引入了一种更强大、更直观的商品数据管理方式。主要变化是将商品数据分为两个不同的资源：ProductInput 用于提交数据，Product 用于查看最终处理的版本，包括商品状态和问题。这种新结构可提供更可预测、更透明的体验。

本指南将介绍主要区别，帮助您将集成从 Content API for Shopping 进行迁移。如需查看有关使用新功能的详细指南，请参阅管理商品。

主要区别

与 Content API for Shopping 相比，Merchant API 在商品管理方面做出了以下重大变更：

• 用于输入数据和处理后数据的专用资源：Merchant API 将商品管理分为两个资源。您可以使用 ProductInput 资源来插入、更新和删除商品数据。您可以使用只读的 Product 资源来查看 Google 处理您的输入、应用规则并合并来自补充来源的数据后生成的最终商品。

• 产品名称的编码：您可以对 ProductInput.name 和 Product.name 字段使用未填充的 base64url (RFC 4648 第 5 节) 编码。如果商品名称包含 Merchant API 使用的字符或网址预留字符，则必须进行编码。例如，如果商品名称包含以下任何字符，您必须对其进行编码：

  % . + / : ~ , ( * ! ) & ? = @ # $
  

• 集成产品状态：productstatuses 服务已移除。 商品验证问题和目标平台状态现已直接包含在 productStatus 字段内的 Product 资源中，从而简化了数据检索。

• 可预测的产品更新：新的 productInputs.patch 方法可直接修改特定产品输入。与 Content API for Shopping 相比，这是一个重大改进，因为在 Content API for Shopping 中，更新可能会被其他 Feed 上传意外覆盖。在 Merchant API 中，更新会一直保留，直到相应商品输入再次更新或被删除。 商品更新应用于 ProductInput 资源，而不是已处理的 Product 资源。

• 选择数据源，以便更清晰地管理数据：所有 productInputs写入操作现在都需要 dataSource 查询参数，以便明确您要修改的数据源。如果您有多个数据源，此功能尤其有用。

• 新的资源标识符：现在，产品通过 RESTful 资源 name 而不是 id 字段来标识。格式为 accounts/{account}/products/{product}。

• 无自定义批次：custombatch 方法已不再可用。您可以使用异步请求或 HTTP 批处理在一次 HTTP 调用中发送多个请求。

迁移期间的数据源准则

在迁移数据源之前，我们强烈建议您选择数据源策略。

为确保顺利迁移并防止出现优惠窃取等问题，请遵循以下建议：

• 回填数据库：我们强烈建议您对本地数据库执行一次性回填，而不是在每次商品操作之前调用 dataSources.list。向每个商品记录添加 dataSource 名称字段，以便您直接在请求中提供正确的标识符。

• 整合并使用任何标签和语言的数据源：Merchant API 可让您创建数据源，而无需指定标签和语言，因此允许插入具有任何数据源标签和语言的商品。考虑使用单个数据源来处理任何标签和语言。

• 保护您的商品：如果您使用数据源规则，请在更新或删除商品之前调用 products.get 来查找与商品关联的确切 dataSource。这样可确保您修改的是预期来源，并防止意外窃取优惠。

请求

本部分比较了 Content API for Shopping 和 Merchant API 的请求格式。

请求说明	Content API for Shopping	Merchant API
获取商品	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
列出商品	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
插入产品	POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products	POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
更新商品	PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
删除商品	DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}	DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
获取商品状态	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId}	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
列出商品状态	GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses	GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
批量处理多个请求	POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch	使用异步请求或 HTTP 批处理

标识符

Merchant API 中的商品标识符格式已更改为标准 REST 资源名称。

标识符说明	Content API for Shopping	Merchant API
产品 ID	一个由英文冒号 (:) 分隔的多个段组成的字符串。 格式：channel:contentLanguage:targetCountry:offerId 或 channel:contentLanguage:feedLabel:offerId。 示例：online:en:US:sku123	REST 资源 name 字符串。 格式：accounts/{account}/products/{product}，其中 {product} 是 contentLanguage~feedLabel~offerId。 示例：accounts/12345/products/en~US~sku123。 编码：建议使用无填充的 base64url 编码，如果商品 ID 包含 Merchant API 使用的字符或网址预留字符，则必须使用此编码。

方法

下表显示了 Content API for Shopping 方法及其在 Merchant API 中的等效方法。

Content API for Shopping 方法	Merchant API 方法	适用范围和备注
products.get	products.get	检索最终的已处理商品。
products.list	products.list	列出最终的已处理商品。
products.insert	productInputs.insert	插入商品输入。需要 dataSource。
products.update	productInputs.patch	行为有显著不同。它会更新特定商品输入，并且是持久性的。
products.delete	productInputs.delete	删除特定商品输入。需要 dataSource。
products.custombatch	不可用	使用异步请求或 HTTP 批处理。
productstatuses.get	products.get	productstatuses 服务已被移除。状态信息现在是 Product 资源的一部分。
productstatuses.list	products.list	productstatuses 服务已被移除。状态信息现在是 Product 资源的一部分。
productstatuses.custombatch	不可用	使用异步请求或 HTTP 批处理。

详细的字段更改

下表重点列出了 Merchant API 中已更改、添加或移除的重要字段。

Content API for Shopping	Merchant API	说明
id	name	产品的首要标识符现在是 REST 资源 name。建议使用无填充的 base64url 编码，如果商品名称包含 Merchant API 使用的字符或网址预留字符，则必须使用无填充的 base64url 编码。
顶级商品数据规范属性（例如 title、price、link）	productAttributes 对象	title、price 和 link 等商品属性不再是顶级字段。现在，它们在 Product 和 ProductInput 资源中都归类于 productAttributes 对象内。这样可以提供更清晰、更有条理的资源结构。
targetCountry	feedLabel	资源名称现在使用 feedLabel 而不是 targetCountry，以与 Merchant Center 功能保持一致。
feedId	dataSource（查询参数）	现在，dataSource 名称是所有 productInputs 写入方法（insert、update、delete）必需的查询参数。
channel	不可用。请为仅限本地的商品使用 legacy_local。	Merchant API 中不再提供 channel 字段。在 Content API for Shopping 中，具有 LOCAL 渠道的商品应改为将 legacy_local 字段设置为 true。
不可用	versionNumber	ProductInput 上新增了一个可选字段，可用于防止将数据无序插入到主要数据源中。
具有已定义值集的 string 类型字段	具有已定义值集的 enum 类型字段	具有已定义值集的商品属性（例如 excluded_destinations、availability）中的字段现在为 enum 类型。