Google BigQuery 集成

需要开发人员协助

您需要开发团队或 Google Cloud 管理员的帮助来设置此集成。请与他们分享本指南。

通过 Google BigQuery 集成，您可以将选定的 Pushwoosh 消息事件流式传输到您的 BigQuery 数据集。您可以使用它在 BigQuery 中分析推送、电子邮件和短信的生命周期事件，构建自定义报告，或将数据连接到您的下游分析工作流。

集成概述

前提条件

在开始集成设置之前，请准备好以下各项。

1. 使用已启用结算功能的 Google Cloud 项目。支持免费试用赠金。BigQuery 沙盒不足以满足要求，因为 Storage Write API 需要启用结算功能。

2. 确保您拥有一个付费的 Pushwoosh 帐户。

定价

您直接向 Google 支付 BigQuery 的使用费用。Pushwoosh 不对集成本身收费。

有关当前费率、免费套餐和区域详情，请参阅 BigQuery 定价。

费用可能包括：

• 数据注入： Pushwoosh 使用 BigQuery Storage Write API 流式传输事件。
• 存储： BigQuery 存储写入目标表中的行。
• 查询： BigQuery 根据您选择的定价模型对查询收费。

集成类型

源： 数据从 Pushwoosh 发送到您的 BigQuery 数据集。

支持的平台

Pushwoosh 从 iOS、Android、Huawei、Chrome、Safari、Firefox 和 Web 平台流式传输事件。

同步的实体

选定的推送、电子邮件和短信生命周期事件将流式传输到 BigQuery。Pushwoosh 会为每个选定的事件向目标表写入一行。

用例

• 近乎实时的消息分析： 在 Pushwoosh 中处理推送、电子邮件和短信生命周期事件后不久，即可在 BigQuery 中进行分析。
• 自定义报告： 为选定的事件类型、应用程序、营销活动和消息标识符构建 BigQuery 报告。
• 下游数据工作流： 将 Pushwoosh 事件数据连接到您的分析、报告或数据处理工作流。

集成工作原理

保存配置后，Pushwoosh 会开始将选定的消息事件近乎实时地流式传输到您的 BigQuery 表。 对于流经 Pushwoosh 的每个消息事件，系统会检查该事件类型是否在您的配置中被选中。

如果被选中，Pushwoosh 会向您的目标表追加一个新行。如果该表尚不存在，Pushwoosh 会使用下述的表结构自动创建它。 事件通常在 Pushwoosh 处理后 30 秒内出现在 BigQuery 中。

在 Google Cloud 中设置集成

选择一个 Google Cloud 项目

登录 Google Cloud Console，然后选择或创建一个将拥有 BigQuery 数据集的项目。

提示

请记下 项目 ID。使用短标识符，例如 my-company-12345，而不是人类可读的项目名称。

启用所需的 API

在 Google Cloud Console 中，转到 API 和服务 → 库 并启用以下 API：

• BigQuery API
• BigQuery Storage API

Pushwoosh 使用这些 API 来创建目标表并将事件流式传输到 BigQuery。

创建服务帐号

Pushwoosh 使用服务帐号将事件写入您的 BigQuery 数据集。

1. 转到 IAM 和管理 → 服务帐号。

2. 点击 创建服务帐号。

3. 在 服务帐号名称 中，输入一个名称，例如 pushwoosh-bigquery。

   Google Cloud 会根据名称自动生成 服务帐号 ID。

   

4. 点击 创建并继续。

授予 IAM 角色

1. 授予服务帐号以下 IAM 角色：

   • BigQuery Data Editor： 允许 Pushwoosh 创建表和追加行。
   • BigQuery User： 允许 Pushwoosh 使用 Storage Write API。
   

注意

您可以在项目级别或数据集级别附加角色。项目级别的访问权限最容易设置。数据集级别的访问权限更具限制性，建议用于生产环境。

2. 点击 继续。

3. 点击 完成。

创建 JSON 密钥

Pushwoosh 使用 JSON 密钥以服务帐号的身份进行身份验证。

1. 打开您创建的服务帐号。

2. 转到 密钥 → 添加密钥 → 创建新密钥。

3. 选择 JSON。

Google Cloud 会将 JSON 密钥文件下载到您的计算机。

警告

请妥善保管 JSON 密钥文件。任何拥有此文件的人都可以写入您的 BigQuery 项目。请勿将其提交到 git 或通过聊天分享。Pushwoosh 会将密钥静态加密存储，并且在上传后不会通过 UI 公开。

创建数据集

数据集是 Pushwoosh 存储流式事件表的地方。

1. 在 Google Cloud Console 中，打开 BigQuery。

2. 在 浏览器 中，选择您为集成准备的项目。

3. 点击 创建数据集。

4. 在 数据集 ID 中，输入一个数据集 ID，例如 pushwoosh_data。

5. 在 数据位置 中，选择数据集区域。

6. 点击 创建数据集。

在 Pushwoosh 中配置集成

1. 在您的 Pushwoosh 帐户中，为您要连接的应用程序转到 设置 → 第三方集成。

2. 在可用服务列表中找到 Google BigQuery，然后点击 配置。

3. 填写配置字段。

• GCP 项目 ID： 输入来自 Google Cloud 的项目 ID，例如 my-company-12345。
• 服务帐号 JSON： 粘贴您从 Google Cloud 下载的 JSON 密钥文件的全部内容。
• 数据集 ID： 填写 GCP 项目 ID 和 服务帐号 JSON 后，Pushwoosh 会获取您的服务帐号可以访问的数据集。选择目标数据集。如果下拉列表为空，请检查服务帐号是否具有访问权限以及该数据集是否存在于您指定的项目中。
• 数据集区域： 选择您的 BigQuery 数据集的区域。
• 表名： 留空以使用默认的 pushwoosh_events 表。Pushwoosh 会使用下述的表结构创建该表。
• 事件： 选择您想要流式传输的事件。您可以稍后更改此列表。
• 将事件流式传输到 BigQuery： 启用此开关。关闭此开关可暂停流式传输而不删除配置。

4. 点击 测试连接。

Pushwoosh 会根据 BigQuery 验证凭据，而不会写入数据。

您可能会看到以下连接状态之一：

• 连接成功： 凭据有效，并且服务帐号可以访问数据集。
• auth_failed：JSON 密钥无效或已被撤销。
• dataset_not_found：数据集 ID 不正确或服务帐号无法访问它。
• missing_permission：服务帐号缺少所需的角色之一。

5. 点击 应用。

Pushwoosh 会保存配置并在大约 30 秒内开始使用它。之后，选定的事件将开始流式传输到 BigQuery。

验证集成

1. 发送一个测试推送，或触发另一个会产生您所选事件类型的消息。

2. 等待大约 30 秒。

3. 打开 BigQuery Studio。

4. 转到您的项目，然后打开您配置的数据集和目标表。如果您将 表名 留空，请打开 pushwoosh_events。

5. 点击 预览。

您应该会在表中看到事件行。

表结构

Pushwoosh 将每个选定的事件作为目标表中的单独一行写入。为了使查询更快、更容易筛选，该表按 timestamp 进行每日分区，并按 app_id 和 event_kind 进行聚类。

字段名	类型	描述
event_kind	STRING	Pushwoosh 事件类型，例如 Push Sent 或 Email Opened。
message_id	STRING	Pushwoosh 消息代码，例如营销活动或消息标识符。
device_id	STRING	产生事件的设备的 Pushwoosh 硬件 ID。
user_id	STRING	您的外部用户 ID（如果已知）。对于匿名设备，此字段为空。
timestamp	TIMESTAMP	UTC 时间的事件时间。
app_id	STRING	Pushwoosh 应用程序代码。
platform	STRING	源平台，例如 ios、android 或 web。
properties	JSON	其他事件字段。使用 JSON_VALUE 查询字段，如下所示。

查询属性

properties 列以 JSON 格式存储其他事件字段。在您的查询中使用 JSON_VALUE 来提取单个字段。

例如，要查看过去 7 天内哪些营销活动带来了最多的打开次数，请点击 + 创建一个新查询，粘贴下面的 SQL，然后点击 运行。

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

要查看过去一小时的事件计数，请运行此查询：

SELECT
  event_kind,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

更新集成

轮换服务帐号密钥

1. 在 Google Cloud Console 中，转到 IAM 和管理 → 服务帐号。

2. 打开您的服务帐号。

3. 转到 密钥 并创建一个新的 JSON 密钥。

4. 在确认新密钥有效之前，请保持旧密钥处于活动状态。

5. 在 Pushwoosh 中，打开 Google BigQuery 配置模式窗口。

6. 将新的 JSON 粘贴到 服务帐号 JSON 中。

7. 点击 应用。

Pushwoosh 会验证新密钥，替换存储的凭据，并在下一次配置重新加载后开始使用它，这大约需要 30 秒。

在确认事件仍在流动后，请在 Google Cloud Console 中删除旧密钥。

更改目标数据集或表

1. 在 Pushwoosh 中，转到 设置 → 第三方集成。

2. 打开 Google BigQuery 设置。

3. 选择一个不同的数据集或输入一个新的表名。

4. 点击 应用。

Pushwoosh 会在大约 30 秒内使用新的目标重新打开流。已经写入的行会保留在旧表中。Pushwoosh 不会回填历史数据。

当您更新其他设置时，如果要保持存储的服务帐号密钥不变，请在点击 应用 之前将 服务帐号 JSON 留空。

问题排查

问题	检查事项
测试连接失败，显示 auth_failed	服务帐号 JSON 格式不正确或密钥已在 Google Cloud 中被撤销。创建一个新密钥并再次粘贴完整的 JSON 文件。该文件以 { 开头，以 } 结尾，并包含一个 private_key 块。
测试连接失败，显示 dataset_not_found	数据集 ID 拼写错误或在您指定的项目中不存在。数据集 ID 区分大小写。从下拉列表中选择数据集以避免拼写错误。
测试连接失败，显示 missing_permission	服务帐号缺少 BigQuery Data Editor 或 BigQuery User 角色。在项目级别授予这两个角色，或者为了更严格的访问控制，在数据集级别授予它们。
测试连接通过，但 BigQuery 中没有出现任何行	等待至少 30 秒。检查您发送的事件类型是否在 事件 中被选中。例如，如果只选择了 Push Opened 并且没有人打开推送，则不会出现任何行。
配置看起来正确，但模式窗口显示为空字段	重新加载页面。配置在每次打开模式窗口时获取，并由底层服务缓存 30 秒。如果您刚刚保存了设置，请稍等片刻再重新打开模式窗口。

注意

Pushwoosh 记录 Push Sent、Email Sent 和 SMS Sent，无论投递状态如何，以便 BigQuery 的聚合数据与 Pushwoosh 的规范统计数据相匹配。对于 Delivered、Opened、Bounced 和 Unsubscribed，Pushwoosh 只记录成功的事件。

常见问题解答

我可以使用免费的 Google Cloud 帐户吗？

可以，只要项目启用了结算功能。免费试用赠金足以在整个试用期内以典型的数据量运行此集成。未启用结算功能的 BigQuery 沙盒将无法工作，因为 Storage Write API 需要启用结算功能。

Pushwoosh 能看到我的 BigQuery 数据吗？

不能。您上传的服务帐号凭据授权 Pushwoosh 写入您选择的数据集。Pushwoosh 不会从您的数据集中读取数据，也无权访问您项目的其余部分。

我可以导出到多个 BigQuery 数据集吗？

每个应用程序支持一个目标。如果您需要在两个数据集中使用相同的事件，请在您的项目中设置一个 BigQuery 计划查询，以将数据从 pushwoosh_events 复制到另一个表。

我可以更改表结构吗？

表结构对所有客户都是固定的。如果您需要额外的列，请在您自己的视图或计划查询中从 properties JSON 中提取它们。

如果我暂时禁用集成会发生什么？

关闭 将事件流式传输到 BigQuery 并点击 应用。Pushwoosh 会在大约 30 秒内停止为该应用程序追加事件。

当您重新启用集成时，在禁用期间产生的事件不会被缓冲或回填。Pushwoosh 会保留配置，包括凭据、数据集和事件选择。

我如何完全删除集成？

请联系 support@pushwoosh.com 删除集成配置。数据集和已经写入 BigQuery 的行将保留在您的 Google Cloud 帐户中。

有投递保证吗？

该集成使用至少一次投递。在正常操作下，重复项很少见。在追加和提交之间发生进程重启可能会产生少量重复行。如果您的下游管道需要精确一次的结果，请在 SQL 中进行去重。

为什么没有 Push Clicked 事件？

Pushwoosh 目前在此集成中为推送通知提供 Push Sent、Push Delivered 和 Push Opened 事件。没有专门的推送点击步骤。电子邮件和短信有它们自己的生命周期事件。