从 Content API v2 迁移到 v2.1

2019 年 3 月，我们发布了 Content API for Shopping 的 2.1 版本；2021 年 4 月，我们宣布 v2 将于 2021 年 9 月 30 日停用。版本 v2 已停用。请立即迁移至 2.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) 或类似立法的州完成，则包含税费数据的调用会失败。如果订单在未采用市场公平法案的州完成配送，则税费将根据 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 中未包含的功能

2.1 版 Content API 中还移除了其他几项功能。请查看以下列表，并根据需要更新您的申请：

  • 不再支持 XML。如需详细了解如何改用 JSON，请参阅 Content API for Shopping 中 XML 支持的终止。

  • dryRun 参数已移除。此变更适用于所有 API 调用。

  • 移除了所有 HTTP BATCH 方法。请改用 customBatch。

  • 已从以下服务中移除 patch 方法：

    • accounts
    • accounttax
    • datafeeds
    • liasettings
    • shippingsettings

  • orderpayments 服务已被移除。

测试迁移

如需详细了解在迁移到 v2.1 后如何测试应用中的更改，请参阅测试 Content API for Shopping 的使用情况。 如果您在测试更新时遇到问题，可以与我们联系。

v2.1 中的其他更改

除了需要更新的更改之外，v2.1 还引入了多项新功能和非破坏性更改：

  • 新服务：

    • 借助新的 localinventory 服务，您可以进行本地产品更新（取代 v2 中的 inventory 服务）。

    • 借助新的 orderreturns 服务，您可以处理退货，而无需使用 orders 服务，从而更轻松地管理“在 Google 上购买”（以前称为“购物行动计划”）。

  • 借助补充 Feed，您可以进行部分商品更新。

  • 对 products 服务的其他更改：

    • products.insert 请求不再报告非严重警告或错误。 这样一来，您就可以插入商品，并通过 Merchant Center 中的 Feed 规则进行后续更新来解决问题，就像对待通过 Content API 以外的方式管理的 Feed 一样。

    • 我们添加了 products.update，以便您更新所选的一组商品字段。如需详细了解可能的使用情况，请参阅指南。

    • 以下属性的无效值不会再触发插入错误，而是作为 productstatus 服务返回的 itemLevelIssues 的一部分：

      • ageGroup
      • availability
      • condition
      • energyEfficiencyClass
      • gender
      • maxEnergyEfficiencyClass
      • minEnergyEfficiencyClass
      • sizeSystem
      • sizeType

    • 自定义属性现在是递归属性，无需自定义组。

    • 除原始 value 字段外，自定义属性现在还具有 groupValues 字段。必须设置且只能设置一个字段。