本頁面由 Cloud Translation API 翻譯而成。

匯入歷來的使用者事件

本頁說明如何大量匯入過去事件的使用者事件資料。

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

如果活動在 userEvents.Documents 中列出文件，Gemini Enterprise 就會自動加入含有該文件的活動。加入後，Gemini Enterprise 就能將點擊和觀看等事件歸因給搜尋結果或建議中的正確文件。如果是自訂搜尋和推薦應用程式，則會非同步加入，也就是在批次匯入完成後，使用者事件才會加入文件 (通常會在幾分鐘內完成)。

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

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

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

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

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

事前準備

匯入使用者事件前的注意事項：

建立資料儲存庫和應用程式。
如要瞭解使用者事件規定，請參閱「關於使用者事件」。

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

REST

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

為匯入作業的輸入參數建立一或多個資料檔案。使用 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 建議將這個欄位留空，讓 Gemini Enterprise 自動建立臨時目錄。

對 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 的存取權。

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

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

從 BigQuery 匯入事件

REST

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

如要匯入使用者事件，請對 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 要求中指定該檔案，請按照下列操作說明進行：

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

{
  "inlineSource": {
    "userEvents": [
      {
        USER_EVENT_1
      },
      {
        USER_EVENT_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。