匯入目錄資訊

本頁說明如何匯入目錄資訊，並確保資訊保持最新狀態。

本頁的匯入程序適用於建議和搜尋。匯入資料後，這兩項服務都能使用該資料，因此如果您同時使用這兩項服務，就不必重複匯入相同資料。

你可以從 BigQuery 匯入產品資料，或在要求中內嵌指定資料。除了連結 Merchant Center 之外，這些程序都是一次性匯入。排定定期匯入目錄 (最好是每天) 的時間，確認目錄為最新版本。

請參閱「維持內容新鮮感」。

你也可以匯入個別產品項目。詳情請參閱「上傳產品」。

事前準備

開始匯入目錄前，請務必完成下列事項：

1. 設定專案。
2. 建立服務帳戶。
3. 將服務帳戶新增至本機環境。

詳情請參閱「設定先決條件」。

目錄匯入注意事項

本節說明可用於批次匯入目錄資料的方法、您可能使用各個方法的情況，以及部分限制。

教學課程

本節將透過影片和殼層教學課程，探討不同的目錄匯入方法。

教學課程影片

觀看這部影片，瞭解如何使用 Retail API 匯入目錄。

教學課程：從 BigQuery 匯入目錄

本教學課程說明如何使用 BigQuery 資料表匯入大量目錄資料，而且不受任何限制。

教學課程：從 Cloud Storage 匯入目錄

本教學課程說明如何將大量項目匯入目錄。

教學課程：透過內嵌方式匯入目錄資料

本教學課程說明如何透過內嵌方式將產品匯入目錄。

目錄匯入最佳做法

高品質資料才能產生高品質結果。如果資料缺少欄位，或包含預留位置值而非實際值，預測和搜尋結果的品質就會受到影響。

匯入目錄資料時，請務必採用下列最佳做法：

• 請務必仔細區分主要產品和子類產品。上傳任何資料前，請參閱產品層級。

  • 變更產品層級設定，以免在匯入資料後耗費大量心力。系統會將主要項目 (而非變體) 做為搜尋結果或推薦內容傳回。

  • 舉例來說，如果主要 SKU 群組是「圓領上衣」，建議模型就會傳回圓領上衣，以及船領和低圓領上衣。不過，如果未使用子類，且每個 SKU 都是主要項目，則建議面板會將每個顏色或尺寸組合的 V 領襯衫視為不同項目：棕色 V 領襯衫，XL 號；棕色 V 領襯衫，L 號，到白色 V 領襯衫，M 號；白色 V 領襯衫，S 號。

  • 只要在 collectionMemberIds[] 中加入主要產品 ID 和子類 ID，系統就能一併辨識產品系列。這會導致使用者事件擷取產品組合，使用者可能已從該組合購買一或多項產品，並將整個組合計入購買交易。這樣一來，系統就能在日後相關查詢中，向同一位使用者放送特定系列的其他產品。

  • 示例：使用者先前購買了被套，因此系統會傳回床單系列中的相符產品，例如枕套。

• 請遵守產品項目匯入限制。

  • 如要從 Cloud Storage 進行大量匯入，每個檔案的大小不得超過 2 GB。單一批次匯入要求一次最多可包含 100 個檔案。

  • 如要內嵌匯入，一次最多可匯入 5,000 項產品。

• 請確認必要目錄資訊是否完整且正確。請勿使用預留位置值。

• 盡可能提供選填的目錄資訊。

• 請確保所有活動都使用單一幣別，特別是如果您打算使用Google Cloud 控制台取得收益指標。Vertex AI Search for Commerce API 不支援每個目錄使用多種幣別。

• 建議每天更新目錄。定期匯入目錄可避免模型品質隨時間下降。使用「搜尋」的商家控制台匯入目錄時，可以排定自動週期性匯入作業。或者，您可以使用 Google Cloud Scheduler 自動匯入資料。

• 請勿記錄尚未匯入的產品項目的使用者事件。

• 匯入目錄資訊後，請查看專案的錯誤回報和記錄資訊。如果發現多個錯誤，請逐一檢查並修正導致錯誤的程序問題。

商家適用的 Vertex AI Search 資料擷取管道包含產品目錄和使用者事件資料。這項資料串流可做為基礎，透過意見回饋機制進行穩健的模型訓練和持續評估。準確且完整的資料擷取作業不僅是先決條件，也是持續進行的程序，有助於維持基礎模型的適應性。進而直接影響搜尋結果的品質和關聯性，大幅提升投資報酬率。

設計商務搜尋解決方案時，請考慮採用下列資料擷取最佳做法。

大量匯入、即時串流，還是兩者皆是？

商家適用的 Vertex AI Search 提供兩種主要目錄擷取方法：

• 大量匯入

• 即時串流

這種雙重做法可滿足各種客戶後端的不同架構需求。您不必只選擇一種方法，可以根據特定需求，採用混合式擷取模式，同時使用大量匯入和串流更新。

如果需要一次新增、刪除或更新數千項產品，就非常適合使用大量匯入功能。相較之下，如果需要持續更新相對較少量的產品，即時串流就很適合。選擇這些方法時，請考量產品目錄的性質、更新頻率，以及後端系統的整體架構。

大量匯入功能支援三種不同的資料來源：

• BigQuery：BigQuery 可快速修改目錄資料、在匯入期間指定分割日期，並透過 SQL 查詢有效轉換資料。
• Google Cloud Storage：Cloud Storage 必須遵守特定格式 (例如 JSON) 和檔案限制。使用者負責管理 bucket 結構、檔案分塊，以及匯入程序的其他方面。此外，直接在 Cloud Storage 中編輯目錄可能很麻煩，而且雖然可能符合成本效益，但缺乏其他方法的彈性。
• 內嵌資料：如果目錄很大，內嵌匯入可能不是最適合的選項，因為有大小限制。建議僅在小幅更新或實驗測試時使用。

如果產品目錄更新量大 (短時間內有數千項產品變更、新增或刪除)，且更新頻率固定，建議結合大量匯入和即時串流的方式，效果會非常好。在 BigQuery 或 Cloud Storage 中暫存更新，並定期執行增量大量匯入作業，例如每隔一到兩小時。這個方法可有效管理大規模更新，同時盡量減少中斷。

如果更新頻率較低，或是需要立即反映在目錄中，請使用即時串流 API。在混合式方法中，即時串流可填補大量匯入之間的間隙，確保目錄保持最新狀態。這項策略可平衡個別 REST API 呼叫 (用於修補產品) 和執行大量變更，進而提升 Vertex AI Search 電子商務目錄管理的效率和回應速度。

目錄管理的分支策略

在單一分店中維護統一目錄，而不是在多個分店中維護不同的目錄。這項做法可簡化目錄更新作業，並降低分支切換期間發生不一致的風險。

下列常見的分支策略適用於目錄管理。

單一分店更新

將即時分支版本設為預設，並在目錄變更時持續更新。如要大量更新，請在流量較低的時段使用匯入功能，盡量減少中斷。使用串流 API 進行較小的增量更新，或將更新批次處理成較大的區塊，以便定期匯入。

切換分支版本

管理不同分支有幾種方式：

• 使用分支版本進行暫存和驗證：

  • 部分商務網站工程師會選擇分支切換方法，在非即時分支中更新目錄，然後在準備好投入生產時，將其設為預設 (即時) 分支。這樣就能預先準備隔天的目錄。您可以透過大量匯入或串流方式，將更新內容匯入非即時分支，確保在流量較低時順暢轉換。
  • 要選擇哪種策略，取決於您的具體需求、更新頻率和基礎架構設定。不過，無論選擇哪種策略，在單一分支機構中維護統一的目錄，對於 Vertex AI Search for commerce 的最佳效能和一致的搜尋結果至關重要。

• 使用分支進行備份：

  • 單一即時分支會持續擷取及處理產品更新，確保商家適用的 Vertex AI Search 索引近乎即時更新。
  • 另一個分支則著重於在 Retail Search 中建立轉換後資料的每日快照，以做為強大的備援機制，避免資料毀損或分支 0 發生問題。
  • 第三個分支則著重於建立轉換後日期的每週快照。這樣一來，客戶就能在不同分支中，分別擁有前一天和前一週的備份。

清除目錄分支版本

如果將新目錄資料匯入現有分支，請務必清空目錄分支，確保匯入分支的資料完整性。如果分支版本為空，你可以匯入新的目錄資料，並將分支版本連結至商家帳戶。

如果您正在放送即時預測或搜尋流量，並打算清除預設分支版本，請先指定其他分支版本做為預設版本，再清除預設分支版本。由於預設分支在清除後會提供空白結果，因此清除預設分支可能會導致服務中斷。

如要從目錄分支版本清除資料，請完成下列步驟：

1. 前往「Search for commerce」控制台的「資料」頁面。
   
   前往「資料」頁面

2. 從「分支版本名稱」欄位選取目錄分支版本。

3. 在「Branch name」(分支名稱) 欄位旁邊的三點選單中，選擇「Purge branch」(清除分支)。

   系統會顯示訊息，警告您即將刪除分支中的所有資料，以及為分支建立的任何屬性。

4. 輸入分支版本，然後按一下「確認」，即可清除分支版本中的目錄資料。

   系統會啟動長時間執行的作業，從目錄分支版本清除資料。 清除作業完成後，清除狀態會顯示在「活動狀態」視窗的「產品目錄」清單中。

Vertex AI Search for Commerce 的商品目錄更新

本節說明如何定期更新目錄，進而提升商家適用的 Vertex AI Search 效能。

即時串流

• 如要使用動態資料，例如庫存資訊 (價格、供應情形) 和商店層級詳細資料 (包括出貨狀態和商店專屬價格)，只能在商家適用的 Vertex AI Search 中使用即時串流。
• 這是因為相較於相對靜態的產品目錄資料，廣告空間的波動頻率較高。產品供應情形每天可能會多次變動，但說明或屬性相對穩定。
• 零售地點越多，商店層級的更新頻率就越高。

非同步更新

• 為因應這種快速變化的步調，Vertex AI Search 電子商務套件採用非同步的庫存更新，並使用會傳回工作 ID 的 API。
• 系統會輪詢並確認工作狀態，更新程序才算完成，因此可能會出現幾秒到幾分鐘的延遲。

更新順序錯誤

• 這項系統的一大特色是，可在將相應產品匯入目錄前更新庫存資訊。這可解決零售商內部常見的狀況，也就是商品目錄和產品資料管道各自運作，有時會導致商品目錄更新前就提供商品目錄資訊。更新商品目錄時，請使用 allowMissing 選項處理商品目錄與產品更新順序不一致的問題。
• 允許商品目錄更新先於商品目錄擷取，Vertex AI Search for Commerce 即可解決這些管道差異，確保即使是新推出的產品，也能提供準確的商品目錄資料。
• 不過，產品的商品目錄資訊會保留 24 小時，如果在這段時間內沒有匯入相符的產品，系統就會清除這些資訊。這項機制可確保資料一致性，並防止系統中持續存在過時的商品目錄資訊。

商家適用的 Vertex AI Search 產品目錄預檢，可進行穩健的 A/B 測試

本節說明如何對產品目錄資料執行預檢。

確保目錄更新內容一致

• 準備在商家適用的 Vertex AI Search 中進行 A/B 測試時，請務必確保舊版 (控制組) 目錄與商家適用的 Vertex AI Search (測試組) 目錄完全一致。如果兩者之間有任何不平衡，可能會對 A/B 測試造成負面影響，導致觀察結果有偏差，甚至可能無效。舉例來說，產品供應情形、價格不一致，甚至是屬性有微小差異，都可能在測試資料中產生非預期的偏誤。
• 為降低這項風險，請務必為控制和測試目錄設計平行更新程序，盡可能避免循序更新。目標是盡量延長兩個目錄同步的時間。另一方面，連續更新可能會導致其中一個車道延遲。這類延遲可能會導致暫時的目錄不符，也就是一個目錄中的產品有現貨，但另一個目錄中沒有。或者，新加入的產品會先出現在其中一個目錄中。這類差異可能會大幅影響使用者行為、點擊次數和購買次數，最終導致比較不公允，以及 A/B 測試結果不準確。
• 零售商優先進行平行更新，並努力確保目錄一致性，即可在商家適用的 Vertex AI Search 中，確保 A/B 測試的公平性。這種做法可對測試結果進行公正分析，進而獲得更可靠的洞察資料，做出更明智的決策。

確保目錄資料一致

• 電子商務搜尋模型對產品的理解程度和準確度，取決於基礎產品目錄資訊的豐富度和品質。商品目錄中的產品資料越完整，模型就越能有效瞭解及分類產品。
• 因此，準備進行 A/B 測試時，請務必確保上傳至舊版 (控制組) 目錄和 Vertex AI Search for commerce (測試組) 目錄的產品資料完全相同。如果這兩個環境的產品資訊有任何差異，可能會大幅影響 A/B 測試結果。
• 舉例來說，如果相較於 Vertex AI Search for Commerce，舊版搜尋引擎的目錄更豐富或更廣泛，就會造成不公平的優勢。Vertex AI Search for Commerce 目錄中缺少資訊，可能會嚴重影響產品理解和分類，導致搜尋結果不準確，以及成效比較結果誤導。使用外部工具偵測這類差異可能很困難，通常需要仔細手動檢查兩個目錄。
• 零售商只要確保兩個目錄都包含相同詳細程度的產品資料，就能在 Vertex AI Search for commerce 中進行公平的 A/B 測試。這種做法有助於公平公正地比較這兩個搜尋引擎，準確評估各自的效能和功能。

災難復原規劃

完善的災難復原計畫可確保商務搜尋功能維持運作並正常回應，盡量減少對顧客體驗和收益的影響。無論根本原因為何，這項計畫都應能快速還原目錄，以解決目錄和使用者事件擷取管道可能發生的故障。

使用 BigQuery 進行資料暫存，在災難復原方面具有明顯優勢。如果 Vertex AI Search for Retail 目前的目錄或使用者事件資料，與儲存在 BigQuery 中的最新快照差異不大，呼叫匯入 API 即可快速還原。這個方法可將停機時間縮到最短，並確保搜尋功能維持運作。

反之，如果 BigQuery 未整合至資料管道，就必須有替代機制，才能從已知良好狀態快速重新載入目錄。這些機制可能包括備份系統、資料複製或其他容錯移轉策略。

將這些災害復原考量納入商家適用的 Vertex AI Search 架構，有助於提升系統的穩定性，即使發生意外中斷，也能維持業務持續運作。

規劃高可用性

將產品目錄上傳至 Vertex AI Search 時，請務必考量不同 Google Cloud 服務如何處理區域性，以便設計彈性的資料擷取管道。

如要使用 Dataflow 建構具備災害復原能力的擷取管道，請採用下列其中一種設計，在多個區域中部署工作：

• 雙主動式：多個區域中的 Dataflow 執行個體會同時主動處理資料。
• 主動/被動：一個區域中的 Dataflow 執行個體處於主動狀態，其他區域中的執行個體則處於待命狀態。

以下說明如何使用 Pub/Sub 和 Dataflow 實作這些設計：

• 全球服務：部分服務 (例如 Pub/Sub) 在全球運作。 Google Cloud 會根據特定服務水準協議 (SLA) 管理這些服務的可用性。
• 區域服務：其他服務 (例如 Dataflow) 是區域服務，您可能會使用這些服務轉換資料並擷取至 Vertex AI Search。您有責任設定這些元件，確保高可用性和災難復原能力。

舉例來說，如果使用 BigQuery 持續儲存資料，可以將其設為多區域，讓 Google Cloud自動處理資料冗餘和可用性。同樣地，使用 Cloud Storage 時，可以將其設定為多區域。

主動/主動設計

主動/主動設計會使用 Pub/Sub 訊息屬性和訂閱項目篩選器，確保特定區域中的主動 Dataflow 作業只處理每則訊息一次。

1. 新增訊息屬性：將訊息發布至 Pub/Sub 主題時 (例如產品更新)，請加入指出目標區域的屬性。例如：

   • region：us-central1
   • region：us-east1

2. 設定訂閱篩選器：針對每個區域 Dataflow 管道，設定其 Pub/Sub 訂閱項目，只使用訊息篩選器擷取符合該區域的訊息。舉例來說，us-central1 Dataflow 工作的訂閱項目會包含 attributes.region = "us-central1" 這類篩選器。

3. 容錯移轉：如果某個區域無法使用，請更新上游發布系統，為所有新訊息加上健康區域的屬性。這會將訊息處理作業重新導向至容錯移轉區域中的 Dataflow 執行個體。

架構中使用的多個元件可以預設設定為多區域。舉例來說，如果使用 BigQuery 持續儲存資料，可以將其設定為多區域，讓 Cloud Storage 自動處理資料冗餘和可用性。同樣地，使用 Cloud Storage 時，也可以將其設定為多區域。

主動/被動設計

這項設計的目標是確保在任何時間，只有一個區域 Dataflow 管道會主動從 Pub/Sub 提取訊息。

1. 附加一個訂閱項目：請確認只有有效區域的 Dataflow 作業附加 Pub/Sub 訂閱項目，並提取訊息。應建立被動區域中 Dataflow 工作的訂閱項目，但仍保持分離狀態。

2. 容錯移轉：如果主要區域發生故障，請手動或以程式輔助方式執行下列操作：

   • 將與失敗區域的 Dataflow 工作相關聯的 Pub/Sub 訂閱項目分離。
   • 在其中一個被動 (待命) 區域中，附加與 Dataflow 工作相關聯的 Pub/Sub 訂閱項目。

這會將訊息處理負載轉移至新啟用的區域。

復原力和鑑識

在資料擷取設計中使用 BigQuery，可處理復原能力，並建立鑑識和偵錯功能。直接透過 patch 和 addLocalInventory API 擷取的產品和商品目錄，表示資料傳送至 Vertex AI Search for Commerce 時，不會留下任何產品和商品目錄更新的軌跡。使用者可能想知道產品未如預期顯示的原因。使用 BigQuery 建立暫存區並保留完整資料記錄，有助於進行這類調查和偵錯。

參考架構

在這個架構中，資料擷取通常會包含原始、精選和使用階段，全都以 BigQuery 為基礎建構而成。系統會使用 Dataflow 在各階段之間移動資料，並透過雲端工作流程自動執行所有作業：

• 系統會直接採用原始資料，並加上時間標記來保留記錄。這項資料不會變更，因此顧客會將其視為真實來源。
• 接著，系統會將資料轉換為精選階段，並再次加上時間標記。這樣一來，顧客就能知道轉換時間，以及是否發生任何失敗情況。
• 最後，系統會在耗用階段，使用系統稍早為資料加上標記的時間，在精選資料中建立檢視區塊。這樣一來，客戶就能確切瞭解最終應擷取至商家適用的 Vertex AI Search 的轉換資料。

分支 0、分支 1 和分支 2 分別做為即時備份、前一天備份和一週前備份的分支。直接擷取至分支 0 的資料，每天會匯總並編入分支 1 的索引，每週則會編入分支 2 的索引。這樣一來，任何資料損毀情況都能回溯，進而提升業務持續性和系統韌性。

此外，由於全球 BigQuery 資料集會保留完整的資料記錄和沿革，因此可進行分析和偵錯。

規劃目錄擷取作業的特殊情況

建立商家適用的 Vertex AI Search 目錄擷取核心機制後，主動做法是評估這些機制在各種極端情況下的復原能力。雖然其中有些情境可能與您的特定業務需求沒有直接關聯，但將這些情境納入後端設計考量，可為日後提供無價的保障。

這個準備步驟包括檢查資料管道是否能處理非預期或極端情況，確保管道的穩定性，並能適應不斷變化的需求。預先掌握並主動解決潛在問題，有助於減少日後中斷情況，確保產品資料順暢匯入零售搜尋系統。

為達成此目標，請建構 Dataflow 邏輯，確保該邏輯：

• 驗證原始資料的每個項目，是否符合適當的結構定義。應預先決定原始資料的合約，並一律根據合約比對每個資料元素。如果驗證失敗，原始資料元素應加上時間標記，並保留在 BigQuery 失敗的原始資料表中，以供鑑識之用。

  這類失敗的例子包括：

  • 某個不屬於合約的屬性突然出現在原始資料元素中。
  • 原始資料元素中缺少特定必要屬性。

• 驗證原始資料的每個項目，以轉換為 Vertex AI Search for Commerce 格式。商家適用的 Vertex AI Search 規定必須提供部分欄位，才能擷取產品資料。現在應再次檢查原始資料的每個元素，確認是否能成功轉換為 Vertex AI Search for Commerce 結構定義格式。如果轉換失敗，原始資料元素應加上時間標記，並保留在 BigQuery 失敗的精選資料表中，其中包含可協助鑑識的實際錯誤訊息。

  這類失敗的例子包括：

  • 如果原始資料元素是英數字元，價格等特定屬性就無法格式化為數字。
  • 完全沒有產品名稱。

這個範例顯示用於保留所有失敗項目以進行偵錯的 BigQuery 資料表結構定義範例：

[
    {
      "mode": "REQUIRED",
      "name": "ingestedTimestamp",
      "type": "TIMESTAMP"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadString",
      "type": "STRING"
    },
    {
      "mode": "REQUIRED",
      "name": "payloadBytes",
      "type": "BYTES"
    },
    {
      "fields": [
        {
          "mode": "NULLABLE",
          "name": "key",
          "type": "STRING"
        },
        {
          "mode": "NULLABLE",
          "name": "value",
          "type": "STRING"
        }
      ],
      "mode": "REPEATED",
      "name": "attributes",
      "type": "RECORD"
    },
    {
      "mode": "NULLABLE",
      "name": "errorMessage",
      "type": "STRING"
    },
    {
      "mode": "NULLABLE",
      "name": "stacktrace",
      "type": "STRING"
    }
  ]

壓力測試和擴充性

透過壓力測試和可擴充性，為高流量活動和成長做好準備。

高流量活動

節慶等高流量事件對資料擷取管道構成重大挑戰。庫存更新 (包括庫存量和價格) 的激增，以及產品屬性的潛在變更，都需要強大的基礎架構。請務必評估擷取系統是否能處理增加的負載。模擬負載測試 (複製尖峰流量模式) 可找出瓶頸，確保在這些重要期間順暢運作。

快閃促銷

限時特賣活動時間短暫，庫存波動快速，因此會帶來獨特的挑戰。確保即時同步處理商品目錄至關重要，可避免搜尋結果與實際供應情形不一致。如果沒有這麼做，可能會導致熱銷產品實際缺貨卻顯示有貨，或實際有貨卻顯示缺貨，造成負面顧客體驗。此外，特賣期間的價格變動可能會大幅影響產品排名，因此搜尋索引中必須有準確及時的價格更新。

擴展目錄

業務成長或產品線擴展可能會導致目錄中的產品數量大幅增加，例如增加 5 倍或 10 倍。您的擷取架構必須具備擴充性，才能順暢因應這類成長。這可能需要重新檢視整個 ETL (擷取、轉換、載入) 管道，特別是導入新的資料來源或產品資訊格式時。

主動因應這些潛在情境，即使遇到流量突然暴增、快閃特賣或目錄大幅成長的情況，也能確保 Vertex AI Search for Commerce 擷取管道維持穩定、可擴充且反應迅速。這種積極主動的做法可確保搜尋結果的準確度和可靠性，進而提升使用者體驗並帶動業務成長。

應評估資料擷取管道的效能，並為下列指標建立基準：

1. 發布及擷取整個目錄和廣告空間資料需要多久時間？在 BFCM 期間，整個目錄的價格可能會大幅變動，因此可能需要臨時執行這項操作。
2. 單一產品更新需要多久才會反映出來？
3. 系統可處理的產品和商品目錄更新率上限為何？

瓶頸

• 評估並找出管道是否能正確擴大和縮減規模。
• 判斷執行個體數量上限是否過高或過低。
• 檢查 HTTP 程式碼 429，判斷系統是否受到商家適用的 Vertex AI Search 速率限制。
• 確認是否需要提高特定 API 配額，以降低速率限制。

目錄擷取的產品資料結構

本節說明如何準備產品資料，以便匯入目錄。

主要產品

主要產品可做為容器，用來將子類產品分組，並做為搜尋格中的項目。只包含主要產品指定子類共用的屬性。包括：

• 主要產品 ID
• 產品 ID (與主要產品 ID 相同)
• 標題
• 說明

詳情請參閱「關於產品屬性」。

子類產品

子類產品會沿用主要產品的通用屬性，但也可以指定專屬值。

必要屬性包括：

• 主要產品的所有指定屬性 (名稱、說明)。價格、名稱和說明可以與主要產品不同。
• 特定子類屬性 (顏色、尺寸和其他相關產品子類)。

詳情請參閱「關於產品屬性」。

屬性擷取

在擷取過程中，系統會考量主要產品和子類產品的所有可搜尋屬性。

關聯性評分

系統只會根據標題和說明欄位計算關聯性分數。為確保適當區別，請稍微修改主要產品名稱的子類 (例如「產品名稱 + 顏色」)。

搜尋結果中的子類比對

子類比對 (例如「藍色洋裝」) 會根據預先定義的子類屬性 (如顏色和尺寸) 篩選結果。搜尋結果最多會為每個主要產品傳回五個相符子類。

將 Merchant Center 同步至 Vertex AI Search for Commerce

Merchant Center 這項工具可讓你的商店和產品資料用於購物廣告和其他 Google 服務。

如要在 Merchant Center 和商家適用的 Vertex AI Search 之間持續同步處理資料，可以將 Merchant Center 帳戶連結至商家適用的 Vertex AI Search。

設定 Vertex AI Search for Commerce 的 Merchant Center 同步功能時，你必須在 Merchant Center 中獲派管理員 IAM 角色。雖然標準存取權角色允許你讀取 Merchant Center 動態饋給，但嘗試將 Merchant Center 同步至 Vertex AI Search for Commerce 時，會收到錯誤訊息。因此，如要順利將 Merchant Center 同步至 Vertex AI Search for Commerce，請先升級角色。

連結 Merchant Center 帳戶

Vertex AI Search for commerce 連結至 Merchant Center 帳戶後，Merchant Center 帳戶中的產品資料變更，會在幾分鐘內自動更新至 Vertex AI Search for commerce。如要避免 Merchant Center 變更同步至 Vertex AI Search for commerce，可以取消連結 Merchant Center 帳戶。

取消連結 Merchant Center 帳戶不會刪除商家適用的 Vertex AI Search 中的產品。如要刪除匯入的產品，請參閱「刪除產品資訊」。

如要同步處理 Merchant Center 帳戶，請完成下列步驟。

同步處理 Merchant Center 帳戶

如要查看已連結的 Merchant Center，請前往「搜尋商務控制台」資料頁面，然後點按頁面右上方的「Merchant Center」按鈕。系統隨即會開啟「已連結的 Merchant Center 帳戶」面板。你也可以從這個面板新增其他 Merchant Center 帳戶。

如要查看已匯入的產品，請參閱查看目錄的匯總資訊。

列出 Merchant Center 帳戶連結

curl -X GET \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"

取消連結 Merchant Center 帳戶

取消連結 Merchant Center 帳戶後，該帳戶就不會再將目錄資料同步至商家適用的 Vertex AI Search。這項程序不會刪除 Vertex AI Search for Commerce 中已上傳的任何產品。

curl -X DELETE \
 -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
 -H "Content-Type: application/json; charset=utf-8" \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/merchantCenterAccountLinks/BRANCH_ID_MERCHANT_CENTER_ID"

連結至 Merchant Center 的限制

• Merchant Center 帳戶可連結任意數量的目錄分支，但單一目錄分支只能連結至一個 Merchant Center 帳戶。

• Merchant Center 帳戶不得為多重客戶帳戶 (MCA)。不過，您可以連結個別子帳戶。

• 連結 Merchant Center 帳戶後，第一次匯入可能需要數小時才能完成。所需時間取決於 Merchant Center 帳戶中的商品數量。

• 如果分支版本已連結至 Merchant Center 帳戶，就無法使用 API 方法修改產品。如要變更這些分店的產品目錄資料，必須使用 Merchant Center。這些變更會自動同步到 Vertex AI Search for Commerce。

• 使用 Merchant Center 連結的分店不支援集合產品類型。

• 為確保資料準確度，Merchant Center 帳戶只能連結至空白目錄分支。如要從目錄分支刪除產品，請參閱「刪除產品資訊」。

從 BigQuery 匯入目錄資料

如要從 BigQuery 匯入格式正確的目錄資料，請使用 Vertex AI Search for commerce 結構定義建立格式正確的 BigQuery 資料表，然後將目錄資料載入空白資料表。然後將資料上傳至商家適用的 Vertex AI Search。

如需 BigQuery 資料表的更多說明，請參閱資料表簡介。如需 BigQuery 查詢方面的協助，請參閱「查詢 BigQuery 資料總覽」一文。

如要匯入目錄，請按照下列步驟操作：

1. 如果 BigQuery 資料集位於其他專案，請設定必要權限，讓 Vertex AI Search for commerce 存取 BigQuery 資料集。瞭解詳情。

2. 將目錄資料匯入商家適用的 Vertex AI Search。

   Cloud 控制台

   1. 前往「Search for commerce」控制台的「資料」頁面。
      
      前往「資料」頁面
   2. 按一下「匯入」開啟「匯入資料」面板。
   3. 選擇「產品目錄」。
   4. 選取「BigQuery」BigQuery做為資料來源。
   5. 選取要上傳目錄的分支版本。
   6. 選擇「零售產品目錄結構定義」。這是商家適用的 Vertex AI Search 產品結構定義。
   7. 輸入資料所在的 BigQuery 資料表。
   8. 選用：在「顯示進階選項」下方，輸入專案中 Cloud Storage bucket 的位置，做為資料的暫時位置。
      
      如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。
   9. 如果未啟用搜尋功能，且使用 Merchant Center 結構定義，請選取產品層級。
      
      如果這是你第一次匯入目錄，或是清除目錄後重新匯入，就必須選取產品層級。進一步瞭解產品等級。匯入任何資料後，變更產品層級需要付出大量心力。
      
      重要事項：如果產品目錄是以子類的形式擷取，就無法為專案啟用搜尋功能。
   10. 按一下「匯入」。

   curl

   1. 如果這是你第一次上傳目錄，或是清除目錄後重新匯入，請使用 Catalog.patch 方法設定產品層級。這項操作需要零售管理員角色。

      • ingestionProductType：支援 primary (預設值) 和 variant。
      • merchantCenterProductIdField：支援 offerId 和 itemGroupId 值。如果您未使用 Merchant Center，就不必設定這個欄位。

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. 建立匯入作業的輸入參數資料檔案。

      使用 BigQuerySource 物件指向 BigQuery 資料集。

      • DATASET_ID：BigQuery 資料集的 ID。
      • TABLE_ID：儲存資料的 BigQuery 資料表 ID。
      • PROJECT_ID：BigQuery 來源所在的專案 ID。如未指定，專案 ID 會沿用父項要求。
      • STAGING_DIRECTORY：選用。Cloud Storage 目錄，用於在資料匯入 BigQuery 前，做為資料的暫時位置。將這個欄位留空，系統就會自動建立臨時目錄 (建議做法)。
      • ERROR_DIRECTORY：選用。用於匯入作業的 Cloud Storage 目錄，內含錯誤資訊。將這個欄位留空，即可自動建立暫時目錄 (建議)。
      • dataSchema：對於 dataSchema 屬性，請使用 product 值 (預設值)。您將使用商家適用的 Vertex AI Search 架構。

      建議您不要指定暫存或錯誤目錄，這樣系統就能自動建立含有新暫存和錯誤目錄的 Cloud Storage bucket。這些目錄會在與 BigQuery 資料集相同的區域中建立，且每個匯入作業都有專屬目錄 (可避免多個匯入工作將資料暫存至相同目錄，並可能重新匯入相同資料)。為降低儲存空間成本，系統會在三天後自動刪除儲存空間和目錄。

      系統自動建立的值區名稱會包含專案 ID、值區區域和資料結構定義名稱，並以底線分隔 (例如 4321_us_catalog_retail)。自動建立的目錄稱為 staging 或 errors，並附加數字 (例如 staging2345 或 errors5678)。

      如果指定目錄，Cloud Storage bucket 必須與 BigQuery 資料集位於相同區域，否則匯入作業會失敗。以「<暫存目錄>:<錯誤目錄>」格式提供暫存和錯誤目錄，這兩個目錄不得相同。gs://<bucket>/<folder>/

      {
         "inputConfig":{
           "bigQuerySource": {
             "projectId":"PROJECT_ID",
             "datasetId":"DATASET_ID",
             "tableId":"TABLE_ID",
             "dataSchema":"product"}
            }
      }

   3. 如要匯入目錄資訊，請對 Products:import REST 方法發出 POST 要求，並提供資料檔案名稱 (在此顯示為 input.json)。

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      您可以使用 API 透過程式輔助方式檢查狀態。您會收到類似下方的回應物件：

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      名稱欄位是作業物件的 ID。如要要求這個物件的狀態，請將名稱欄位替換為 import 方法傳回的值，直到 done 欄位傳回 true 為止：

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456"

      作業完成後，傳回的物件會包含 true 的 done 值，以及類似下列範例的 Status 物件：

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse",
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      您可以檢查 Cloud Storage 中錯誤目錄的檔案，確認匯入期間是否發生錯誤。

設定 BigQuery 資料集存取權

如果 BigQuery 資料集與 Vertex AI Search for commerce 服務位於不同專案，請完成下列步驟來設定存取權。

1. 在 Google Cloud 控制台中開啟「IAM」頁面。

   開啟「IAM」頁面

2. 選取 Vertex AI Search for Commerce 專案。

3. 找出名稱為「Retail Service Account」的服務帳戶。

   如果先前未啟動匯入作業，這個服務帳戶可能不會列出。如果找不到這個服務帳戶，請返回匯入工作並啟動匯入作業。如果因權限錯誤而失敗，請返回這裡完成這項工作。

4. 複製服務帳戶的 ID，看起來像是電子郵件地址 (例如 service-525@gcp-sa-retail.)。

5. 切換至 BigQuery 專案 (在同一個「IAM 和管理」頁面中)，然後按一下「授予存取權」person_add。

6. 針對「New principals」(新主體)，輸入 Vertex AI Search for commerce 服務帳戶的 ID，並選取「BigQuery」>「BigQuery User」(BigQuery 使用者) 角色。

7. 按一下「新增其他角色」，然後選取「BigQuery」>「BigQuery 資料編輯者」。

   如果不想為整個專案提供資料編輯者角色，可以直接將這個角色新增至資料集。瞭解詳情。

8. 按一下 [儲存]。

產品結構定義

從 BigQuery 匯入目錄時，請使用下列 Vertex AI Search for commerce 產品結構定義建立格式正確的 BigQuery 資料表，並載入目錄資料。然後匯入目錄。

[
  {
    "name": "name",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "id",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "type",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "primaryProductId",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "collectionMemberIds",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "gtin",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "categories",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "title",
    "type": "STRING",
    "mode": "REQUIRED"
  },
  {
    "name": "brands",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "description",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "languageCode",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "attributes",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "key",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "value",
        "type": "RECORD",
        "mode": "NULLABLE",
        "fields": [
          {
            "name": "text",
            "type": "STRING",
            "mode": "REPEATED"
          },
          {
            "name": "numbers",
            "type": "FLOAT",
            "mode": "REPEATED"
          }
        ]
      }
    ]
  },
  {
    "name": "tags",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "priceInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "currencyCode",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "price",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "originalPrice",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "cost",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "priceEffectiveTime",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "priceExpireTime",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "rating",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "ratingCount",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "averageRating",
        "type": "FLOAT",
        "mode": "NULLABLE"
      },
      {
        "name": "ratingHistogram",
        "type": "INTEGER",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "expireTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "ttl",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "seconds",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "nanos",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "availableTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availability",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "availableQuantity",
    "type": "INTEGER",
    "mode": "NULLABLE"
  },
  {
    "name": "fulfillmentInfo",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "type",
        "type": "STRING",
        "mode": "NULLABLE"
      },
      {
        "name": "placeIds",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "uri",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "images",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "uri",
        "type": "STRING",
        "mode": "REQUIRED"
      },
      {
        "name": "height",
        "type": "INTEGER",
        "mode": "NULLABLE"
      },
      {
        "name": "width",
        "type": "INTEGER",
        "mode": "NULLABLE"
      }
    ]
  },
  {
    "name": "audience",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "genders",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "ageGroups",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "colorInfo",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "name": "colorFamilies",
        "type": "STRING",
        "mode": "REPEATED"
      },
      {
        "name": "colors",
        "type": "STRING",
        "mode": "REPEATED"
      }
    ]
  },
  {
    "name": "sizes",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "materials",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "patterns",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "conditions",
    "type": "STRING",
    "mode": "REPEATED"
  },
  {
    "name": "publishTime",
    "type": "STRING",
    "mode": "NULLABLE"
  },
  {
    "name": "promotions",
    "type": "RECORD",
    "mode": "REPEATED",
    "fields": [
      {
        "name": "promotionId",
        "type": "STRING",
        "mode": "NULLABLE"
      }
    ]
  }
]

從 Cloud Storage 匯入目錄資料

如要匯入 JSON 格式的目錄資料，請建立一或多個包含要匯入目錄資料的 JSON 檔案，然後上傳至 Cloud Storage。然後匯入 Vertex AI Search for Commerce。

如需 JSON 產品項目格式範例，請參閱「產品項目 JSON 資料格式」。

如需將檔案上傳至 Cloud Storage 的說明，請參閱上傳物件。

1. 請確認 Vertex AI Search for Commerce 服務帳戶具備讀取及寫入 bucket 的權限。

   Vertex AI Search for Commerce 服務帳戶會列在 Google Cloud 控制台的 IAM 頁面，名稱為「Retail Service Account」(零售服務帳戶)。將帳戶新增至 bucket 權限時，請使用服務帳戶的 ID，看起來像是電子郵件地址 (例如 service-525@gcp-sa-retail.)。

2. 匯入目錄資料。

   Cloud 控制台

   1. 前往「Search for commerce」控制台的「資料」頁面。
      
      前往「資料」頁面
   2. 按一下「匯入」開啟「匯入資料」面板。
   3. 選擇「產品目錄」做為資料來源。
   4. 選取要上傳目錄的分支版本。
   5. 選擇「零售產品目錄結構定義」做為結構定義。
   6. 輸入資料的 Cloud Storage 位置。
   7. 如果未啟用搜尋功能，請選取產品層級。
      
      如果這是你第一次匯入目錄，或是清除目錄後重新匯入，請務必選取產品層級。進一步瞭解產品等級。匯入任何資料後，變更產品層級需要付出大量心力。
      
      重要事項：如果產品目錄是以子類的形式擷取，就無法為專案啟用搜尋功能。
   8. 按一下「匯入」。

   curl

   1. 如果這是你第一次上傳目錄，或是清除目錄後重新匯入，請使用 Catalog.patch 方法設定產品層級。進一步瞭解產品層級。

      • ingestionProductType：支援的值為 primary (預設值) 和 variant。
      • merchantCenterProductIdField：支援 offerId 和 itemGroupId 值。如果您未使用 Merchant Center，就不必設定這個欄位。

      curl -X PATCH \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "productLevelConfig": {
           "ingestionProductType": "PRODUCT_TYPE",
           "merchantCenterProductIdField": "PRODUCT_ID_FIELD"
         }
       }' \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog"

   2. 建立匯入輸入參數的資料檔案。使用 GcsSource 物件指向 Cloud Storage 值區。

      您可以提供多個檔案，也可以只提供一個檔案；這個範例使用兩個檔案。

      • INPUT_FILE：Cloud Storage 中的一或多個檔案，內含目錄資料。
      • ERROR_DIRECTORY：Cloud Storage 目錄，用於存放匯入作業的錯誤資訊。

      輸入檔案欄位的格式必須為「gs://<bucket>/<path-to-file>/」。錯誤目錄的格式必須為 gs://<bucket>/<folder>/。如果錯誤目錄不存在，系統會建立該目錄。 值區必須已存在。

      {
      "inputConfig":{
       "gcsSource": {
         "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"]
        }
      },
      "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
      }

   3. 如要匯入目錄資訊，請對 Products:import REST 方法發出 POST 要求，並提供資料檔案名稱 (在此顯示為 input.json)。

      curl -X POST \
      -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      -H "Content-Type: application/json; charset=utf-8" -d @./input.json \
      "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

      如要查看匯入作業的狀態，最簡單的方法是使用 Google Cloud 控制台。詳情請參閱「查看特定整合作業的狀態」。

      您也可以使用 API 以程式輔助方式檢查狀態。 您會收到類似下方的回應物件：

      {
      "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "done": false
      }

      名稱欄位是作業物件的 ID。您要求這個物件的狀態，並將名稱欄位替換為匯入方法傳回的值，直到 done 欄位傳回 true 為止：

      curl -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
      "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/[OPERATION_NAME]"

      作業完成後，傳回的物件會包含 true 的 done 值，以及類似下列範例的 Status 物件：

      { "name": "projects/PROJECT_ID/locations/global/catalogs/default_catalog/operations/import-products-123456",
      "metadata": {
        "@type": "type.googleapis.com/google.cloud.retail.v2.ImportMetadata",
        "createTime": "2020-01-01T03:33:33.000001Z",
        "updateTime": "2020-01-01T03:34:33.000001Z",
        "successCount": "2",
        "failureCount": "1"
      },
      "done": true,
      "response": {
      "@type": "type.googleapis.com/google.cloud.retail.v2.ImportProductsResponse"
      },
      "errorsConfig": {
        "gcsPrefix": "gs://error-bucket/error-directory"
      }
      }

      您可以檢查 Cloud Storage 中錯誤目錄的檔案，瞭解匯入期間發生的錯誤類型。

透過內嵌方式匯入目錄資料

public static String importProductsFromInlineSource(
    List<Product> productsToImport)
    throws IOException, InterruptedException, ExecutionException {
  ProductServiceClient productClient = getProductServiceClient();

  ProductInlineSource inlineSource = ProductInlineSource.newBuilder()
      .addAllProducts(productsToImport)
      .build();

  ProductInputConfig inputConfig = ProductInputConfig.newBuilder()
      .setProductInlineSource(inlineSource)
      .build();

  ImportProductsRequest importRequest = ImportProductsRequest.newBuilder()
      .setParent(IMPORT_PARENT)
      .setRequestId(REQUEST_ID)
      .setReconciliationMode(ReconciliationMode.INCREMENTAL)
      .setInputConfig(inputConfig)
      .build();

  String operationName = productClient
      .importProductsAsync(importRequest).getName();

  productClient.shutdownNow();
  productClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

產品項目 JSON 資料格式

JSON 檔案中的 Product 項目應與下列範例類似。

請在一行中提供完整產品。每項產品應各占一行。

至少須提供下列欄位：

      {
        "id": "1234",
        "categories": "Apparel & Accessories > Shoes",
        "title": "ABC sneakers"
      }
      {
        "id": "5839",
        "categories": "casual attire > t-shirts",
        "title": "Crew t-shirt"
      }

      {
        "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/1234",
        "id": "1234",
        "categories": "Apparel & Accessories > Shoes",
        "title": "ABC sneakers",
        "description": "Sneakers for the rest of us",
        "attributes": { "vendor": {"text": ["vendor123", "vendor456"]} },
        "language_code": "en",
        "tags": [ "black-friday" ],
        "priceInfo": {
          "currencyCode": "USD", "price":100, "originalPrice":200, "cost": 50
        },
        "availableTime": "2020-01-01T03:33:33.000001Z",
        "availableQuantity": "1",
        "uri":"http://example.com",
        "images": [
          {"uri": "http://example.com/img1", "height": 320, "width": 320 }
        ]
      }
      {
        "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/4567",
        "id": "4567",
        "categories": "casual attire > t-shirts",
        "title": "Crew t-shirt",
        "description": "A casual shirt for a casual day",
        "attributes": { "vendor": {"text": ["vendor789", "vendor321"]} },
        "language_code": "en",
        "tags": [ "black-friday" ],
        "priceInfo": {
          "currencyCode": "USD", "price":50, "originalPrice":60, "cost": 40
        },
        "availableTime": "2020-02-01T04:44:44.000001Z",
        "availableQuantity": "2",
        "uri":"http://example.com",
        "images": [
          {"uri": "http://example.com/img2", "height": 320, "width": 320 }
        ]
      }

歷來目錄資料

商家適用的 Vertex AI Search 支援匯入及管理歷來目錄資料。使用歷來使用者事件訓練模型時，歷來目錄資料會很有幫助。系統可使用過往產品資訊，充實歷來使用者事件資料，進而提升模型準確度。

系統會將歷史產品儲存為過期產品。這些屬性不會在搜尋回應中傳回，但會顯示在 Update、List 和 Delete API 呼叫中。

匯入歷來目錄資料

如果產品的 expireTime 欄位設為過去的時間戳記，該產品就會視為歷史產品。將產品供應情形設為 OUT_OF_STOCK，避免影響建議。

建議使用下列方法匯入歷來目錄資料：

• 呼叫 Product.Create 方法。
• 內嵌匯入過期產品。
• 從 BigQuery 匯入已過期的產品。

呼叫 Product.Create 方法

使用 Product.Create 方法建立 Product 項目，並將 expireTime 欄位設為過去的時間戳記。

內嵌匯入已過期產品

步驟與內嵌匯入相同，但產品的 expireTime 欄位應設為過去的時間戳記。

請在一行中提供完整產品。每項產品應各占一行。

以下是在內嵌匯入要求中使用 ./data.json 的範例：

{
"inputConfig": {
  "productInlineSource": {
      "products": [
          {
            "id": "historical_product_001",
            "categories": "Apparel & Accessories > Shoes",
            "title": "ABC sneakers",
            "expire_time": {
              "second": "2021-10-02T15:01:23Z"  // a past timestamp
            }
          },
          {
            "id": "historical product 002",
            "categories": "casual attire > t-shirts",
            "title": "Crew t-shirt",
            "expire_time": {
              "second": "2021-10-02T15:01:24Z"  // a past timestamp
            }
          }
      ]
    }
  }
}

從 BigQuery 或 Cloud Storage 匯入已過期的產品

請按照從 BigQuery 匯入目錄資料或從 Cloud Storage 匯入目錄資料的相同程序操作。不過，請務必將 expireTime 欄位設為過去的時間戳記。

維持內容新鮮感

為獲得最佳成效，目錄必須包含最新資訊。 建議每天匯入目錄，確保目錄內容為最新狀態。您可以使用 Google Cloud Scheduler 排定匯入作業，或是在使用Google Cloud 控制台匯入資料時，選擇自動排程選項。

你可以只更新新產品或有異動的產品項目，也可以匯入整個目錄。如果匯入的產品已在目錄中，系統不會再次新增。系統會更新所有變更的項目。

如要更新單一項目，請參閱「更新產品資訊」。

批次更新

你可以使用匯入方法，以批次方式更新目錄。方法與初始匯入作業相同，請按照「匯入目錄資料」一文中的步驟操作。

監控匯入健康狀態

如要監控目錄擷取作業和健康狀態：

1. 在「搜尋商務資料」頁面的「目錄」分頁中，查看目錄的匯總資訊，並預覽已上傳的產品。

   前往「資料」頁面

2. 評估是否需要更新目錄資料，以提升搜尋結果品質，並在「資料品質」頁面解鎖搜尋成效等級。

   如要進一步瞭解如何檢查搜尋資料品質及查看搜尋成效等級，請參閱「解鎖搜尋成效等級」。如需本頁面提供的目錄指標摘要，請參閱「目錄品質指標」。

   前往「資料品質」頁面

3. 如要建立快訊，在資料上傳發生問題時通知您，請按照「設定 Cloud Monitoring 快訊」一文中的程序操作。

   請務必隨時更新目錄，確保獲得優質結果。使用快訊監控匯入錯誤率，並視需要採取行動。

後續步驟

• 開始記錄使用者事件。
• 查看目錄的匯總資訊。
• 設定資料上傳快訊。