从 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 字段的更改：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 方法。

• 无论您如何调用 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。
price、salePrice、salePriceEffectiveDate、availability、quantity、pickupMethod、pickupSla和instoreProductLocation（在 LocalInventory 中）	已移至“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 字段向账号添加初始管理员。