将分析指标导出至 BigQuery

本页面介绍如何将用于零售分析的 Vertex AI Search 指标导出到 BigQuery。通过导出分析指标，您可以保留指标并编写 SQL 以便自行分析。

适用于零售的 Vertex AI Search 分析指标会自动为您生成。如需详细了解如何使用分析指标来衡量适用于零售业的 Vertex AI Search 的业务影响，请参阅查看分析数据。

将指标数据导出到 BigQuery 时存在以下限制：

  • 导出到 Vertex AI Search for Retail 项目中的 BigQuery 表的数据是授权视图，而不是具体化视图。

  • 您无法更改或更新这些表中的数据。如果您需要更改或更新数据，请将视图导出或复制到另一个目的地。

  • 对于 180 天之前的用户事件或 180 天之前生成的指标，您无法导出相关指标。在 180 天期限之前生成的任何指标均无法检索。

准备工作

您必须先完成准备工作中的步骤，才能将指标导出到 BigQuery。这包括导入用户事件和（可选）目录信息。

有关导入的详细信息，请参阅：

在 BigQuery 中创建数据集

您需要在 BigQuery 中创建数据集来保存分析指标数据。

您必须在实现零售版 Vertex AI Search 的同一项目中创建数据集。

  1. 如果您之前未在项目中使用过 BigQuery，请启用 BigQuery API，并确保您具有可以创建数据集和表的 IAM 角色。

    请参阅准备工作和使用 IAM 进行访问权限控制

    请参阅 BigQuery 文档。

  2. 在 BigQuery 中，在 US（美国的多个区域）多区域位置创建数据集。例如，将其命名为 retail_data。如果您在其他区域创建数据集，则将数据导出到 BigQuery 会失败。不支持对该数据集使用 CMEK；启用此 CMEK 会导致导出失败。

    如需了解如何创建数据集，请参阅 BigQuery 文档中的创建数据集。

    此数据集将用于保存您导出的数据表。以下步骤介绍了如何导出。

将分析指标导出到 BigQuery 表

使用 exportAnalyticsMetrics 方法将零售目录导出到 BigQuery 表。

在使用任何请求数据之前，请先进行以下替换：

  • PROJECT_ID：您在其中创建了 BigQuery 数据集的 Vertex AI Search for Retail API 项目的 ID。
  • DATASET_ID：您在 在 BigQuery 中创建数据集部分创建的数据集的名称。例如，使用 retail_data 或 retail_metrics_data。
  • TABLE_ID_PREFIX：表 ID 的前缀。此前缀不得为空字符串。添加了 retail_analytics_metrics 的后缀，以补全表名称。例如，如果前缀为 test，则表的名称为 test_retail_analytics_metrics。

请求 JSON 正文：

{
  "catalog": "projects/PROJECT_ID/locations/global/catalogs/default_catalog",
  "outputConfig":
  {
    "bigqueryDestination":
    {
      "datasetId": "DATASET_ID",
        "tableIdPrefix": "TABLE_ID_PREFIX",
        "tableType": "view"
    }
  }
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

{
  "name": "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/operations/12310973052792775280",
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.retail.v2.ExportAnalyticsMetricsResponse",
    "outputResult": {
      "bigqueryResult": [
        {
          "datasetId": "DATASET_ID",
          "tableId": "TABLE_ID_PREFIX_retail_analytics_metrics"
        }
      ]
    }
  }
}

指标定义

导出的指标是计数指标。某些计数指标可能会轻微偏移，因为漫游器过滤可能会将某些事件从指标计算中排除。漫游器过滤功能有助于更准确地测量性能。这不会影响依赖维度 external_experiment_ids 的 A/B 测试，而漫游器过滤适用于所有流量。

指标维度

计数指标是从具有相同维度的相关用户事件直接汇总的原始计数。为了解读指标，您需要知道指标所依据的维度。对于分析指标，搜索和浏览事件称为展示事件，detail_page_view、add_to_cart 和 purchase 事件称为转化事件。下表定义了指标维度。

指标维度 说明
日期

生成指标的相关事件的日期。

对于展示指标，这是指展示事件的日期。

对于会话和访问者指标，这是指会话/访问者首次展示事件的日期。
external_experiment_ids

生成指标的相关事件的实验 ID。

对于展示指标，此字段为展示事件的实验 ID。

对于会话和访问者指标，这是会话/访问者中出现的所有展示事件的唯一外部实验 ID 的串联。例如，如果某个会话/访问者内有两个搜索事件，第一个搜索事件包含 external_experiment_ids“test_arm_1,test_arm_2”，第二个搜索事件包含“external_experiment_ids”“test_arm_1,test_arm_3”，则会话/访问者的 external_experiment_id 为“test_arm_1,test_arm_3”,test_arm_
device_type

生成指标的相关事件的设备类型。例如，如果事件是从移动设备还是桌面设备生成的。

对于展示指标，这是指展示事件的设备类型。

对于会话和访问者指标，如果会话/访问者具有多种不同的设备类型，则此字段为空；如果整个会话/访问者只有一个设备类型，则此字段为空。
serving_config

生成指标的相关事件的投放配置。

对于展示指标，这是指展示事件的服务配置。

对于会话和访问者指标，如果会话/访问者有多个不同的服务配置，则此字段为空；如果整个会话/访问者只有一个服务配置，则此字段为空。
traffic_destination

生成指标的相关事件的来源。

对于展示次数指标，如果展示由 Google 投放，则此值为“Google”；如果展示由您自己的解决方案投放，则为“非 Google”。

对于会话和访问者指标，如果会话/访问者同时具有由 Google 和您自己的解决方案投放的展示事件，此值为“混合”。如果展示事件完全由 Google 提供，则为“Google”；如果展示事件完全由整个会话/访问者的解决方案提供，则为“非 Google”。
实体

零售商使用同一个商品清单面向多个品牌网站或区域提供服务。实体通常代表品牌或营业地点。

对于展示指标，这是展示事件的实体。

对于会话和访问者指标，这是针对会话/访问者统计的展示事件中排名前五位的实体。

展示次数指标

展示次数指标是根据前提条件计算的。转化事件（detail_page_view、add_to_cart 和 purchase 事件）只有在满足以下条件时才能归因于展示事件。

  • 展示事件和转化事件具有同一访问者。

  • 转化事件的产品 ID 必须显示在展示事件的结果中。

  • 展示事件发生后，转化事件在要求的时间范围内。不同类型的转化事件适用不同的转化时间范围。

    转化路径 转化时间范围
    展示 -> 详情页面浏览 60 秒
    展示 -> 添加到购物车 24 小时
    展示 -> 购买 48 小时

搜索网络展示次数指标

指标名称 说明
search_event 搜索事件数
detail_page_view_from_search 搜索带来的详情页面浏览事件数
add_to_cart_unit_from_search 搜索到的添加到购物车中的商品数量
purchase_unit_from_search 搜索带来的购买单位数
revenue_from_search 搜索带来的收入
search_event_without_result 未返回任何结果的搜索事件数
search_request_personalization_enabled 启用了个性化功能的搜索请求的数量
search_request_personalization_result_served 提供个性化结果的搜索请求的数量

浏览展示次数指标

指标名称 说明
browse_event 浏览事件数
detail_page_view_from_browse 浏览带来的详情页面浏览事件数
add_to_cart_unit_from_browse 浏览后添加到购物车中的商品数量
purchase_unit_from_browse 浏览带来的购买单元数
revenue_from_browse 浏览收入
browse_event_without_result 未返回任何结果的浏览事件数
browse_request_personalization_enabled 启用了个性化功能的浏览请求数量
browse_request_personalization_result_served 随个性化结果一起传送的浏览请求数量

会话指标

会话是指用户与系统之间持续互动的一段时间。任何用户事件都标记有会话开始，如果在接下来的 30 分钟内没有发生任何其他事件，会话结束就会标记出来。每当在已启动的会话中发生用户事件时，该会话都会再延长 30 分钟。会话结束后，当用户再次与系统互动时，会开始新的会话。

描述会话指标的维度由会话中的所有用户事件共同定义。如需了解如何为会话设置维度值，请参阅指标维度。

指标名称 说明
session 会话数

搜索会话指标

搜索会话是指至少包含一个搜索事件的会话。请注意，根据浏览会话指标的定义，搜索会话也可以是浏览会话。

指标名称 说明
search_session 涉及搜索的会话数
search_event_in_search_session 搜索会话中的搜索事件数
browse_event_in_search_session 搜索会话中浏览事件数
detail_page_view_in_search_session 搜索会话中的详情网页浏览次数
add_to_cart_in_search_session 搜索会话内的“添加到购物车”事件数
add_to_cart_unit_in_search_session 搜索会话内的添加到购物车单元数
purchase_order_in_search_session 搜索会话中的采购订单计数
purchase_unit_in_search_session 搜索会话中的购买单元数
revenue_in_search_session 搜索会话内的收入
bounce_count_in_search_session 在搜索会话中仅浏览了一个网页就离开网站的访问者的会话数

浏览会话指标

浏览会话是指至少包含一个浏览事件的会话。请注意，浏览会话也可以是搜索会话指标定义的搜索会话。

指标名称 说明
browse_session 涉及浏览的会话数
search_event_in_browse_session 浏览会话内的搜索事件数
browse_event_in_browse_session 浏览会话内的浏览事件数
detail_page_view_in_browse_session 浏览会话中的详情页浏览量
add_to_cart_in_browse_session 浏览会话内的“添加到购物车”事件数
add_to_cart_unit_in_browse_session 浏览会话内添加到购物车单元的数量
purchase_order_in_browse_session 浏览会话中的采购订单计数
purchase_unit_in_browse_session 浏览会话中的购买单元数
revenue_in_browse_session 浏览会话内的收入
bounce_count_in_browse_session 在浏览会话中仅查看了一个网页就离开网站的访问者的会话数

访问者指标

访问者由访问者 ID 进行唯一标识。访问者指标汇总了访问者的所有用户事件信息。

描述访问者指标的维度由访问者的所有用户事件共同定义。如需了解如何为访问者设置维度值，请参阅指标维度。

指标名称 说明
访问者 访问者数量

搜索访问者指标

搜索访问者是指至少执行了一个搜索事件的访问者。请注意，根据浏览访问者指标的定义，搜索访问者也可以是浏览访问者。

指标名称 说明
search_visitor 至少执行过一次搜索的访问者数量
search_event_from_search_visitor 来自搜索访问者的搜索事件数
browse_event_from_search_visitor 浏览搜索访问者的事件数
detail_page_view_from_search_visitor 搜索访问者的详情页面浏览量
add_to_cart_from_search_visitor 搜索访问者的添加到购物车事件数
add_to_cart_unit_from_search_visitor 搜索访问者添加到购物车中的商品数量
purchase_order_from_search_visitor 来自搜索访问者的采购订单数量
purchase_unit_from_search_visitor 搜索访问者的购买次数单位
revenue_from_search_visitor 搜索访问者带来的收入

浏览访问者指标

浏览访问者是指执行至少一个浏览事件的访问者。请注意，根据搜索访问者指标的定义，浏览访问者也可以是搜索访问者。

指标名称 说明
browse_visitor 至少执行一次浏览的访问者数量
search_event_from_browse_visitor 浏览访问者的搜索事件数
browse_event_from_browse_visitor 浏览访问者的浏览事件数
detail_page_view_from_browse_visitor 浏览访问者的详情页面浏览量
add_to_cart_from_browse_visitor 浏览访问者的“添加到购物车”事件数
add_to_cart_unit_from_browse_visitor 浏览访问者的添加到购物车单元数
purchase_order_from_browse_visitor 浏览访问者带来的采购订单数量
purchase_unit_from_browse_visitor 浏览访问者的购买单元数
revenue_from_browse_visitor 浏览访问者带来的收入

用法示例

如果您将指标数据复制或导出到其他目标位置，则可以使用 SQL 获取有关所导出指标的概要信息或具体信息。以下各部分提供了使用 SQL 浏览导出的指标的一些常用方法。

计算点击率 (CTR)

针对每个流量目的地，按日期计算每种设备类型的搜索点击率。

SELECT
  `date`,
  device_type,
  traffic_destination,
  SUM(detail_page_view_from_search) / SUM(search_event) as search_CTR
FROM copied_table
GROUP BY `date`, device_type, traffic_destination

获取由浏览带来的详情页面浏览量

使用包含 test_arm 的 external_experiment_ids 获取来自 Google 流量浏览事件的详细信息页浏览事件，并显示所有维度信息。external_experiment_ids重复string。

SELECT
  `date`,
  external_experiment_ids,
  device_type,
  serving_config,
  traffic_destination,
  entity,
  detail_page_view_from_browse
FROM copied_table
WHERE
  traffic_destination = 'Google' AND 'test_arm' in UNNEST(external_experiment_ids)

获取最常用的服务配置

获取 2023 年 10 月 1 日至 2023 年 11 月 1 日期间针对 Google 流量最常用的服务配置。每个搜索事件都应具有关联的服务配置。

SELECT
  serving_config,
  SUM(search_event) as total_search_count
FROM copied_table
WHERE `date` between '2023-10-01' and '2023-11-01' AND traffic_destination = 'Google'
GROUP BY serving_config
ORDER BY total_search_count