從 Content API v2 遷移至 v2.1

我們在 2019 年 3 月推出 2.1 版 Content API for Shopping，並於 2021 年 4 月宣布第 2 版將於 2021 年 9 月 30 日停用。第 2 版已終止服務。請立即遷移至 2.1 版。

遷移應用程式

從 v2 遷移至 v2.1 時，需要更新端點網址以呼叫新的 2.1 版，並修改應用程式，以因應 2.1 版中導入的破壞性變更。

請更新 API 呼叫以使用 v2.1 端點

如要呼叫 2.1 版，請將要求更新為使用新的 v2.1 端點。

舉例來說，如要使用第 2 版呼叫 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 呼叫的網址外，您還需要更新應用程式，以因應 2.1 版導入的多項破壞性變更。請查看以下各節，並視需要更新應用程式。

1. 更新與「inventory」服務的整合

v2 inventory 服務已移除，下列 2.1 版功能提供同等功能：

2. 更新對 accounts 服務的呼叫

  • 在 2.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

  • 第 2 版選項 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" 的資料動態饋給。

6. 更新對 orders 和 TestOrders 服務的呼叫

  • 在 2.1 版中，呼叫不應納入稅金資料，因為系統會自動計算稅金資料。如果訂單履行具有 Marketplace 公平性法 (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 未提供的功能

第 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 的測試使用情形」。如果您在測試更新時遇到問題，可以將問題張貼在 Content API 論壇。

2.1 版的其他變更

此外，2.1 版除了需要更新的變更外，還推出了幾項新功能和非破壞性變更：

  • 新服務：

    • 新的 localinventory 服務可讓您更新店面產品 (取代 v2 中的 inventory 服務)。

    • 新的 orderreturns 服務 (舊稱「購物行動」) 可讓您在無需使用 orders 服務的情況下處理退貨，讓您更輕鬆管理 Buy on Google (舊稱「購物行動」)。

  • 補充動態饋給可讓您更新部分產品。

  • products 服務的其他變更：

    • products.insert 要求不會再回報不嚴重的警告或錯誤。如此一來，您就能透過 Merchant Center 中的動態饋給規則插入產品並進行後續更新，以解決問題，就像處理非 Content API 所管理的動態饋給一樣。

    • 已新增 products.update，方便您更新一組選定的產品欄位。如要進一步瞭解可能的用法，請參閱指南。

    • 下列屬性值的無效值不會再觸發插入錯誤，且 productstatus 服務會在 itemLevelIssues 中傳回值：

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

    • 自訂屬性現在為遞迴，因此不再需要自訂群組。

    • 除了原始的 value 欄位以外，自訂屬性現在也包含 groupValues 欄位。只能設定其中一個欄位。