匯入歷來使用者事件

本頁說明如何大量匯入過去活動的使用者事件資料。媒體應用程式必須提供使用者事件。如果您不使用媒體應用程式，就不需要匯入使用者事件。不過，建議自訂搜尋和推薦應用程式記錄使用者事件。

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

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

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

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

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

• 從 Cloud Storage
• 從 BigQuery
• 以本機 JSON 資料的形式

如要瞭解使用者事件的 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. 展開「詳細資料」欄中的錯誤，然後按一下「查看詳細資料」，即可在「活動記錄詳細資料」窗格中查看更多資訊。

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

REST

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

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

   {
   "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，看起來像是電子郵件地址，例如 [e-mail]。
7. 切換至 BigQuery 專案 (在同一個「IAM 和管理」頁面)，然後按一下「授予存取權」。
8. 在「New principals」(新主體) 中，輸入服務帳戶的 ID，然後選取「BigQuery」>「BigQuery Data Viewer」(BigQuery 資料檢視者) 角色。
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. 展開「詳細資料」欄中的錯誤，然後按一下「查看詳細資料」，即可在「活動記錄詳細資料」窗格中查看更多資訊。

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

REST

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

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

   匯入事件時，請使用 user_event 做為 dataSchema 的值。

   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。