匯入歷來使用者事件

本頁說明如何大量匯入過去事件的使用者事件資料。媒體應用程式需要使用者事件。如果您不使用媒體應用程式，則不需要匯入使用者事件。不過，我們建議您為自訂搜尋和推薦應用程式記錄使用者事件。

如要瞭解可匯入的使用者事件類型，請參閱 userEvents 物件的 eventType 欄位。匯入使用者事件有助於提升結果品質。舉例來說，使用者事件會影響搜尋結果的排名。點閱率較高的結果會獲得提升，點閱率較低的結果則會被埋沒。請勿匯入尚未匯入的文件使用者事件。

如果事件包含 userEvents.Documents 中列出的文件，Vertex AI Search 會自動將事件與該文件彙整。透過彙整，Vertex AI Search 就能將點擊和瀏覽等事件歸因至搜尋結果或推薦內容中的正確文件。對於自訂搜尋和推薦應用程式，系統會非同步進行彙整，也就是說，系統會在批次匯入作業完成後 (通常在幾分鐘內) 將使用者事件彙整至文件。對於媒體應用程式，匯入作業會同步進行，Vertex AI Search 會在批次匯入作業進行期間開始將使用者事件匯入文件。如要瞭解如何在控制台中查看未彙整的事件指標，請參閱「查看匯總的使用者事件資訊」。

如果您使用的是附加多個資料儲存庫的搜尋應用程式，請在位置層級 (而非資料儲存庫層級) 匯入使用者事件。這樣一來，系統就能將特定使用者事件傳送至相關聯的資料儲存庫。如要在位置層級 (而非資料儲存庫層級) 匯入不同 dataStores 的使用者事件文件，請參閱 userEvents.import。

如要即時匯入使用者事件，請參閱「記錄即時使用者事件」。

您可以透過下列方式匯入歷史事件：

如要瞭解使用者事件的 JSON 表示法，請參閱 API 參考資料中的 userEvents。

事前準備

匯入使用者事件前：

從 Cloud Storage 匯入歷史使用者事件

如果您有媒體應用程式，可以使用 Google Cloud 控制台或 API 匯入使用者事件。對於其他類型的應用程式，您只能使用 API 匯入。

主控台

如要使用控制台匯入媒體應用程式的使用者事件，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「AI Applications」頁面。

    AI 應用程式

  2. 在「應用程式」頁面中，按一下媒體應用程式。

  3. 前往「資料」頁面。

    對於媒體推薦應用程式，「需求」分頁會顯示您需要匯入的媒體文件和使用者事件。

  4. 點選「事件」分頁標籤。如果您已匯入任何事件，這個分頁會顯示相關資訊。

  5. 按一下「匯入活動」。

  6. 選取「Cloud Storage」做為資料來源。

  7. 輸入或選取使用者事件的 Cloud Storage 位置。

  8. 按一下「匯入」。

  9. 「活動」分頁會顯示匯入作業狀態。

  10. 如果發生匯入錯誤，請在「活動」分頁中：

    1. 展開「Details」欄中的錯誤，然後按一下「View details」，即可在「Activity log details」窗格中查看更多資訊。

    2. 在「活動記錄詳細資料」窗格中，按一下「查看完整錯誤記錄」，即可在「記錄檔探索工具」中查看錯誤。

REST

如要從 Cloud Storage 大量匯入歷史使用者事件，請按照下列步驟操作：

  1. 建立一或多個資料檔案，用於匯入作業的輸入參數。使用 gcsSource 物件指向 Cloud Storage 值區。

    {
"gcsSource": {
  "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  "dataSchema": "user_event"
  },
  "errorConfig":{
      "gcsPrefix":"ERROR_DIRECTORY"
  }
}

    更改下列內容：

    • INPUT_FILE：Cloud Storage 中的檔案，其中包含使用者事件資料。請確認每個使用者事件各自佔一行，且沒有換行符號。如要瞭解使用者事件的 JSON 表示法，請參閱 API 參考資料中的 userEvents。輸入檔案欄位必須符合下列格式：gs://<bucket>/<path-to-file>/。
    • ERROR_DIRECTORY：選用。用於匯入作業的錯誤資訊的 Cloud Storage 目錄，例如 gs://<your-gcs-bucket>/directory/import_errors。Google 建議您將這個欄位留空，讓 AI 應用程式自動建立暫存資料夾。

  2. 請對 userEvents.import 方法提出 POST 要求，並提供資料檔案名稱，即可匯入事件。

    curl -X POST \
    -v \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
    --data @DATA_FILE.json \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

    如果您要匯入位置層級的使用者事件，請使用端點 https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import。

從 BigQuery 匯入歷史使用者事件

在 BigQuery 中建立使用者事件資料表時，請使用「關於使用者事件」一文中所述的結構定義。

設定 BigQuery 存取權

如果 BigQuery 資料集位於與資料儲存庫不同的專案中，請按照下列步驟設定 BigQuery 存取權。

  1. 在 Google Cloud 控制台中開啟「IAM & Admin」(IAM 與管理) 頁面。
  2. 選取包含要匯入使用者事件的資料儲存庫專案。
  3. 選取「包含 Google 提供的角色授予項目」核取方塊。
  4. 找出名稱為「Discovery Engine Service Account」的服務帳戶。
  5. 如果您先前未透過 Discovery Engine 啟動匯入作業，系統可能不會列出這個服務帳戶。如果找不到這個服務帳戶，請返回匯入工作並啟動匯入作業。如果因權限錯誤而失敗，請返回此處並完成此工作。系統會列出 Discovery Engine 服務帳戶。
  6. 複製服務帳戶的 ID，這個 ID 看起來就像電子郵件地址，例如 service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com。
  7. 切換至 BigQuery 專案 (在同一個「IAM 與管理」頁面中)，然後按一下「授予存取權」。
  8. 針對「New principals」(新原則)，請輸入服務帳戶的 ID，然後選取「BigQuery > BigQuery Data Viewer」(BigQuery > BigQuery Data Viewer) 角色。
  9. 按一下 [儲存]。

如要進一步瞭解 BigQuery 存取權，請參閱 BigQuery 說明文件中的「控管資料集存取權」。

從 BigQuery 匯入事件

如果您有媒體應用程式，可以使用Google Cloud 主控台或 API 匯入使用者事件。如果是其他類型的應用程式，您只能使用 API 匯入。

主控台

如要使用控制台匯入媒體應用程式的使用者事件，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的「AI Applications」頁面。

    AI 應用程式

  2. 在「應用程式」頁面中，按一下媒體應用程式。

  3. 前往「資料」頁面。

    對於媒體推薦應用程式，「需求」分頁會顯示您需要匯入的媒體文件和使用者事件。

  4. 點選「事件」分頁標籤。如果您已匯入任何事件，這個分頁會顯示相關資訊。

  5. 按一下「匯入活動」。

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

  7. 輸入或選取使用者事件的 BigQuery 路徑。

  8. 按一下「匯入」。

  9. 「活動」分頁會顯示匯入作業狀態。

  10. 如果發生匯入錯誤，請在「活動」分頁中：

    1. 展開「Details」欄中的錯誤，然後按一下「View details」，即可在「Activity log details」窗格中查看更多資訊。

    2. 在「活動記錄詳細資料」窗格中，按一下「查看完整錯誤記錄」，即可在「記錄檔探索工具」中查看錯誤。

REST

如要從 Cloud Storage 大量匯入歷史使用者事件，請按照下列步驟操作：

  1. 請向 userEvents.import 方法提出 POST 要求，並提供 BigQuery 專案名稱、資料集 ID 和資料表 ID，即可匯入使用者事件。

    匯入事件時，請將 dataSchema 的值設為 user_event。

    curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1/projects/[PROJECT_NUMBER]/locations/global/dataStores/DATA_STORE_ID/userEvents:import" \
  --data '{
      "bigquerySource": {
          "projectId":"PROJECT_ID",
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID",
          "dataSchema": "user_event"
      }
    }'

    如果您要匯入位置層級的使用者事件，請使用端點 https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import。

將歷史使用者事件匯入為本機 JSON 資料

您可以透過在 userEvents.import 方法的呼叫中加入事件的本機 JSON 資料，匯入使用者事件。

如要將使用者事件資料放入 JSON 檔案，並在 API 要求中指定該檔案，請按照下列操作說明進行：

  1. 建立包含使用者事件資料的 JSON 檔案。如要瞭解使用者事件的 JSON 表示法，請參閱 API 參考資料中的 userEvents。

    {
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_2
      }
    ]
  }
}

  2. 請對 userEvents.import 方法提出 POST 要求，並提供資料檔案名稱，即可匯入事件。

    curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    --data @[JSON_FILE] \
  "https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"

    如果您要匯入位置層級的使用者事件，請使用端點 https://discoveryengine.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/userEvents:import。