从 v1beta 迁移到 v1

本指南可帮助您从 Merchant API v1beta 迁移到 v1（第一个正式版）。v1 版本引入了多项更新和一些可能需要更新代码的变更。这些更改旨在简化 API 并改进 Merchant Center 账号的管理。

主要差异

从 v1beta 迁移到 v1 时，您需要了解以下最重要的变化：

• 至少注册一位 API 开发者以使用 Merchant API（一次性注册）：您需要调用 registerGcp 方法（每个用于身份验证的 Google Cloud 项目只需调用一次）来提供您的联系信息，以便您使用该 API 并接收与 Merchant API 相关的更新和公告。 在完成此步骤之前，您将无法使用任何 v1 或 v1alpha API。如需查看相关说明，请参阅注册为开发者
• Product.attributes 已重命名：Product.attributes 字段已重命名为 Product.productAttributes。
• 移除商品级税费信息：taxes 和 taxCategory 字段已从 Product.productAttributes 对象中移除。如需了解详情，请参阅关于税费的 Google Merchant Center 帮助文章
• GTIN 字段的更改：Product.productAttributes 对象中的 gtin 字段已重命名为 gtins，以更好地反映它可以包含多个值。OrderTrackingSignals.lineItemDetails 对象中的 gtin 字段现在是 array，并且已重命名为 gtins。
• 渠道字段移除：channel 字段已从商品、商品输入和数据源中移除。我们新增了一个布尔值字段 legacyLocal，用于明确指定仅在实体店销售的商品。注意：legacyLocal 字段是一个辅助字段，用于帮助迁移，一旦在线和本地营销方法能够完全以单一商品来源为目标，该字段最终将被弃用。如需了解详情，请查看下一部分中的表格。
• 区域和本地商品目录属性的新字段：
  • 除 name、account 和 region 以外的所有 RegionalInventory 字段现在都封装在一个名为 regionalInventoryAttributes 的新对象下。例如，RegionalInventory.price 属性现在位于 RegionalInventory.regionalInventoryAttributes.price 下。
  • 除 name、account 和 storeCode 以外的所有 LocalInventory 字段现在都封装在一个名为 localInventoryAttributes 的新对象下。例如，LocalInventory.price 属性现在位于 LocalInventory.localInventoryAttributes.price 下。
• 从区域和本地商品目录中移除 customAttributes：customAttributes 字段已从 RegionalInventory 和 LocalInventory 资源中移除。
• 改进了账号创建流程：从 CreateAndConfigureAccountRequest 中移除了多余的 users 字段。使用单数形式的 user 字段将初始用户与新账号相关联。
• 某些属性类型已从字符串更改为枚举：Product和 Inventory 资源中具有已定义值短列表的某些字段已从 string 类型更改为 enum 类型，以便更好地进行数据验证（例如，Product.ProductAttributes.condition 字段现在是 enum）。
• 移除在线退货政策更新方法：onlineReturnPolicy.update 方法已在 v1 中移除。请改用 onlineReturnPolicy.create 方法创建线上退货政策。

如何迁移

Merchant API 的 v1beta 版本计划于 2026 年 2 月 28 日停用。如需详细了解弃用时间表，请参阅商家 API 版本控制指南。

• 迁移的第一步是完成一次性开发者注册（请参阅注册成为开发者）。您必须针对用于身份验证的每个 Google Cloud 项目调用 registerGcp 方法，然后才能使用任何 v1 方法。

• 无论您是以 REST、gRPC 还是通过使用客户端库来调用 API，都可以分阶段进行迁移。这意味着您可以一次更新和迁移一个 API 的代码（例如，将 Products API 迁移到 v1，同时将 Accounts API 保留在 v1beta 上），而无需一次性更新整个集成。

详细的字段更改

下表详细比较了 v1beta 和 v1 版本之间发生变化的字段。

v1beta	v1	说明
Product.gtin	Product.gtins	GTIN 的字段已重命名。
Product.taxes	已移除	已移除 taxes 字段
Product.taxCategory	已移除	已移除 taxCategory 字段
Product.channel	已移除	已移除 channel 字段。对于本地用例，请使用 legacyLocal 字段。
Product.attributes	Product.productAttributes	attributes 字段已重命名为 productAttributes。
Product 字段中的 availability、condition、gender、includedDestinations 和 excludedDestinations 表示为 strings（或 strings 的 array）	这些字段现在是 enums（或 enums 的 array）	具有已定义短值列表的字段已从 string 类型更改为 enum。
RegionalInventory 中的 price、salePrice、salePriceEffectiveDate 和 availability	已移至“RegionalInventory.regionalInventoryAttributes”	这些字段已移至 regionalInventoryAttributes 下。
RegionalInventory.availability 字段为 string	RegionalInventory.regionalInventoryAttributes.availability现为enums	将“是否有空”的类型从 string 更改为 enum。
LocalInventory 中的 price、salePrice、salePriceEffectiveDate、availability、quantity、pickupMethod、pickupSla 和 instoreProductLocation	已移至“LocalInventory.localInventoryAttributes”	这些字段已移至 localInventoryAttributes 下。
LocalInventory.availability 字段为 string	LocalInventory.localInventoryAttributes.availability现为enums	将“是否有空”的类型从 string 更改为 enum。
LocalInventory.customAttributes	已移除	本地商品目录不再支持自定义属性。
RegionalInventory.customAttributes	已移除	区域广告资源不再支持自定义属性。
ProductInput.channel	已移除	已移除 channel 字段。对于本地用例，请使用 legacyLocal 字段。
DataSource.channel	已移除	已移除 channel 字段。对于本地用例，请使用 legacyLocal 字段。
不可用	ProductInput.legacyLocal	一个新布尔值字段，用于指明商品只能定位到本地营销方式。商品资源 ID 将带有“local~”前缀。
不可用	Product.legacyLocal	一个新布尔值字段，用于指明商品仅在本地实体店销售，无法在线购买。
不可用	DataSource.legacyLocal	一个新布尔值字段，用于指示数据源是否包含仅在本地商店销售的商品。
OrderTrackingSignals.LineItemDetails.gtin	OrderTrackingSignals.LineItemDetails.gtins	gtin 字段已重命名为 gtins，现在是字符串数组（而不是字符串）。
CreateAndConfigureAccountRequest.users	已移除	已移除 users 字段。使用 user 字段向账号添加初始管理员。