從 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

如要進一步瞭解 2.1 版服務和端點，請參閱 API 參考資料。

進行必要變更

除了更新 API 呼叫的網址，您也需要更新應用程式，以因應 v2.1 中導入的幾項重大變更。請參閱下列章節，並視需要更新應用程式。

1. 更新與 inventory 服務的整合

v2 inventory 服務已移除，但您可以使用下列 v2.1 功能，取得同等功能：

2. 更新對 accounts 服務的呼叫

  • 在 2.1 版中，呼叫 accounts.update 方法會完全覆寫 accounts 資源，而不是只更新要求中包含的欄位。為避免刪除 accounts 資源中的欄位，請更新呼叫要求，加入所有欄位。

  • 已移除「reviewsUrl」。

  • 已移除「inactive」的連結狀態，適用於「adsLinks」、「googleMyBusinessLink」和「youtubeChannelLinks」。

3. 更新對 products 服務的呼叫

  • 自訂屬性不再包含類型和單位。而是附加至值，且系統應會自動偵測類型。

  • 重複欄位 productTypes 已取代 productType 和 additionalProductTypes。

  • 重複欄位 includedDestinations 和 excludedDestinations 已取代重複欄位 destinations。

  • 下列 AdWords 相關欄位已重新命名：

    • adwordsGrouping -> adsGrouping
    • adwordsLabels -> adsLabels
    • adwordsRedirect -> adsRedirect

  • 下列欄位已遭移除：

    • aspects
    • destinations
    • onlineOnly
    • validatedDestinations
    • warnings

  • includeInvalidInsertedItems 參數已移除。在 2.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" 的資料動態饋給。

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

  • 在 2.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 的用途」。如果在測試更新時遇到問題，請與我們聯絡。

2.1 版的其他異動

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

  • 新服務：

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

    • 有了這項新服務 orderreturns，你就能更輕鬆地管理「透過 Google 購物」(前稱「購物行動」)，不必使用 orders 服務即可處理退貨。

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

  • products 服務的其他異動：

    • products.insert 要求不再回報不嚴重的警告或錯誤。 這樣一來，你就能插入產品，並透過 Merchant Center 中的動態饋給規則解決問題，如同管理不是用 Content API 維護的其他動態饋給。

    • products.update，方便你更新所選的一組產品欄位。如要進一步瞭解可能的使用方式，請參閱指南。

    • 下列屬性的無效值不會再觸發插入錯誤，而是由 productstatus 服務以 itemLevelIssues 的形式傳回：

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

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

    • 自訂屬性現在除了原始的 value 欄位外，還包含 groupValues 欄位。必須設定其中一個欄位。