本指南可帮助您从 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 字段向账号添加初始管理员。 |