選擇檔案動態饋給或 Merchant API

你可以使用檔案式動態饋給、Merchant API 或兩者並用，將產品資料上傳至 Merchant Center：

• 檔案型產品動態饋給：使用 SFTP、Google Cloud Storage、Google 試算表或排程擷取功能，上傳 CSV、TSV 或 XML 檔案。
• Merchant API：直接從後端傳送程式輔助要求，在產品資料變更時進行增量更新，並定期同步完整目錄。

本指南會比較這兩種方法，說明何時應使用其中一種方法 (或同時使用兩種方法)，並提供逐步遷移指南，協助你將部分或所有產品從檔案動態饋給轉移至 API。

選擇資料來源方法

評估目錄變動性、後端架構和作業工作流程，決定要使用 Merchant API、檔案動態饋給，還是混合設定。

Merchant API 的使用時機

在下列情況下，請使用 API 主要資料來源：

• 直接程式輔助整合：您偏好直接從後端呼叫 API，而不是產生檔案及管理檔案移轉管道 (例如 SFTP 或 Google Cloud Storage)。
• 價格和商品目錄波動大：產品價格或庫存量在一天內頻繁變動。
• 資料變更時立即更新：你想在後端發生產品變更時，立即將變更傳送給 Google，而不是等待下次排定的檔案生成和上傳。
• 漸進式目錄更新：您想在個別產品有異動時，插入、更新或刪除這些產品，而不必每次都重新上傳整個目錄。
• 部分屬性更新：您想更新產品的特定欄位 (例如使用 productInputs.patch 更新 price 或 availability)，但不想重新傳送完整的產品酬載。

檔案動態饋給的使用時機

在下列情況下，請使用檔案式主要資料來源：

• 靜態目錄：產品資料不常變更 (例如每天一次或更少)。
• 僅限快照後端，不追蹤差異：後端只會匯出完整的目錄快照，無法追蹤項目層級的變更或明確刪除的產品。
• 以試算表為基礎的工作流程：非工程團隊直接在 Google 試算表或 CSV 檔案中，管理或覆寫產品資料。
• 低維護作業：您偏好排定檔案匯出作業，由 Merchant Center 處理擷取和快照處理作業，而非透過 API 整合，處理要求頻率、重試處理和定期完整目錄同步。

兩者並用的時機

在下列情況下，您可以在同一個 Merchant Center 帳戶中，結合使用檔案動態饋給和 Merchant API：

• 分區產品目錄：使用 Merchant API 處理快速變動的產品 (例如快閃促銷或高週轉率商品)，並使用檔案動態饋給處理靜態目錄區隔或獨立產品系列。確認每項產品都只透過一個主要資料來源上傳 (請參閱「並行使用和主要資料來源擁有權」)。
• API 主要資料搭配檔案型補充動態饋給：你透過 API 主要資料來源管理核心產品資料，而非工程團隊或第三方合作夥伴則透過檔案型補充動態饋給 (例如 Google 試算表或 CSV 檔案) 提供額外屬性，並與屬性規則結合，反之亦然。
• 部分或分階段遷移：將特定市場、類別或子帳戶轉移至 API，同時保留其餘目錄的檔案動態饋給。

如要將部分或所有產品從檔案動態饋給移至 Merchant API，請按照逐步遷移指南操作。

主要架構差異

檔案動態饋給和推送式 Merchant API 在 Google 處理及管理產品資料的方式上有所不同：

概念	檔案動態饋給	Merchant API
整合模式	離線檔案轉儲：將目錄匯出至檔案，並透過 SFTP、Google Cloud Storage、Google 試算表或排程擷取功能轉移。	直接程式輔助整合：後端直接將要求傳送至 API 端點。
異動精細程度	大量處理：修改單一項目通常需要重新處理整個檔案。	精細交易：你只能插入、修補或刪除已變更的產品。
同步處理時間	批次同步處理：變更會保留在後端，直到下一次排定的檔案匯出和轉移週期。	立即或排定呼叫：您可以在發生異動時立即傳送增量變更，並定期執行完整同步作業。
刪除行為	隱含 (快照)：每個檔案都是完整的快照；從主要檔案中移除資料列，就會刪除產品。	明確：沒有快照概念，請呼叫 productInputs.delete 移除停售產品。
資源表示法	單一狀態：檔案的資料列代表原始輸入內容。	區分原始和處理後的資料：API 會將資料分為 ProductInput (原始輸入內容) 和 Product (最終處理狀態)。
屬性 (動態饋給) 規則	套用至 Merchant Center 使用者介面中的原始檔案資料欄。	Merchant Center 使用者介面支援這項功能。將 API 資料與第三方補充檔案合併時，必須提供這項資訊；如果單一來源轉換作業是在後端處理，則可視需要提供。

並行使用和主要資料來源擁有權 (「以最後更新者為準」)

雖然你可以在同一個 Merchant Center 帳戶中同時使用檔案動態饋給和 API，但強烈建議你只使用一種方法插入任何指定產品。

Merchant Center 採用「以最新更新為準」模式。推送最新產品插入項目的主要資料來源 (API 或檔案動態饋給)，會取得該產品資料的主要擁有權：

• 如果產品是由檔案資料來源擁有：在後續上傳檔案時省略產品，會觸發隱含刪除，將產品從 Merchant Center 移除。
• 產品由 API 資料來源擁有：由於檔案動態饋給不再擁有產品，因此從檔案上傳中省略產品不會有任何影響。您必須呼叫 accounts.productInputs.delete 才能移除。
• 意外重新取得擁有權的風險：如果更新後的檔案動態饋給在 API 推送後執行，且包含產品，檔案資料來源會重新取得擁有權。如果之後從檔案中省略該產品，系統就會意外刪除該產品。

為避免意外刪除或遺失 API 更新，請勿同時使用 API 和檔案主要資料來源，對相同產品執行更新。

API 重要注意事項

開始導入前，請先瞭解下列 Merchant API 的重要行為：

彈性資料來源 (不含語言或標籤)

檔案動態饋給需要預先定義特定的目標動態饋給標籤和語言，Merchant API 則可讓您建立主要資料來源，而不必指定 feedLabel 或 contentLanguage。

• 彈性上傳：可將任何語言或動態饋給標籤組合的產品，上傳至單一資料來源。
• 簡化管理：不必為每個目標市場建立及管理個別 資料來源。 注意：如要進一步瞭解如何選擇資料來源策略，請參閱「選擇資料來源策略」。

同步策略和配額

檔案動態饋給會一次上傳整個目錄，但 Merchant API 整合則不同，請根據增量更新和定時完整同步處理來設計：

• 結合增量更新與定期完整同步：後端的產品屬性變更時，請傳送 productInputs.insert 或 productInputs.patch 要求。如果只依賴增量更新，資料可能會隨著時間而不同步，因此請定期執行完整同步處理，根據可靠資料來源調整目錄 (這也會重新整理 30 天的產品到期時間)。執行完整同步處理的頻率取決於目錄大小和可用的 API 配額。
• 依 API 配額調整要求速度：請勿一次呼叫所有產品的 API。雖然增量變更可在發生時傳送，但請將完整同步要求平均分配到一整天，以免超出每分鐘和每日方法呼叫配額。詳情請參閱「配額與限制」和「經常更新產品」。

測試整合

在安全環境中驗證整合邏輯，再移至正式環境。

使用測試帳戶

建議您先在沙箱測試帳戶中執行遷移作業的初始步驟，再對正式環境進行變更：

1. 建立測試帳戶：設定獨立的測試帳戶，安全地進行實驗，不影響實際廣告或免費產品資訊。
2. 建立 API 資料來源：練習建立 API 主要資料來源。
3. 測試屬性規則：驗證資料轉換和補充動態饋給彙整。
4. 驗證酬載和產品金鑰：推送範例產品，驗證 SKU 大小寫、編碼和錯誤處理。

詳情請參閱「步驟 1：建立測試帳戶」和「測試帳戶」指南。

驗證產品金鑰是否一致

請確認程式輔助酬載產品金鑰與檔案動態饋給 SKU 完全一致。Google 會結合以下資訊來識別產品：

• offerId (在檔案動態饋給中稱為 id，區分大小寫)
• contentLanguage (例如 en)
• feedLabel (例如 US)

注意：如果檔案動態饋給使用小寫 SKU (例如 sku-123)，而 API 整合傳送大寫 SKU (例如 SKU-123)，Google 會將兩者視為不同產品。這會導致項目重複，且放送記錄遺失。

特殊字元和編碼

如果產品 ID 包含 /、% 或 ~ 等字元，請在 API 呼叫中使用編碼格式 (未填補的 base64url 編碼)。詳情請參閱 ProductInput.name

並行控制

在即時整合中，更新可能會因網路延遲而未按順序送達。為避免舊更新覆寫新資料，請使用 ProductInput 資源中的 versionNumber 欄位。

逐步遷移教戰手冊

如果您決定將部分或所有產品從檔案動態饋給移至 Merchant API，請按照這份指南操作，在不損失曝光次數或放送記錄的情況下轉移產品。

1. 在測試帳戶中演練遷移作業

在實際執行環境中進行變更前，請使用 accounts.createTestAccount 方法建立沙箱測試帳戶 (請參閱測試帳戶指南)。測試帳戶提供獨立環境，預設會核准商品，不需驗證網域，且資料絕不會公開。

使用測試帳戶複製正式版設定，並演練端對端遷移作業：

1. 複製檔案動態饋給設定：在測試帳戶中建立檔案主要資料來源 (和任何補充資料來源)，並上傳正式版動態饋給檔案範例。
2. 建立測試 API 資料來源和規則：建立 API 主要資料來源，並設定任何必要的屬性規則或補充動態饋給彙整。
3. 測試擁有權轉移和金鑰對應：傳送範例產品的 productInputs.insert 要求，並確認 API 資料來源取得現有項目的擁有權，且未建立重複的產品。
4. 驗證更新和刪除作業：使用 productInputs.patch 測試部分更新，並使用 productInputs.delete 測試移除作業，然後使用 products.get 檢查產生的資源。

2. 建立正式版 Products API 資料來源

推送資料前，請先在帳戶中建立 API 類型的主要資料來源。

建立 API 主要資料來源

如要建立接受 API 推送的資料來源，請向 dataSources 端點傳送 POST 要求。詳情請參閱「建立主要產品資料來源」。

3. 轉換自訂屬性規則

自訂屬性規則會繫結至特定資料來源，不會自動從檔案資料來源轉移至新的 API 資料來源。

轉換屬性規則的方式取決於規則用途：

• 跨來源合併和第三方補充動態饋給：如要合併主要 API 資料和外部補充資料來源 (例如第三方供應商檔案、商品目錄試算表或促銷活動動態饋給)，請務必在 Merchant Center 使用者介面中重新建立屬性規則，並附加至新的 API 資料來源。用戶端預先處理無法取代彙整多個獨立來源資料的規則。
• 單一來源資料轉換：如要對主要目錄資料進行單一來源清理、預設值或字串格式設定，請選擇下列其中一項：
  • 後端轉換 (建議)：在呼叫 API 之前，先在自己的系統中套用轉換。這可讓您更有效地控管程式、更輕鬆地進行測試，並簡化偵錯作業。
  • Merchant Center 屬性規則：如要讓 Merchant Center 繼續自動管理轉換規則，請在 Merchant Center 使用者介面中，為新的 API 資料來源重新建立轉換規則。

4. 啟用 API 整合

啟用正式版 API 整合，開始在新的 API 主要資料來源中插入、更新及刪除產品：

• 插入及更新產品 (接管擁有權)：從整合項目傳送 productInputs.insert 和 productInputs.patch 要求。使用 API 插入產品時，如果產品的鍵 (offerId、contentLanguage、feedLabel) 與現有檔案動態饋給產品相同，API 資料來源會取得該產品的擁有權，並保留其放送記錄。如需更多指引，請參閱「插入產品」和「新增及管理產品」。

  重要事項：你只能使用 productInputs.patch 更新已插入 API 主要資料來源的產品。更新產品前，請務必先將產品插入 API 主要資料來源 (因此由 API 主要資料來源擁有)。

• 刪除停售產品：設定整合功能，在產品從目錄中移除時，明確呼叫 productInputs.delete。

• 逐步部署：如果目錄較大，請一次啟用一個 Merchant Center 子帳戶或一個資料來源的整合。

• 設定並行：如要傳送大量要求，請設定用戶端處理並行要求及管理多個連線。請參閱「重構程式碼以處理並行要求」指南。

5. 暫停更新檔案資料來源

API 整合啟用後，請在下次排定的檔案執行前停止檔案更新，以免檔案資料來源覆寫 API 更新：

1. 停止將新檔案上傳至 SFTP/FTP 位置、Google Cloud Storage 或 Google 試算表。
2. 在 Merchant Center 使用者介面中，前往檔案資料來源，並暫停排程擷取。
3. 檔案資料來源擁有的現有產品最多會保留 30 天，直到 API 整合插入這些產品為止。

6. 等待遷移作業完成並驗證

等待所有有效產品從檔案資料來源遷移至 API 資料來源。雖然增量更新會隨著產品變更而遷移產品，但透過定期整合執行分段完整目錄同步作業，可加快遷移整個目錄的速度 (請參閱「同步策略和配額」)。

在這個階段：

1. 在 Merchant Center 使用者介面中，監控商品數量。請等到檔案資料來源數量減少至 0，且 API 資料來源數量與有效目錄相符。
2. 使用 products.get 確認屬性和自訂屬性規則是否如預期合併。
3. 在 Merchant Center 使用者介面中，監控 API 診斷工具，追蹤錯誤率和 API 效能。

7. 停用檔案資料來源

轉換完成後，檔案動態饋給項目數量為 0：

1. 確認更新內容即時反映。
2. 在 Merchant Center 使用者介面中刪除舊版檔案資料來源，以免檔案型更新意外覆寫 API 資料。