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"])。 |