导入历史用户事件

本页面介绍如何批量导入过往事件的用户事件数据。Vertex AI Search for Retail 模型需要用户事件数据进行训练。

设置实时事件记录后，可能需要相当长的时间记录足够的用户事件数据来训练模型。您可以通过从过去的事件中批量导入用户事件数据来加速初始模型训练。在此之前，请查看本页中记录用户事件的最佳做法和准备工作部分。

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

您可以：

教程：从 Cloud Storage 导入事件

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

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

操作演示

教程：从 BigQuery 导入事件

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

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

操作演示

教程：以内嵌方式导入事件

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

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

操作演示

准备工作

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

事件导入注意事项

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

Cloud Storage 说明 从加载到 Cloud Storage 存储桶中的文件导入 JSON 格式的数据。每个文件不得超过 2 GB，一次最多可导入 100 个文件。可以使用 Google Cloud 控制台或 c网址 完成导入操作。使用 Product JSON 数据格式，该格式允许自定义属性。
使用时间 您需要在单个步骤中加载大量数据时。
限制 如果您的数据位于 Google Analytics 或 Merchant Center 中，则您只能将数据导出到 BigQuery，还需要额外执行将数据导入到 Cloud Storage 这一步骤。
BigQuery 说明 从使用 Vertex AI Search for Retail 架构的先前加载的 BigQuery 表中导入数据。可以使用 Google Cloud 控制台或 c网址 执行。
使用时间 在您还使用分析或预处理事件数据，然后再将其导入时。
局限性 需要额外执行创建映射到 Vertex AI Search for Retail 架构的 BigQuery 表这一步骤。如果您有大量用户事件，另请考虑 BigQuery 的费用高于 Cloud Storage。
BigQuery 和 Analytics 360 说明 将预先存在的数据从 Analytics 360 导入 Vertex AI Search 零售解决方案。
使用时间 您使用 Google Analytics 360，并跟踪推荐或搜索的转化情况时。无需其他架构映射。
局限性 只有一部分属性可用，因此某些高级 Vertex AI Search for Retail 功能无法使用。如果您计划使用搜索广告系列，则需要在 Google Analytics 中跟踪展示次数。
BigQuery 和 Google Analytics 4 说明 将预先存在的数据从 Google Analytics 4 导入 Vertex AI Search 零售解决方案。
使用时间 您使用 Google Analytics 4，并跟踪推荐或搜索的转化情况时。无需其他架构映射。
局限性 只有一部分属性可用，因此某些高级 Vertex AI Search for Retail 功能无法使用。 如果您打算使用搜索功能，则需要设置事件参数键值对以进行跟踪；建议的键为 search_query。
内嵌导入 说明 通过调用 userEvents.import 方法导入。
使用时间 当您希望加强在后端进行所有身份验证的隐私保护，并且能够执行后端导入时。
限制 通常比 Web 导入复杂。

从 Cloud Storage 导入用户事件

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

控制台

  1. 在 Search for Retail 控制台中，前往 Data（数据）> 页面。

    前往“数据”页面
  2. 点击导入以打开导入数据面板。
  3. 选择用户事件。
  4. 选择 Google Cloud Storage 作为数据源。
  5. 选择 Retail 用户事件架构作为架构。
  6. 输入数据的 Cloud Storage 位置。
  7. 点击导入。

cURL

使用 userEvents.import 方法导入用户事件。

  1. 为导入作业的输入参数创建一个数据文件。您可以使用 GcsSource 对象指向您的 Cloud Storage 存储桶。

    您可以提供多个文件，也可以只提供一个。

    • INPUT_FILE：Cloud Storage 中包含您的用户事件数据的文件。有关每种用户事件类型格式的示例，请参阅用户事件简介。确保每个用户事件都位于单独的一行，没有换行符。
    • ERROR_DIRECTORY：存放与导入有关的错误信息的 Cloud Storage 目录。

    输入文件字段必须采用 gs://<bucket>/<path-to-file>/ 格式。错误目录必须采用 gs://<bucket>/<folder>/ 格式。如果错误目录不存在，Vertex AI Search 零售解决方案会创建它。存储桶必须已存在。

    {
"inputConfig":{
 "gcsSource": {
   "inputUris": ["INPUT_FILE_1", "INPUT_FILE_2"],
  },
  "errorsConfig":{"gcsPrefix":"ERROR_DIRECTORY"}
}

  2. 向 userEvents:import REST 方法发出 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 application-default print-access-token)"" \
     --data @./DATA_FILE.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"
  }
}'

从 BigQuery 导入用户事件

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

设置 BigQuery 访问权限

按照设置对 BigQuery 数据集的访问权限中的说明，为您的 Vertex AI Search for retail 服务账号授予 BigQuery 数据集的 BigQuery Data Owner 角色。

从 BigQuery 导入用户事件

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

控制台

  1. 在 Search for Retail 控制台中，前往 Data（数据）> 页面。

    前往“数据”页面
  2. 点击导入以打开导入数据面板。
  3. 选择用户事件。
  4. 选择 BigQuery 作为数据源。

  5. 选择数据架构。

  6. 输入数据所在的 BigQuery 表格。
  7. 可选：输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。
    如果未指定，系统会使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
  8. 可选：在显示高级选项下，输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。

    如果未指定，则使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
  9. 点击导入。

curl

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

您为 dataSchema 指定的值取决于您要导入的内容：

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 和 Google 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 Retail 需要同时使用 searchQuery 和 productDetails 才能返回搜索结果列表，但 Analytics 360 不会在一个事件中同时存储搜索查询和产品展示。为了让 Vertex AI Search for Retail 正常运行，您需要在数据层中创建代码或 JavaScript 像素，以便从 Google Analytics 来源导入这两种类型的用户事件：

      • searchQuery（从 search_term 参数或 view_search_results 事件读取）派生自 hits.page.searchKeyword，如果 hits.customVariables.customVarName 为 searchQuery，则派生自 hits.customVariables.customVarValue。
      • 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 事件

您可以使用 Search Ads 360 控制台或 userEvents.import 方法导入 Google Analytics 360 事件。

控制台

  1. 在 Search for Retail 控制台中，前往 Data（数据）> 页面。

    前往“数据”页面
  2. 点击导入以打开导入数据面板。
  3. 选择用户事件。
  4. 选择 BigQuery 作为数据源。

  5. 选择数据架构。

  6. 输入数据所在的 BigQuery 表格。
  7. 可选：输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。
    如果未指定，系统会使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
  8. 可选：在显示高级选项下，输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。

    如果未指定，则使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
  9. 点击导入。

REST

通过在调用 userEvents.import 方法时添加事件数据，导入用户事件。

对于 dataSchema，请使用值 user_event_ga360。

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"
    }
  }
}'

Java

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 导入 Google Analytics 360 首页浏览数据

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

以下步骤介绍了如何从 Google Analytics 360 数据中提取首页浏览事件，并将其导入到 Vertex AI Search for Retail。简而言之，这项操作是通过将用户对首页的浏览次数（通过首页路径标识）提取到新的 BigQuery 表中，然后将该新表中的数据导入 Vertex AI Search for Retail 来实现的。

如需将首页浏览事件从 Google Analytics 360 导入 Vertex AI Search for Retail，请执行以下操作：

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

    此数据集可以位于 Vertex AI Search 零售解决方案项目中，也可以位于存储 Google 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. 点击 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 表中包含 Google Analytics 360 数据的项目的 ID。

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

      • source_table:：源项目中包含 Google 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. 点击 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 的使用。

准备工作

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

查看数据源

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

如需查看 Vertex AI Search 零售解决方案使用的 Google Analytics 4 字段及其对应的 Vertex AI Search 零售解决方案字段的表格，请参阅 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 Retail 需要同时使用 searchQuery 和 productDetails 才能返回搜索结果列表，但 Google Analytics 4 不会在一个事件中同时存储搜索查询和商品展示次数。为了让 Vertex AI Search for Retail 正常运行，您需要在数据层或通过 JavaScript 像素创建代码，以便从 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"

设置 BigQuery 访问权限

按照设置对 BigQuery 数据集的访问权限中的说明，为您的 Vertex AI Search for retail 服务账号授予 BigQuery 数据集的 BigQuery Data Owner 角色。

导入 Google Analytics 4 事件

您可以使用 Search Ads 360 中的零售广告控制台或 userEvents.import 方法导入 Google Analytics 4 事件。

使用控制台导入 Google Analytics 4 事件

  1. 在 Search for Retail 控制台中，前往 Data（数据）> 页面。

    前往“数据”页面
  2. 点击导入以打开导入数据面板。
  3. 选择用户事件。
  4. 选择 BigQuery 作为数据源。

  5. 选择数据架构。

  6. 输入数据所在的 BigQuery 表格。
  7. 可选：输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。
    如果未指定，系统会使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
  8. 可选：在显示高级选项下，输入项目中 Cloud Storage 存储桶的位置作为数据的临时位置。

    如果未指定，则使用默认位置。如果指定，BigQuery 和 Cloud Storage 存储桶必须位于同一区域内。
  9. 点击导入。

使用 API 导入 Google Analytics 4 事件

通过在调用 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。

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

curl

  1. 创建 JSON 文件：

    {
  "inputConfig": {
    "userEventInlineSource": {
      "userEvents": [
        {
          <userEvent1>>
        },
        {
          <userEvent2>
        },
        ....
      ]
    }
  }
}

  2. 调用 POST 方法：

    curl -X POST \
     -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     --data @./data.json \
  "https://retail.googleapis.com/v2/projects/PROJECT_ID/locations/global/catalogs/default_catalog/userEvents:import"

Java

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 Retail 控制台的数据页面上的事件标签页中查看事件集成指标。此页面会显示去年写入或导入的所有事件。数据成功提取后，指标最长可能需要 24 小时才会显示。

前往“数据”页面

后续步骤