导入历史用户事件

本页面介绍了如何将过往事件的用户事件数据批量导入 Vertex AI Search 商务解决方案。训练模型需要用户事件数据。设置实时事件记录后，可能需要相当长的时间记录足够的用户事件数据来训练模型。导入历史数据可以加快此流程。

此页面上的导入过程同时适用于推荐和搜索。导入数据后，这两项服务都可以使用这些事件，因此如果同时使用这两种服务，则无需两次导入相同的数据。

您可以从以下来源导入活动：

• Cloud Storage。
• BigQuery。
• Google Analytics 360 事件的 BigQuery。
• 适用于 Google Analytics 4 事件的 BigQuery。
• 使用 userEvents.import 方法以内嵌方式导入事件。

入门常规提示

• 验证数据是否已从 Google Analytics 4 完全导入到 BigQuery。
• 在控制台中检查导入状态，并参阅调试或错误数据以进行问题排查。
• 在导入历史用户事件数据之前，请查看本页中记录用户事件的最佳实践和准备工作部分。
• 导入历史目录数据可以进一步丰富用户事件并提高模型准确率。

教程

这些教程介绍了如何从各种来源导入用户事件。

从 Cloud Storage 导入事件

本教程介绍如何从 Cloud Storage 导入用户事件。

如需遵循有关此任务的分步指导，请直接在 Cloud Shell Editor 中点击操作演示：

操作演示

从 BigQuery 导入事件

本教程介绍如何从 BigQuery 导入用户事件。

如需遵循有关此任务的分步指导，请直接在 Cloud Shell Editor 中点击操作演示：

操作演示

以内嵌方式导入事件

本教程展示了如何以内嵌方式导入用户事件数据。

如需遵循有关此任务的分步指导，请直接在 Cloud Shell Editor 中点击操作演示：

操作演示

准备工作

为避免导入错误并验证是否有足够的数据来生成良好的结果，请在导入用户事件之前查看以下信息。

• 查看记录用户事件的最佳做法。

• 用户事件格式因用户事件类型而异。如需了解为每种事件类型创建表时要指定的格式，请参阅用户事件类型和示例架构。

• 建议和搜索功能的数据要求不同。确保您的用户事件符合您计划使用的服务的要求：

  • 请参阅用户事件要求和最佳实践，了解搜索和推荐要求。

  • 如果您使用的是推荐模型，另请参阅用户事件数据要求，其中根据您计划使用的推荐模型类型和优化目标列出了其他要求。

事件导入注意事项

本部分介绍了可用于批量导入历史用户事件的方法、何时可以使用每种方法，以及这些方法的一些限制。

从 Cloud Storage 导入用户事件

使用 Google Cloud 控制台或 userEvents.import 方法从 Cloud Storage 导入用户事件。

从 BigQuery 导入用户事件

使用 Google Cloud 控制台或 userEvents.import 方法从 BigQuery 导入用户事件。

设置 BigQuery 访问权限

按照设置对 BigQuery 数据集的访问权限中的说明，为您的 Vertex AI Search for commerce 服务账号授予成功导入所需的最低 BigQuery User 角色，以及 BigQuery 数据集的其他 BigQuery Data Editor 角色。BigQuery Data Owner 角色是不必要的。

从 BigQuery 导入用户事件

您可以使用 Search for Commerce 控制台或 userEvents.import 方法导入用户事件。

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 application-default print-access-token)" \
"https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \
--data '{
  "inputConfig": {
    "bigQuerySource": {
      "datasetId": "DATASET_ID",
      "tableId": "TABLE_ID",
      "dataSchema": "SCHEMA_TYPE"
  }
}
}'

使用 BigQuery 导入 Google Analytics 360 用户事件

如果您已将 Google Analytics 360 与 BigQuery 集成并使用增强型电子商务功能，则可以导入 Google Analytics 360 用户事件。

以下过程假设您熟悉 BigQuery 和 Analytics 360 的使用。

准备工作

在开始后续步骤之前，请确保：

• 您使用的是增强型电子商务。
• 您已将 BigQuery 关联到 Analytics 360。

查看数据源

1. 确保您要导入的用户事件数据在您有权访问的 BigQuery 表中已正确设置了格式。

   确保该表的名称为 project_id:ga360_export_dataset.ga_sessions_YYYYMMDD。

   请参阅 Google Analytics 文档，详细了解该表的格式和命名。

2. 在 BigQuery Google Cloud 控制台中，从探索器面板中选择表以预览表。

   请检查：

   1. clientId 列具有有效值，例如 123456789.123456789。

      请注意，该值与完整的 _ga Cookie 值（格式类似于 GA1.3.123456789.123456789）不同。

   2. hits.transaction.currencyCode 列具有有效的货币代码。

   3. 如果您打算导入 search 事件，请检查 hits.page.searchKeyword 或 hits.customVariable.searchQuery 列是否存在。

      虽然 Vertex AI Search for Commerce 需要同时提供 searchQuery 和 productDetails 才能返回搜索结果列表，但 Analytics 360 不会将搜索查询和商品展示次数同时存储在一个事件中。为了使 Vertex AI Search for Commerce 正常运行，您需要在数据层或 JavaScript Pixel 中创建一个代码，以便能够从 Google Analytics 来源导入以下两种类型的用户事件：

      • searchQuery（从 search_term 参数或 view_search_results 事件中读取）派生自 hits.page.searchKeyword 或 hits.customVariables.customVarValue（如果 hits.customVariables.customVarName 为 searchQuery）。
      • productDetails，即从 view_item_list 事件的 items 参数中读取的产品展示，如果 hits.product.isImpressions 为 TRUE，则从 hits.product 中获取。

3. 检查上传的目录与 Analytics 360 用户事件表之间的项 ID 一致性。

   使用 BigQuery 表预览的 hits.product.productSKU 列中的任意产品 ID 和 product.get 方法，确保您上传的目录中有相同的产品。

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

导入 Analytics 360 事件

您可以使用商业控制台中的“搜索”功能或 userEvents.import 方法导入 Google Analytics 360 事件。

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 application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "datasetId": "some_ga360_export_dataset",
        "tableId": "ga_sessions_YYYYMMDD",
        "dataSchema": "user_event_ga360"
    }
  }
}'

public static String importUserEventsFromBigQuerySource()
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  BigQuerySource bigQuerySource = BigQuerySource.newBuilder()
      .setProjectId(PROJECT_ID)
      .setDatasetId(DATASET_ID)
      .setTableId(TABLE_ID)
      .setDataSchema("user_event")
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setBigQuerySource(bigQuerySource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

使用 BigQuery 导入 Analytics 360 首页浏览

在 Analytics 360 中，首页浏览事件与其他网页浏览事件没有区别。这意味着，首页浏览事件不会像其他事件类型（例如详情页浏览）那样，在导入 Analytics 360 事件中作为事件导入。

以下步骤介绍了如何从 Analytics 360 数据中提取首页浏览事件，并将其导入到 Vertex AI Search 商务解决方案中。简而言之，此过程包括将用户对首页（由首页路径标识）的浏览情况提取到新的 BigQuery 表中，然后将该表中的数据导入到 Vertex AI Search for commerce 中。

如需将首页浏览事件从 Analytics 360 导入到 Vertex AI Search 商务解决方案，请执行以下操作：

1. 创建 BigQuery 数据集，或确保您有一个可向其中添加表的 BigQuery 数据集。

   此数据集可以位于 Vertex AI Search 商务解决方案项目中，也可以位于包含 Analytics 360 数据的项目中。这是您要将 Analytics 360 首页查看事件复制到的目标数据集。

2. 在数据集中创建 BigQuery 表，如下所示：

   1. 将以下 SQL 代码中的变量替换为以下内容。

      • target_project_id:：第 1 步中的数据集所在的项目。

      • target_dataset:：第 1 步中的数据集名称。

      CREATE TABLE TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage (
       eventType STRING NOT NULL,
       visitorId STRING NOT NULL,
       userId STRING,
       eventTime STRING NOT NULL
      );

   2. 复制 SQL 代码示例。

   3. 在 Google Cloud 控制台中打开 BigQuery 页面。

      转到 BigQuery 页面

   4. 如果尚未选择，请选择目标项目。

   5. 在编辑器窗格中，粘贴 SQL 代码示例。

   6. 点击 play_circle Run（运行），然后等待查询完成运行。

   运行此代码会创建一个格式为 target_project_id:target_dataset.ga_homepage_YYYYMMDD 的表，例如 my-project:view_events.ga_homepage_20230115。

3. 将 Analytics 360 数据表中的 Analytics 360 首页浏览事件复制到上一步 2 中创建的表中。

   1. 将以下 SQL 示例代码中的变量替换为以下值：

      • source_project_id:：包含 BigQuery 表格中的 Analytics 360 数据的项目的 ID。

      • source_dataset:：源项目中包含 BigQuery 表中的 Analytics 360 数据的数据集。

      • source_table:：源项目中包含 Analytics 360 数据的表。

      • target_project_id:：与上一步（第 2 步）中的目标项目 ID 相同。

      • target_dataset:：与上一步（步骤 2）中的目标数据集相同。

      • path：这是首页的路径。通常，此值为 /，例如，如果首页为 example.com/。不过，如果首页类似于 examplepetstore.com/index.html，则路径为 /index.html。

      INSERT INTO `TARGET_PROJECT_ID.TARGET_DATASET.ga_homepage(eventType,visitorId,userID,eventTime)`
      
      SELECT
        "home-page-view" as eventType,
        clientId as visitorId,
        userId,
        CAST(FORMAT_TIMESTAMP("%Y-%m-%dT%H:%M:%SZ",TIMESTAMP_SECONDS(visitStartTime)) as STRING) AS eventTime
      
      FROM
        `SOURCE_PROJECT_ID.SOURCE_DATASET.SOURCE_TABLE`, UNNEST(hits) as hits
      
      WHERE hits.page.pagePath = "PATH" AND visitorId is NOT NULL;

   2. 复制 SQL 代码示例。

   3. 在 Google Cloud 控制台中打开 BigQuery 页面。

      转到 BigQuery 页面

   4. 如果尚未选择，请选择目标项目。

   5. 在编辑器窗格中，粘贴 SQL 代码示例。

   6. 点击 play_circle Run（运行），然后等待查询完成运行。

4. 按照从 BigQuery 导入用户事件中的说明，从目标表中导入主页浏览事件。在选择架构期间，如果您使用控制台导入，请选择零售用户事件架构；如果您使用 userEvents.import 导入，请为 dataSchema 值指定 user_event。

5. 删除您在第 1 步和第 2 步中创建的表和数据集。

使用 BigQuery 导入 Google Analytics 4 用户事件

如果您已将 Google Analytics 4 与 BigQuery 集成并使用 Google Analytics 电子商务，则可以导入 Google Analytics 4 用户事件。

以下过程假设您熟悉 BigQuery 和 Google Analytics 4 的使用。

准备工作

在开始后续步骤之前，请确保：

• 您使用的是 Google Analytics 电子商务。
• 您已将 BigQuery 关联到 Google Analytics 4。

查看数据源

为确保用户事件数据已准备好可供导入，请按以下步骤操作。

如需查看 Vertex AI Search for Commerce 使用的 Google Analytics 4 字段以及这些字段映射到的 Vertex AI Search for Commerce 字段，请参阅 Google Analytics 4 用户事件字段。

如需查看所有 Google Analytics 事件参数，请参阅 Google Analytics 事件参考文档。

1. 确保您要导入的用户事件数据在您有权访问的 BigQuery 表中已正确设置了格式。

   • 数据集应命名为 analytics_PROPERTY_ID。
   • 该表应命名为 events_YYYYMMDD。

   如需了解表名称和格式，请参阅 Google Analytics 文档。

2. 在 BigQuery Google Cloud 控制台中，从探索器面板中选择数据集，然后找到您计划导入的用户事件表。

   请检查：

   1. event_params.key 列具有 currency 键，并且其关联的字符串值是有效的币种代码。

   2. 如果您打算导入 search 事件，请检查 event.event_params.key 列是否具有 search_term 键和关联的值。

      虽然 Vertex AI Search for commerce 需要同时提供 searchQuery 和 productDetails 才能返回搜索结果列表，但 Google Analytics 4 不会将搜索查询和产品展示次数同时存储在一个事件中。为了使 Vertex AI Search for Commerce 正常运行，您需要在数据层或通过 JavaScript Pixel 创建代码，以便能够从 Google Analytics 来源导入以下两种类型的用户事件：

      • searchQuery，该值从 search_term 参数或 view_search_results 事件中读取。
      • productDetails，即从 view_item_list 事件的 items 参数中读取的产品展示。

      如需了解 Google Analytics 4 中的 search，请参阅 Google Analytics 文档中的 search。

3. 检查上传的目录与 Google Analytics 4 用户事件表之间的商品 ID 一致性。

   为确保 Google Analytics 4 用户表中的产品也位于您上传的目录中，请从 BigQuery 表预览的 event.items.item_id 列中复制一个产品 ID，然后使用 product.get 方法检查该产品 ID 是否位于您上传的目录中。

   export GOOGLE_APPLICATION_CREDENTIALS=/tmp/my-key.json
   
      curl \
        -v \
        -X GET \
        -H "Content-Type: application/json; charset=utf-8" \
        -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
        "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/default_branch/products/PRODUCT_ID"

导入 Google Analytics 4 事件

您可以使用商业控制台中的“搜索”功能或 userEvents.import 方法导入 Google Analytics 4 事件。

使用控制台

1. 在 Search for Commerce 控制台中，前往数据页面。
   
   前往“数据”页面
2. 点击导入以打开导入数据面板。
3. 选择用户事件。
4. 选择 BigQuery 作为数据源。

5. 选择数据架构。

   • Google Analytics 4：用于 Google Analytics 4 事件。
   • Google Analytics 360：用于 Google Analytics 360 事件，除非您仅从 Google Analytics 360 导入首页浏览事件（在这种情况下，请使用零售用户事件架构）。
   • 零售用户事件架构：用于从 Google Analytics 以外的来源导入事件，以及仅从 Google Analytics 360 导入首页浏览事件。
6. 输入数据所在的 BigQuery 表格。
7. 可选：输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。
   如果未指定，系统会使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
8. 可选：在显示高级选项下，输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。
   
   如果未指定，则使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
9. 点击导入。

使用 API

通过在调用 userEvents.import 方法时添加事件数据，导入用户事件。请参阅 userEvents.import API 参考文档。

对于 dataSchema，请使用值 user_event_ga4。

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 application-default print-access-token)" \\
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import" \\
  --data '{
    "inputConfig": {
      "bigQuerySource": {
        "projectId": "PROJECT_ID",
        "datasetId": "DATASET_ID",
        "tableId": "TABLE_ID",
        "dataSchema": "user_event_ga4"
    }
  }
}'

以内嵌方式导入用户事件

您可以通过在 userEvents.import 方法的调用中包含事件的数据来以内嵌方式导入用户事件。

最简单的方法是将用户事件数据放入 JSON 文件并将该文件提供给 curl。

如需了解用户事件类型的格式，请参阅关于用户事件。

public static String importUserEventsFromInlineSource(
    List<UserEvent> userEventsToImport)
    throws IOException, InterruptedException, ExecutionException {
  UserEventServiceClient userEventsClient = getUserEventServiceClient();

  UserEventInlineSource inlineSource = UserEventInlineSource.newBuilder()
      .addAllUserEvents(userEventsToImport)
      .build();

  UserEventInputConfig inputConfig = UserEventInputConfig.newBuilder()
      .setUserEventInlineSource(inlineSource)
      .build();

  ImportUserEventsRequest importRequest = ImportUserEventsRequest.newBuilder()
      .setParent(DEFAULT_CATALOG_NAME)
      .setInputConfig(inputConfig)
      .build();

  String operationName = userEventsClient
      .importUserEventsAsync(importRequest).getName();

  userEventsClient.shutdownNow();
  userEventsClient.awaitTermination(2, TimeUnit.SECONDS);

  return operationName;
}

历史目录数据

您还可以导入历史用户事件中显示的目录数据。此目录数据非常有用，因为过去的产品信息可用于丰富用户事件捕获，从而提高模型准确率。

如需了解详情，请参阅导入历史目录数据。

查看导入的活动

在 Search for Commerce 控制台数据页面的事件标签页中查看事件集成指标。此页面显示去年写入或导入的所有事件。成功数据注入后，指标最多可能需要 24 小时才会显示。

前往“数据”页面

后续步骤

• 开始记录用户事件。
• 管理用户事件。