本指南說明如何將整合項目從 Content API for Shopping 的 datafeeds 和 datafeedstatuses 服務,遷移至 Merchant API 的 Data Sources 子 API。新的 Data Sources 子 API 可讓您更直接控管資料管道,並簡化資料來源管理。
如要進一步瞭解新功能,請參閱「管理資料來源」指南。
主要差異
與 Content API for Shopping 相比,Merchant API 有幾項優勢:
明確建立資料來源。首次插入產品時,API 不會再自動建立「Content API」資料來源。在 Merchant API 中,您須先明確建立資料來源,才能將產品上傳至該來源。這樣從一開始,就能有效控管產品資料管道的組織架構和管理作業。
支援多個 API 資料來源。在 Content API for Shopping 中,你只能使用單一自動建立的「Content API」資料來源。你可以使用 Merchant API 建立及管理多個
API輸入類型的資料來源。沒有標籤和語言的資料來源。Merchant API 可讓您建立主要資料來源,而不必指定
feedLabel和contentLanguage。這類資料來源接受feedLabel和contentLanguage的任何組合,可簡化產品上傳作業,適用於不需要為不同區域提供個別資料來源的整合。簡化資料目標。現在每個資料來源都對應一個目標,由
feedLabel和contentLanguage的不重複組合定義。Merchant API 已淘汰多資料目標動態饋給。專屬檔案上傳狀態。Merchant API 會使用獨立的唯讀
fileUploads資源,代表檔案式資料來源的狀態。如要擷取檔案上傳狀態,請使用fileUploads.get方法和latest別名。新資料來源類型。
DataSource資源支援更多產業,包括促銷活動、店面商品目錄資料和區域商品目錄,可讓您以統一的方式管理所有資料管道。自動資料來源:現在,你可以透過 Merchant API,使用 Accounts sub-API 中的
autofeedSettings.updateAutofeedSettings方法,為帳戶啟用或停用自動資料來源功能。詳情請參閱「調整自動動態饋給設定」。
選擇資料來源策略
管理資料來源的方式有三種:
為任何動態饋給標籤和語言建立單一 Merchant API 資料來源。這個選項可簡化管理作業,因為單一資料來源可接受任何
feedLabel和contentLanguage的產品。在舊版 Content API 設定中,您需要透過不同的資料來源,為特定標籤和語言定義規則,並將產品插入具有相應指定規則的資料來源。如果選擇這個選項,建議將所有產品遷移至新的資料來源,並在所有產品遷移完畢後,移除 Content API 資料來源。為每個標籤和語言建立新的 Merchant API 資料來源。 如果您需要支援新的
feedLabel和contentLanguage組合 (且偏好嚴格區分兩者),或使用依賴特定feedLabel和contentLanguage的資料來源規則設定,請使用這個選項。您必須為使用的每組feedLabel和contentLanguage建立個別資料來源。你可以將 Merchant API 資料來源與透過 Content API for Shopping 建立的資料來源合併。
- 保留現有的 Content API 資料來源。你可以繼續使用透過 Content API for Shopping 建立的資料來源,因為這些資料來源與 Merchant API 相容。你可以使用
dataSources.list或在 Merchant Center 使用者介面中,找出這些資源名稱。Content API 主要資料來源僅支援建立時指定的feedLabel和contentLanguage。即使產品是使用 Merchant API 插入,Content API 資料來源在 Merchant Center 中仍會顯示為「Content API」來源。你可以將這些資料來源與新的 Merchant API 資料來源合併,後者也指定特定的feedLabel和contentLanguage組合。
建議您回填本機產品資料庫,為每項產品儲存一次所有主要資料來源的名稱,避免重複呼叫 dataSources.list。
要求
下表比較 Content API for Shopping 和 Merchant API 的要求網址格式。
| 要求說明 | Content API for Shopping | Merchant API |
|---|---|---|
| 建立資料來源 | POST https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds |
POST https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources |
| 取得資料來源 | GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID} |
GET https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID} |
| 列出資料來源 | GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds |
GET https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources |
| 更新資料來源 | PUT https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID} |
PATCH https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID} |
| 刪除資料來源 | DELETE https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID} |
DELETE https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID} |
| 擷取資料來源 | POST https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeeds/{DATAFEED_ID}/fetchNow |
POST https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}:fetch |
| 取得資料來源狀態 | GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeedstatuses/{DATAFEED_ID} |
GET https://merchantapi.googleapis.com/v1/accounts/{ACCOUNT_ID}/dataSources/{DATASOURCE_ID}/fileUploads/latest |
| 列出資料來源狀態 | GET https://shoppingcontent.googleapis.com/content/v2.1/{MERCHANT_ID}/datafeedstatuses |
無法使用。為每個檔案資料來源使用 dataSources.list 和 fileUploads.get。 |
ID
Merchant API 會使用字串形式的資源名稱做為 ID。
| ID 說明 | Content API for Shopping | Merchant API |
|---|---|---|
| 資料來源 ID | datafeedId (數字) |
name (字串,格式:accounts/{account}/dataSources/{datasource}) |
方法
下表比較 Content API for Shopping datafeeds 和 datafeedstatuses 服務的方法,以及 Merchant API 中的對應方法。
| Content API for Shopping 方法 | Merchant API 方法 | 適用情形和注意事項 |
|---|---|---|
datafeeds.custombatch |
無法使用 | 請改用個別 API 呼叫。 |
datafeeds.delete |
dataSources.delete |
有。 |
datafeeds.fetchnow |
dataSources.fetch |
有。這個方法現在僅適用於檔案輸入的資料來源。 |
datafeeds.get |
dataSources.get |
有。 |
datafeeds.insert |
dataSources.create |
有。 |
datafeeds.list |
dataSources.list |
有。 |
datafeeds.update |
dataSources.update |
有。使用 PATCH 語意,而非 PUT。 |
datafeedstatuses.custombatch |
無法使用 | 請改用個別 API 呼叫。詳情請參閱「一次傳送多項要求」。 |
datafeedstatuses.get |
fileUploads.get |
適用於檔案型資料來源。使用 latest 別名,即可取得最近一次上傳作業的狀態。如果是其他資料來源類型,狀態資訊會包含在 DataSource 資源中。 |
datafeedstatuses.list |
無法使用 | 如要取得多個資料來源的狀態,請先使用 dataSources.list 列出所有資料來源。然後使用每個檔案型資料來源的 latest 別名呼叫 fileUploads.get。 |
詳細欄位變更
下表顯示 Content API for Shopping 中 Datafeed 和 DatafeedStatus 資源,以及 Merchant API 中 DataSource 和 FileUpload 資源之間的欄位層級異動。
| Content API for Shopping | Merchant API | 說明 |
|---|---|---|
Datafeed |
DataSource |
資料來源設定的主要資源。 |
id |
name |
資源 ID。從數字 ID 變更為字串資源名稱。 |
name |
displayName |
資料來源的名稱 (面向使用者)。 |
attributeLanguage |
primaryProductDataSource.contentLanguage |
資料來源中項目的雙字母 ISO 639-1 語言代碼。 |
fileName |
fileInput.fileName |
上傳檔案的名稱。這個欄位現在會巢狀置於 fileInput 下方。 |
fetchSchedule |
fileInput.fetchSettings |
擷取檔案資料來源的時間表。現在,這個項目會嵌套在 fileInput 下方。 |
fetchSchedule.paused |
fileInput.fetchSettings.enabled |
邏輯相反。paused: true 相當於 enabled: false。 |
format |
無法使用 | fileEncoding、columnDelimiter 和 quotingMode 欄位已移除。現在系統會自動偵測這類活動。 |
targets |
primaryProductDataSource.feedLabel、primaryProductDataSource.contentLanguage、primaryProductDataSource.countries |
重複的 targets 欄位已移除。現在,每個資料來源都有由這些欄位定義的單一目標,反映出多資料目標動態饋給已淘汰。 |
DatafeedStatus |
FileUpload |
檔案上傳狀態現在是獨立的唯讀資源。 |
datafeedId |
name |
檔案上傳的 ID,參照其上層資料來源。 |
processingStatus |
processingState |
上傳項目的處理狀態。字串值 (success、failure、in progress) 會替換為列舉 (SUCCEEDED、FAILED、IN_PROGRESS)。 |
errors、warnings |
issues |
錯誤和警告會合併為單一 issues 清單。每個問題都有 severity 欄位 (ERROR 或 WARNING)。 |
lastUploadDate |
uploadTime |
上次上傳的時間戳記。格式已從字串變更為 Timestamp 物件。 |
country、language、feedLabel |
不適用 | 狀態資源不再包含這些欄位。這些是 DataSource 資源的一部分。 |
targets[].included_destinations、targets[].excluded_destinations |
primaryProductDataSource.destinations |
原本包含和不適用目的地清單,將合併為單一 destinations 清單。新清單中的每個項目都是一個物件,用於指定目的地及其狀態 (ENABLED 或 DISABLED),提供更明確的設定。 |