遷移產品

Merchant API 提供更強大、更直覺的產品資料管理方式。主要異動是將產品資料分成兩個不同的資源:ProductInput 用於提交資料,Product 則用於查看最終處理版本,包括產品狀態和問題。新結構可提供更可預測且透明的體驗。

本指南將逐步說明主要差異,協助您從 Content API for Shopping 遷移整合。如需使用新功能的詳細指南,請參閱「管理產品」。

主要差異

相較於 Content API for Shopping,Merchant API 在產品管理方面有以下重大異動:

  • 輸入和處理資料的專屬資源:Merchant API 將產品管理分為兩項資源。您可以使用 ProductInput 資源插入、更新及刪除產品資料。Google 處理輸入內容、套用規則並合併補充來源的資料後,您可以使用唯讀 Product 資源查看最終產品。

  • 產品名稱編碼:ProductInput.name 和 Product.name 欄位皆可使用未填充的 base64url (RFC 4648 第 5 節) 編碼。如果產品名稱包含 Merchant API 使用的字元或網址保留字元,則必須編碼。舉例來說,如果產品名稱包含下列任一字元,就必須進行編碼:

    % . + / : ~ , ( * ! ) & ? = @ # $
    
  • 整合產品狀態:productstatuses 服務已移除。產品驗證問題和目的地狀態現在會直接包含在 productStatus 欄位中的 Product 資源,簡化資料擷取作業。

  • 可預測的產品更新:新的 productInputs.patch 方法會直接修改特定產品輸入內容。這項功能比 Content API for Shopping 有顯著改善,因為後者可能會因其他動態饋給上傳作業,而意外覆寫更新內容。在 Merchant API 中,更新會保留到該特定產品輸入資料再次更新或刪除為止。產品更新會套用至 ProductInput 資源,而非處理過的 Product 資源。

  • 選擇資料來源,更輕鬆管理資料:所有 productInputs 寫入作業現在都需要 dataSource 查詢參數,明確指出要修改的資料來源。如果有多個資料來源,這項功能特別實用。

  • 新資源 ID:產品現在由 RESTful 資源 name 識別,而非 id 欄位。格式為 accounts/{account}/products/{product}。

  • 不支援自訂批次:custombatch 方法已無法使用。您可以使用非同步要求或 HTTP 批次處理,在單一 HTTP 呼叫中傳送多個要求。

遷移期間的資料來源規範

遷移資料來源前,強烈建議您選擇資料來源策略。

為確保遷移作業順利進行,並避免發生優惠遭竊等問題,請遵循下列建議:

  • 補充資料庫:強烈建議您對本機資料庫執行一次性補充,而不是在每次產品作業前呼叫 dataSources.list。請在每筆產品記錄中新增 dataSource 名稱欄位,以便直接在要求中提供正確的 ID。

  • 整合並使用任何標籤和語言的資料來源:Merchant API 可讓您建立資料來源,而不必指定標籤和語言,因此可插入任何資料來源標籤和語言的產品。建議為所有標籤和語言使用單一資料來源。

  • 保護產品:如果使用資料來源規則,請先呼叫 products.get,找出與產品相關聯的確切 dataSource,再更新或刪除產品。這可確保您修改的是預期來源,並防止意外竊取優惠。

要求

本節比較 Content API for Shopping 和 Merchant API 的要求格式。

要求說明 Content API for Shopping Merchant API
取得產品 GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
列出產品 GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
插入一項產品 POST https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products POST https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs:insert
更新產品 PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} PATCH https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
刪除產品 DELETE https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId} DELETE https://merchantapi.googleapis.com/products/v1/accounts/{account}/productInputs/{productinput}
取得產品狀態 GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses/{productId} GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products/{product}
列出產品狀態 GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/productstatuses GET https://merchantapi.googleapis.com/products/v1/accounts/{account}/products
批次處理多項要求 POST https://shoppingcontent.googleapis.com/content/v2.1/products/custombatch 使用非同步要求或 HTTP 批次處理

ID

Merchant API 的產品 ID 格式已變更為標準 REST 資源名稱。

ID 說明 Content API for Shopping Merchant API
產品 ID 由多個區隔組成的字串,各區隔之間以半形冒號 (:) 分隔。
格式:channel:contentLanguage:targetCountry:offerId 或 channel:contentLanguage:feedLabel:offerId。
範例:online:en:US:sku123
REST 資源 name 字串。
格式:accounts/{account}/products/{product},其中 {product} 為 contentLanguage~feedLabel~offerId。
範例:accounts/12345/products/en~US~sku123。
編碼:建議使用未填補的 base64url 編碼,如果產品 ID 包含 Merchant API 使用的字元或網址保留字元,則必須使用。

方法

下表列出 Content API for Shopping 方法,以及 Merchant API 中的對應方法。

Content API for Shopping 方法 Merchant API 方法 適用範圍和注意事項
products.get products.get 擷取最終處理過的產品。
products.list products.list 列出最終處理過的產品。
products.insert productInputs.insert 插入產品輸入。須具備 dataSource。
products.update productInputs.patch 行為有明顯差異。這項屬性會更新特定產品輸入,且會持續生效。
products.delete productInputs.delete 刪除特定產品輸入。須具備 dataSource。
products.custombatch 無法使用 使用非同步要求或 HTTP 批次處理。
productstatuses.get products.get productstatuses 服務已移除。狀態資訊現在是 Product 資源的一部分。
productstatuses.list products.list productstatuses 服務已移除。狀態資訊現在是 Product 資源的一部分。
productstatuses.custombatch 無法使用 使用非同步要求或 HTTP 批次處理。

詳細欄位變更

下表列出 Merchant API 中變更、新增或移除的重要欄位。

Content API for Shopping Merchant API 說明
id name 產品的主要 ID 現在是 REST 資源 name。建議使用不含填補字元的 base64url 編碼,如果產品名稱包含 Merchant API 使用的字元或網址保留字元,則必須使用。
頂層產品資料規格屬性 (例如 title、price、link) productAttributes 個物件 title、price 和 link 等產品屬性不再是頂層欄位。現在,這些欄位會分組在 Product 和 ProductInput 資源的 productAttributes 物件中。這樣一來,資源結構會更簡潔、更有條理。
targetCountry feedLabel 資源名稱現在使用 feedLabel,而非 targetCountry,以配合 Merchant Center 功能。
feedId dataSource (查詢參數) 現在,所有 productInputs 寫入方法 (insert、update、delete) 都必須提供 dataSource 名稱做為查詢參數。
channel 無法使用。僅限店面產品使用 legacy_local。 Merchant API 不再提供 channel 欄位。在 Content API for Shopping 中,管道為 LOCAL 的產品應將 legacy_local 欄位設為 true。
無法使用 versionNumber ProductInput 的新選項欄位,可用來防止順序有誤的資料插入主要資料來源。
string 類型欄位,具有一組定義的值 enum 類型欄位,具有一組定義的值 產品屬性中具有定義值組合的欄位 (例如 excluded_destinations、availability) 現在為 enum 類型。
gtin productAttributes.gtins 從單一字串 (gtin) 變更為重複字串 (gtins)。
sizes productAttributes.size 從重複字串 (sizes) 變更為單數字串 (size)。
sizeType、additionalSizeType productAttributes.sizeTypes 將 sizeType 和 additionalSizeType 替換為重複的 SizeType 列舉 (sizeTypes),最多可接受兩個值 (例如 ["PETITE", "MATERNITY"])。