匯入目錄資訊

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

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

教學課程影片

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

從 BigQuery 匯入目錄資料

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

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

從 Cloud Storage 匯入目錄資料

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

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

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

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

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

事前準備

如要匯入目錄資訊，請務必先完成「事前準備」中的操作說明，特別是設定專案、建立服務帳戶，以及將服務帳戶新增至本機環境。

您必須具備「Retail 管理員」身分與存取權管理角色，才能執行匯入作業。

目錄匯入最佳做法

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

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

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

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

    • 舉例來說，如果主要 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 自動匯入資料。

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

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

關於匯入目錄資料

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

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

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

目錄匯入注意事項

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

BigQuery 說明 從先前載入的 BigQuery 資料表匯入資料，該資料表使用 Vertex AI Search for Commerce 結構定義或 Merchant Center 結構定義。可使用 Google Cloud 控制台或 curl 執行。
使用時機 如果產品目錄包含許多屬性，BigQuery 匯入作業會使用 Vertex AI Search for commerce 結構定義，相較於其他匯入選項，這個結構定義有更多產品屬性，包括鍵/值自訂屬性。

如果您有大量資料，BigQuery 匯入作業沒有資料限制。

如果您已使用 BigQuery。
限制 需要額外步驟，建立對應至商家適用的 Vertex AI Search 結構定義的 BigQuery 資料表。
Cloud Storage 說明 從 Cloud Storage bucket 中載入的檔案匯入 JSON 格式的資料。每個檔案的大小不得超過 2 GB，一次最多可匯入 100 個檔案。您可以使用 Google Cloud 控制台或 curl 匯入。使用 Product JSON 資料格式，可自訂屬性。
使用時機 如需透過單一步驟載入大量資料。
限制 不適合經常更新商品目錄和價格的商家，因為變更不會立即反映。
內嵌匯入 說明 透過呼叫 Product.import 方法匯入。使用 ProductInlineSource 物件，這個物件的產品目錄屬性比 Vertex AI Search for commerce 架構少，但支援自訂屬性。
使用時機 如果目錄資料是平面非關聯式，或是數量或價格更新頻率很高。
限制 一次最多只能匯入 100 個目錄項目。不過，您可以執行許多載入步驟，且沒有項目限制。

目錄擷取的產品資料結構

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

主要產品

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

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

子類產品

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

必要屬性包括：

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

屬性擷取

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

關聯性評分

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

搜尋結果中的變體比對

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

清除目錄分支版本

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

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

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

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

    前往「資料」頁面

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

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

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

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

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

將 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，請先升級角色。

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

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

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

同步處理 Merchant Center 帳戶

Cloud 控制台

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

    前往「資料」頁面
  2. 按一下「匯入」開啟「匯入資料」面板。
  3. 選擇「產品目錄」。
  4. 選取「Merchant Center 同步」做為資料來源。
  5. 選取 Merchant Center 帳戶。如果沒有看到帳戶，請檢查「使用者存取權」。
  6. 選用：選取「Merchant Center 動態饋給篩選器」，只匯入所選動態饋給的商品。

    如未指定，系統會匯入所有動態饋給的商品 (包括日後新增的動態饋給)。
  7. 選用：如要只匯入指定國家/地區或語言的商品，請展開「顯示進階選項」，然後選取要篩選的 Merchant Center 銷售國家/地區和語言。
  8. 選取要上傳目錄的分支版本。
  9. 按一下「匯入」。

curl

  1. 確認本機環境中的服務帳戶有權存取 Merchant Center 帳戶和 Vertex AI Search for commerce。如要查看哪些帳戶有權存取你的 Merchant Center 帳戶，請參閱「Merchant Center 的使用者存取權」。

  2. 請使用 MerchantCenterAccountLink.create 方法建立連結。

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
 --data '{
  "merchantCenterAccountId": MERCHANT_CENTER_ID,
  "branchId": "BRANCH_ID",
  "feedFilters": [
    {"dataSourceId": DATA_SOURCE_ID_1}
    {"dataSourceId": DATA_SOURCE_ID_2}
  ],
  "languageCode": "LANGUAGE_CODE",
  "feedLabel": "FEED_LABEL",
 }' \
 "https://retail.googleapis.com/v2alpha/projects/PROJECT_ID/locations/global/catalogs/default_catalog/merchantCenterAccountLinks"
    • MERCHANT_CENTER_ID：Merchant Center 帳戶的 ID。
    • BRANCH_ID：要建立連結的分支 ID。可接受的值為「0」、「1」或「2」。
    • LANGUAGE_CODE：(選用) 要匯入產品的雙字母語言代碼。如 Merchant Center 中產品的 Language 欄所示。如未設定，系統會匯入所有語言。
    • FEED_LABEL：(選用) 要匯入產品的動態饋給標籤。你可以在 Merchant Center 的產品「動態饋給標籤」欄中查看動態饋給標籤。如未設定，系統會匯入所有動態饋給標籤。
    • FEED_FILTERS：(選用) 產品匯入來源的主要動態饋給清單。如未選取動態饋給，系統會共用所有 Merchant Center 帳戶動態饋給。你可以在 Content API 資料動態饋給資源中找到 ID，也可以前往 Merchant Center，選取動態饋給，然後從網站網址的 afmDataSourceId 參數取得動態饋給 ID。例如：mc/products/sources/detail?a=MERCHANT_CENTER_ID&afmDataSourceId=DATA_SOURCE_ID。

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

如要查看已匯入的產品，請參閱「查看目錄的匯總資訊」一文中的操作說明。

Cloud 控制台

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

    前往「資料」頁面

  2. 按一下頁面右上方的「Merchant Center」按鈕，開啟已連結的 Merchant Center 帳戶清單。

curl

使用 MerchantCenterAccountLink.list 方法列出連結資源。

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 帳戶後，該帳戶就不會再將目錄資料同步至商家適用的 Vertex AI Search。這項程序不會刪除 Vertex AI Search for Commerce 中已上傳的任何產品。

Cloud 控制台

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

    前往「資料」頁面

  2. 按一下頁面右上方的「Merchant Center」按鈕，開啟已連結的 Merchant Center 帳戶清單。

  3. 找到要取消連結的 Merchant Center 帳戶，然後按一下旁邊的「取消連結」，並在隨即顯示的對話方塊中確認。

curl

使用 MerchantCenterAccountLink.delete 方法移除 MerchantCenterAccountLink 資源。

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 帳戶只能連結至空白目錄分支。如要從目錄分支刪除產品，請參閱「刪除產品資訊」。

從 Merchant Center 匯入目錄資料

你可以使用 Merchant Center 結構定義，從 BigQuery 大量匯入 Merchant Center 的目錄資料 (僅限建議)。

從 Merchant Center 大量匯入

你可以使用「搜尋商務控制台」或 products.import 方法，從 Merchant Center 匯入目錄資料。大量匯入是單次程序，且僅支援建議。

如要從 Merchant Center 匯入目錄，請完成下列步驟：

  1. 按照「Merchant Center 移轉作業」一文中的操作說明，設定從 Merchant Center 移轉至 BigQuery 的作業。

    您將使用 Google Merchant Center 產品資料表結構定義。將移轉作業設為每天重複執行，但將資料集到期時間設為 2 天。

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

  3. 將目錄資料從 BigQuery 匯入 Vertex AI Search for commerce。

    Cloud 控制台

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

      前往「資料」頁面

    2. 按一下「匯入」開啟「匯入」面板。

    3. 選擇「產品目錄」。

    4. 選取「BigQuery」BigQuery做為資料來源。

    5. 選取要上傳目錄的分支版本。

    6. 在資料架構欄位選取「Merchant Center」。

    7. 輸入資料所在的 BigQuery 資料表。

    8. 選用：在專案中輸入 Cloud Storage bucket 的位置，做為資料的暫時位置。

      如未指定，系統會使用預設位置。您指定的 BigQuery 和 Cloud Storage 值區必須位於同一區域。

    9. 選擇是否要排定定期上傳目錄資料。

    10. 如果這是你第一次匯入目錄，或是清除目錄後重新匯入，請選取產品層級。進一步瞭解產品等級。

      匯入任何資料後，變更產品層級設定需要投入大量心力。

    11. 按一下「匯入」。

    curl

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

      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. 使用 Products.import 方法匯入目錄。

      • DATASET_ID：BigQuery 資料集的 ID。
      • TABLE_ID：儲存資料的 BigQuery 資料表 ID。
      • STAGING_DIRECTORY：選用。Cloud Storage 目錄，用於在資料匯入 BigQuery 前，做為資料的暫時位置。將這個欄位留空，系統就會自動建立臨時目錄 (建議做法)。
      • ERROR_DIRECTORY：選用。用於匯入作業的 Cloud Storage 目錄，內含錯誤資訊。將這個欄位留空，即可自動建立暫時目錄 (建議)。
      • dataSchema：針對 dataSchema 屬性，請使用值 product_merchant_center。請參閱 Merchant Center 產品資料表結構定義。

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

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

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

      curl -X POST \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       -H "Content-Type: application/json; charset=utf-8" \
       --data '{
         "inputConfig":{
            "bigQuerySource": {
              "datasetId":"DATASET_ID",
              "tableId":"TABLE_ID",
              "dataSchema":"product_merchant_center"
            }
          }
      }' \
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products:import"

從 BigQuery 匯入目錄資料

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

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

如要直接在 Cloud Shell 編輯器中按照逐步指南操作，請按一下「Guide me」(逐步引導)：

逐步引導

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

  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 方法設定產品層級。這項操作需要零售管理員角色。

      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 會沿用父項要求的專案 ID。
      • STAGING_DIRECTORY：選用。Cloud Storage 目錄，用於在資料匯入 BigQuery 前，做為資料的暫時位置。將這個欄位留空，系統就會自動建立臨時目錄 (建議做法)。
      • ERROR_DIRECTORY：選用。用於匯入作業的 Cloud Storage 目錄，內含錯誤資訊。將這個欄位留空，即可自動建立暫時目錄 (建議)。
      • dataSchema：對於 dataSchema 屬性，請使用 product 值 (預設值)。您將使用商家適用的 Vertex AI Search 結構定義。

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

      系統自動建立的值區名稱會包含專案 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.iam.gserviceaccount.com)。

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

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

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

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

  8. 按一下 [儲存]。

從 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.iam.gserviceaccount.com)。

  2. 匯入目錄資料。

    Cloud 控制台

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

      前往「資料」頁面
    2. 按一下「匯入」開啟「匯入資料」面板。
    3. 選擇「產品目錄」做為資料來源。
    4. 選取要上傳目錄的分支版本。
    5. 選擇「零售產品目錄結構定義」做為結構定義。
    6. 輸入資料的 Cloud Storage 位置。
    7. 如果未啟用搜尋功能，請選取產品層級。

      如果這是你第一次匯入目錄，或是清除目錄後重新匯入，請務必選取產品層級。進一步瞭解產品等級。匯入任何資料後，變更產品層級需要付出大量心力。

      重要事項：如果產品目錄是以子類的形式擷取，就無法為專案啟用搜尋功能。
    8. 按一下「匯入」。

    curl

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

      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 中錯誤目錄的檔案，瞭解匯入期間發生的錯誤類型。

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

curl

您可透過對 Products:import REST 方法發出 POST 要求，並使用 productInlineSource 物件指定目錄資料，內嵌匯入目錄資訊。

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

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

  1. 為產品建立 JSON 檔案，並命名為 ./data.json：
{
"inputConfig": {
  "productInlineSource": {
      "products": [
        { PRODUCT_1 }
        { PRODUCT_2 }
      ]
    }
  }
}

  1. 呼叫 POST 方法：

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

Java

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 方法

使用 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 快訊」一文中的程序操作。

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

後續步驟