此页面由 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 存储桶。
```
{
"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 和管理页面。
选择要向其中导入用户事件的数据存储区所在的项目。
选中包括 Google 提供的角色授权复选框。
找到名为 Discovery Engine Service Account 的服务账号。
如果您之前未曾使用 Discovery Engine 发起导入操作，则此服务账号可能不会被列出。如果您没有看到此服务账号，请返回导入任务并发起导入。当导入因权限错误而失败时，请返回此处并完成此任务。Discovery Engine 服务账号将被列出。
复制服务账号的标识符，类似于邮箱，例如 service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com。
切换到您的 BigQuery 项目（在同一 IAM 和管理页面上），然后点击授予访问权限。
在新的主账号部分，输入服务账号的标识符，然后依次选择 BigQuery > BigQuery Data Viewer 角色。
点击保存。

如需详细了解 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。