2019 年 3 月,我们发布了 Content API for Shopping 的 2.1 版本;2021 年 4 月,我们宣布将于 2021 年 9 月 30 日停用 v2。版本 v2 已停用。请立即迁移到 v2.1。
迁移应用
从 v2 迁移到 v2.1 涉及更新端点网址以调用新的 v2.1 版本,并修改应用以应对 v2.1 中引入的重大更改。
更新您的 API 调用以使用 v2.1 端点
如需调用 v2.1,请更新您的请求以使用新的 v2.1 端点。
例如,如需使用 v2 调用 products.get
方法,您应使用以下代码:
GET https://shoppingcontent.googleapis.com/content/v2/merchantId/products/productId
对于 v2.1,请将网址更新为:
GET https://shoppingcontent.googleapis.com/content/v2.1/merchantId/products/productId
如需了解 v2.1 服务和端点的完整信息,请参阅 API 参考文档。
进行所需的更改
除了更新 API 调用的网址之外,您还需要更新应用以适应 v2.1 中引入的几项重大变更。请查看以下部分,并根据需要更新您的应用。
1. 更新与 inventory
服务的集成
v2 inventory
服务已移除,以下 v2.1 功能提供了等效功能:
使用新的补充 Feed 或
products.update
进行部分商品更新。可以更新所有可变商品字段,包括之前使用inventory.set
更新的所有字段(不包括localinventory
专有的字段)。如需了解详情,请参阅迁移到补充 Feed。使用新的
localinventory
服务获取本地商品更新。
2. 更新对 accounts
服务的调用
v2.1 中调用
accounts.update
方法会完全覆盖accounts
资源,而不是仅更新请求中包含的字段。为避免删除accounts
资源上的字段,请更新您的调用请求以包含所有字段。reviewsUrl
已移除。移除了
adsLinks
、googleMyBusinessLink
和youtubeChannelLinks
的关联状态inactive
。
3. 更新对 products
服务的调用
自定义属性不再包含类型和单位。相反,系统应该会自动检测要附加到值中的单位和类型。
重复字段
productTypes
已替换productType
和additionalProductTypes
。重复字段
includedDestinations
和excludedDestinations
已替换重复字段destinations
。以下与 AdWords 相关的字段已重命名:
adwordsGrouping
->adsGrouping
adwordsLabels
->adsLabels
adwordsRedirect
->adsRedirect
已移除以下字段:
aspects
destinations
onlineOnly
validatedDestinations
warnings
移除了
includeInvalidInsertedItems
参数。在 v2.1 中,默认情况下会返回所有产品。现在,插入的商品需要等待几分钟才能通过
products.get
或products.list
检索。返回的
offerId
不再保证与输入offerId
相同。v2.1 会修剪offerId
中的前导空格和尾随空格,并将多个空白字符合并为一个。此更改不会影响符合建议的offerId
语法的offerId
值。现在,价格会在插入商品之前进行验证。值字符串中仅允许使用以下字符:
+
、-
、.
和数字(即0
-9
)。不再支持使用逗号。products.insert
或products.update
调用的响应仅包含以下属性:channel
contentLanguage
id
offerId
feedLabel
v2 选项
includeAttributes
已弃用。请改为结合使用products.get
和ProductId
来查看完整的商品信息。
4. 更新对 productstatuses
服务的调用
已移除
product
属性以及includeAttributes
参数。如需检索与状态对应的商品属性,请使用products
服务并传递新的productId
字段的值。移除了
includeInvalidInsertedItems
参数。无论商品是否有效,现在都会返回每件商品的productId
。destinationStatuses
中的intention
、approvalStatus
和approvalPending
字段已替换为status
,后者是一个字符串,可以是approved
、disapproved
或pending
之一。dataQualityIssues
已替换为itemLevelIssues
。
5. 更新对 datafeeds
服务的调用
替换了以下目标字段:
contentLanguage
->language
targetCountry
->country
intendedDestinations
->includedDestinations
和excludedDestinations
包含“
contentType = "product inventory update"
”的数据 Feed 已被移除。
6. 更新对 orders
和 TestOrders
服务的调用
在 v2.1 中,调用不应包含税费数据,因为税费数据是自动计算的。如果订单是在具有市场公平性法案 (MFA) 或类似措施的州履行的,则包含税费数据的调用会失败。如果订单是在非 MFA 状态下履行的,则系统会根据 Merchant Center 中配置的设置计算税费。如果未配置,计算出的税费为 0。
InStoreRefundLineItem
和ReturnRefundLineItem
字段amountPretax
和amountTax
已分别替换为priceAmount
和taxAmount
。priceAmount
可以是税前或税后值,具体取决于订单的地理位置。请求中的
ShipLineItem
字段carrier
、shipmentId
和trackingId
已移至shipmentInfos
。billingAddress
和predefinedBillingAddress
现在分别是orders
和TestOrder
中的顶级字段。customer.explicitMarketingPreference
已替换为customer.marketingRightsInfo
。netAmount
字段已拆分为netPriceAmount
和netTaxAmount
。shippingOption
已替换为lineItems[].shippingDetails
。请求中的
CancelLineItem
字段amount
、amountPretax
和amountTax
已被移除。系统现在会自动计算退款金额。已移除
CustomBatch
。移除了
Refund
。请改用refundOrder
或refundItem
。paymentMethod
字段已移除。v2 方法
orders.returnlineitem
和orders.refund
已替换为orderreturns.creatOrderReturn
和orderreturns.process
。移除了
customer.email
、channelType
和lineItem.product.channel
字段。promotions
字段已从TestOrder
服务中移除,其格式在Order
中已更改。
7. 更新对 orderinvoice
服务的调用
amountPretax
和amountTax
字段已分别替换为priceAmount
和taxAmount
。priceAmount
字段可以是税前或税后字段,具体取决于订单的地理位置。已从
invoiceSummary
与促销扣款相关字段中移除了余额(商家、客户、Google)。
8. 移除了 v2.1 中未包含的功能
我们还从 Content API 2.1 版中移除了另外一些功能。请查看以下列表,并根据需要更新您的应用:
XML 已不再受支持。如需详细了解如何切换到 JSON,请参阅 Content API for Shopping 不再支持 XML。
移除了
dryRun
参数。此更改适用于所有 API 调用。已移除所有
HTTP BATCH
方法。请改用customBatch
。patch
方法已从以下服务中移除:accounts
accounttax
datafeeds
liasettings
shippingsettings
orderpayments
服务已被移除。
测试迁移
如需详细了解如何在迁移到 2.1 版后测试应用更改,请参阅测试 Content API for Shopping 的使用情况。如果您在测试更新时遇到问题,可以在 Content API 论坛上发布您的问题。
v2.1 中的其他更改
除了需要更新的变更之外,v2.1 还引入了几项新功能和非重大变更:
新服务:
新的
localinventory
服务可让您进行本地产品更新(代替 v2 中的inventory
服务)。新的
orderreturns
服务让您无需使用orders
服务即可处理退货,从而更轻松地管理“在 Google 上购买”(以前称为“购物行动”)。
利用补充 Feed,您可以进行部分商品更新。
对
products
服务的其他更改:products.insert
请求不再报告非严重警告或错误。这样,您就可以在 Merchant Center 中通过 Feed 规则插入商品并进行后续更新来解决问题,就像处理在 Content API 外部管理的 Feed 一样。添加了
products.update
,可让您更新一组选定的商品字段。如需详细了解可能的用法,请参阅指南。以下属性的无效值不会再触发插入错误,并作为
itemLevelIssues
的一部分由productstatus
服务返回:ageGroup
availability
condition
energyEfficiencyClass
gender
maxEnergyEfficiencyClass
minEnergyEfficiencyClass
sizeSystem
sizeType
自定义属性现在是递归属性,因此无需自定义组。
除了原始的
value
字段之外,自定义属性现在还具有groupValues
字段。必须设置其中一个字段。