导入历史用户事件

本页面介绍了如何从过往活动中批量导入用户事件数据。用户 事件是必填项。如果您不使用媒体内容 因此不需要导入用户事件。不过，对于媒体搜索应用，我们建议使用此属性。

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

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

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

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

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

准备工作

在导入用户事件之前，请执行以下操作：

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

从 Cloud Storage 导入历史用户事件

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

控制台

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

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

    Agent Builder

  2. 在应用页面上，点击您的媒体应用。

  3. 前往数据页面。

    对于媒体推荐应用，要求标签页会显示您需要导入的媒体文档和用户事件。

  4. 点击事件标签页。如果您已导入任何事件，此标签页上会显示与这些事件相关的信息。

  5. 点击导入活动。

  6. 选择 Cloud Storage 作为数据源。

  7. 输入或选择用户事件的 Cloud Storage 位置。

  8. 点击导入。

  9. 活动标签页会显示导入状态。

  10. 如果发生导入错误，请在活动标签页中执行以下操作：

    1. 展开详细信息列中的错误，然后点击查看详细信息以 如需了解详情，请参阅活动日志详细信息窗格。

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

  2. 向 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 的访问权限。

  1. 在 Google Cloud 控制台中打开 IAM 和管理页面。
  2. 选择包含您要导入用户的数据存储区的项目 事件转换为
  3. 选中包括 Google 提供的角色授权复选框。
  4. 找到名为 Discovery Engine Service Account 的服务账号。
  5. 如果您之前没有使用 Discovery Engine，可能未列出此服务账号。如果您 未找到此服务账号，请返回导入任务，并启动 导入。当由于权限错误而失败时，请返回此处完成此任务。系统将列出 Discovery Engine 服务账号。
  6. 复制服务账号的标识符（类似于电子邮件） 地址，例如 service-525@gcp-sa-discoveryengine.iam.gserviceaccount.com。
  7. 切换到您的 BigQuery 项目（在 IAM 和管理的同一个页面上） 然后点击授予访问权限。
  8. 在新的主账号部分，输入服务账号的标识符，然后 选择 BigQuery >BigQuery Data Viewer 角色。
  9. 点击保存。

如需详细了解 BigQuery 访问权限，请参阅 BigQuery 文档中的控制对数据集的访问权限。

从 BigQuery 导入事件

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

控制台

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

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

    Agent Builder

  2. 在应用页面上，点击您的媒体应用。

  3. 前往数据页面。

    对于媒体推荐应用，要求标签页会显示您需要导入的媒体文档和用户事件。

  4. 点击事件标签页。如果您已导入任何事件，此标签页上会显示与这些事件相关的信息。

  5. 点击导入活动。

  6. 选择 BigQuery 作为数据源。

  7. 输入或选择用户事件的 BigQuery 路径。

  8. 点击导入。

  9. 活动标签页会显示导入状态。

  10. 如果发生导入错误，请在活动标签页中执行以下操作：

    1. 展开详细信息列中的错误，然后点击查看详细信息以 如需了解详情，请参阅活动日志详细信息窗格。

    2. 在活动日志详细信息窗格中，点击查看完整的错误日志以 在日志浏览器中查看错误。

REST

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

  1. 通过向 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 文件并在 API 请求中指定该文件，请执行以下操作： 请按照以下说明操作：

  1. 创建一个包含用户事件数据的 JSON 文件。对于 JSON 表示用户事件，请参阅 userEvents 。

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

  2. 通过向 userEvents:import 方法，从而提供 数据文件。

    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"