迁移产品

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 调用中发送多个请求。

提示 ：使用通道池提高吞吐量：配置通道池，以最大限度地提高批量操作的吞吐量。这通过管理多个底层连接，绕过了单个 gRPC 通道通常具有的 100 个数据流的限制。如需了解详情，请参阅重构代码以处理并发请求：使用通道池提高吞吐量

迁移期间的数据源准则

关键术语： 当通过唯一键（language、feedlabel、offerID）标识的商品到与其所属的主要数据源不同的主要数据源时，就会发生“商品信息窃取”。这实际上会从旧数据源中删除商品，并将其移至新数据源，其中可能适用不同的数据源规则和所有权设置。虽然可以有意使用窃取来重新整理商品，但如果在插入期间提供了不正确的 dataSource，则可能会发生意外窃取。

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

为确保顺利迁移并防止出现商品信息被盗等问题，请遵循以下建议：

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

• 整合并使用适用于任何标签和语言的数据源： 借助 Merchant API，您可以创建数据源，而无需指定标签和语言，因此可以插入具有任何数据源标签和语言的商品。考虑为所有标签和语言使用单一数据源。

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

注意： 调用 Merchant API 时，请务必为同一商品使用与 Content API for Shopping 相同的 offerId，以免丢失商品历史记录。另请参阅本页中的标识符部分。

请求

本部分比较了 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。 编码：如果商品 ID 包含 Merchant API 使用的字符或网址保留字符，则建议使用无填充的 base64url 编码，并且必须使用该编码。

注意： Merchant API 中不再提供 channel 字段。对于 Content API for Shopping 中具有 LOCAL 渠道的商品，应改为将 legacy_local 字段设置为 true。

方法

下表显示了 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。如果商品名称包含 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 类型。