迁移产品

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 服务已被移除。商品验证问题和目标状态现在直接包含在 中 Product 资源中的 productStatus 字段，从而简化了数据检索。

• 可预测的商品更新：新的 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 调用中发送多个 请求。

• 适用于任何 Feed 标签和语言的数据源：Merchant API 允许您创建数据源，而无需指定 Feed 标签和语言，因此允许插入具有任何 Feed 标签和语言的商品。

请求

本部分比较了 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.update	行为有很大不同。它会更新特定的商品输入，并且是持久性的。
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。如果商品名称包含 Merchant API 使用的字符或网址保留字符，建议使用未填充的 base64url 编码 ，并且必须 使用此编码。
顶级商品数据规范属性（例如 title、price、link）	productAttributes 对象	title、price 和 link 等商品属性不再是顶级字段。它们现在分组在 productAttributes 对象内，在 Product 和 ProductInput 资源中。这提供了更清晰、更有条理的资源结构。
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 类型。