从 Content API v2 迁移到 v2.1

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 字段。必须设置其中一个字段。