从 v1beta 迁移到 v1

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

主要区别

从 v1beta 迁移到 v1 时，需要注意以下最重要的更改：

• 至少一位 API 开发者需进行一次性注册才能使用 Merchant API： 您需要调用 registerGcp 方法（对于用于身份验证的每个 Google Cloud 云项目，只需调用一次），以提供您的详细联系信息，这样您就可以使用 该 API 并接收与 Merchant API 相关的更新和通知。在完成此步骤之前，您将无法使用任何 v1 或 v1alpha API。如需详细了解注册流程，请参阅 注册。

• 商品名称编码： ProductInput.name 和 Product.name 字段支持无填充 base64url (RFC 4648 第 5 节) 编码。请遵循以下准则：

  • 在编码之前，字符串必须遵循 contentLanguage~feedLabel~offerId 格式。

  • 如果您的商品名称包含 Merchant API 使用的字符或网址保留字符（例如：），则必须 进行编码。

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

  • 如果您的商品名称遵循 contentLanguage~feedLabel~offerId 格式，并且 不 包含 Merchant API 使用的任何字符或 网址保留字符，则可以使用纯文本格式，无需编码。

  • 为确保解析的一致性和正确性，我们建议对所有商品名称使用无填充 base64url 编码。

• 移除商品级税务信息： taxes 和 taxCategory。

• Product.attributes 已重命名：Product.attributes 字段已重命名为 Product.productAttributes。

• 移除商品级税务信息： taxes 和 taxCategory 字段已从 Product.productAttributes 对象中移除。如需了解详情，请参阅 Google Merchant Center 帮助文章中的税费 。

• GTIN 字段的更改： gtin 字段在 Product.productAttributes 对象中已重命名为 gtins，以更好地反映它可以包含多个值。gtin 字段在 OrderTrackingSignals.lineItemDetails 对象中现在是一个 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）。

• 移除了在线退货政策更新方法： v1 中移除了 onlineReturnPolicy.update 方法。请改用 onlineReturnPolicy.create 方法创建在线退货政策。

如何迁移

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

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

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

字段更改详情

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

v1beta	v1	说明
ProductInput.name	ProductInput.name	Unpadded base64url encoding 支持，并且对于 包含 Merchant API 使用的字符或网址保留字符的商品名称，此编码是必需的。
Product.name	Product.name	Unpadded base64url encoding 支持，并且对于 包含 Merchant API 使用的字符或网址保留字符的商品名称，此编码是必需的。
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 字段向账号添加初始管理员。