此页面由 Cloud Translation API 翻译。

导入历史用户事件

本页介绍了如何批量导入过往事件的用户事件数据。媒体推荐需要用户事件。如果您不使用媒体推荐功能，则无需导入用户事件。不过，对于媒体搜索应用，我们建议使用此属性。

如需了解您可以导入的用户事件类型，请参阅 userEvents 对象的 eventType 字段。通过导入用户事件，您可以提高推荐内容的质量以及搜索结果的排名。点击率较高的搜索结果会被提升，而点击率较低的搜索结果会被隐藏。请勿为尚未导入的文档导入用户事件。

如果某个事件包含 userEvents.Documents 中列出的文档，Vertex AI Search 会自动将该事件与该文档联接起来。通过联接，Vertex AI Search 可以将点击和观看等事件归因于搜索结果或推荐中的正确文档。对于常规用例应用，联接是异步进行的，也就是说，用户事件会在批量导入完成后（通常几分钟内）与文档联接。对于媒体应用，联接是同步进行的，Vertex AI Search 会在批量导入仍在进行时开始将用户事件联接到文档。如需了解如何在控制台中查看未联接的事件指标，请参阅查看聚合的用户事件信息。

如需实时导入用户事件，请参阅记录实时用户事件。

您可以通过以下方式导入历史事件：

从 Cloud Storage 加载
从 BigQuery
作为本地 JSON 数据

如需了解用户事件的 JSON 表示法，请参阅 API 参考文档中的 userEvents。

准备工作

在导入用户事件之前，请确保：

创建数据存储区和应用。
如需了解用户事件要求，请参阅用户事件简介。

从 Cloud Storage 导入历史用户事件

如果您有媒体应用，则可以使用 Google Cloud 控制台或 API 导入用户事件。对于其他应用类型，您只能使用 API 进行导入。

控制台

如需使用控制台导入媒体应用的用户事件，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Agent Builder 页面。

Agent Builder
在应用页面上，点击您的媒体应用。
前往数据页面。

对于媒体推荐应用，要求标签页会显示您需要导入的媒体文档和用户事件。
点击事件标签页。如果您已导入任何事件，此标签页上会显示与这些事件相关的信息。
点击导入活动。
选择 Cloud Storage 作为数据源。
输入或选择用户事件的 Cloud Storage 位置。
点击导入。
活动标签页会显示导入状态。
如果发生导入错误，请在活动标签页中执行以下操作：
1. 展开详细信息列中的错误，然后点击查看详情，在活动日志详情窗格中查看更多信息。
2. 在活动日志详情窗格中，点击查看完整错误日志，以在 Logs Explorer 中查看错误。

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 建议将此字段留空，以便 Vertex AI Agent Builder 自动创建临时目录。

向 userEvents:import 方法发出 POST 请求，并提供数据文件的名称，以导入事件。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/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 导入事件

如果您有媒体应用，则可以使用 Google Cloud 控制台或 API 导入用户事件。对于其他类型的应用，您只能使用 API 进行导入。

控制台

如需使用控制台导入媒体应用的用户事件，请按以下步骤操作：

在 Google Cloud 控制台中，前往 Agent Builder 页面。

Agent Builder
在应用页面上，点击您的媒体应用。
前往数据页面。

对于媒体推荐应用，要求标签页会显示您需要导入的媒体文档和用户事件。
点击事件标签页。如果您已导入任何事件，此标签页上会显示与这些事件相关的信息。
点击导入活动。
选择 BigQuery 作为数据源。
输入或选择用户事件的 BigQuery 路径。
点击导入。
活动标签页会显示导入状态。
如果发生导入错误，请在活动标签页中执行以下操作：
1. 展开详细信息列中的错误，然后点击查看详情，在活动日志详情窗格中查看更多信息。
2. 在活动日志详情窗格中，点击查看完整错误日志，以在 Logs Explorer 中查看错误。

REST

如需从 Cloud Storage 批量导入历史用户事件，请按以下步骤操作：

通过向 userEvents:import 方法发出 POST 请求（并提供 BigQuery 项目名称、数据集 ID 和表 ID），导入用户事件。

导入事件时，请使用 dataSchema 的 user_event 值。

export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json

curl \
  -v \
  -X POST \
  -H "Content-Type: application/json; charset=utf-8" \
  -H "Authorization: Bearer "$(gcloud auth print-access-token)"" \
  "https://discoveryengine.googleapis.com/v1beta/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"
      }
    }'

将历史用户事件作为本地 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/v1beta/projects/PROJECT_NUMBER/locations/global/dataStores/DATA_STORE_ID/userEvents:import"