# Google BigQuery 集成
[Google BigQuery](https://cloud.google.com/bigquery) 集成可将选定的 Pushwoosh 消息事件流式传输到您的 BigQuery 数据集。您可以使用它来分析 BigQuery 中的推送、电子邮件和短信生命周期事件，构建自定义报告，或将数据连接到您的下游分析工作流。
## 集成概述
### 先决条件
在打开集成设置之前，请准备好以下内容。
1. 使用已启用结算功能的 Google Cloud 项目。支持免费试用积分。BigQuery Sandbox 不够，因为 Storage Write API 需要启用结算功能。
2. 确保您拥有一个付费的 Pushwoosh 账户。
### 定价
您直接向 Google 支付 BigQuery 的使用费。Pushwoosh 不对集成本身收费。
有关当前费率、免费套餐和地区详情，请参阅 [BigQuery 定价](https://cloud.google.com/bigquery/pricing)。
费用可能包括：
- **数据注入：** 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](https://console.cloud.google.com)，然后选择或创建一个将拥有 BigQuery 数据集的项目。
### 启用所需的 API
在 Google Cloud Console 中，转到 **APIs & Services** → **Library** 并启用这些 API：
- **BigQuery API**
- **BigQuery Storage API**
Pushwoosh 使用这些 API 来创建目标表并将事件流式传输到 BigQuery。
### 创建服务账户
Pushwoosh 使用服务账户将事件写入您的 BigQuery 数据集。
1. 转到 **IAM & Admin** → **Service Accounts**。
2. 点击 **Create service account**。
3. 在 **Service account name** 中，输入一个名称，例如 `pushwoosh-bigquery`。
Google Cloud 会根据名称自动生成 **Service account ID**。
4. 点击 **Create and continue**。
### 授予 IAM 角色
1. 授予服务账户以下 IAM 角色：
- **BigQuery Data Editor：** 允许 Pushwoosh 创建表和追加行。
- **BigQuery User：** 允许 Pushwoosh 使用 Storage Write API。
2. 点击 **Continue**。
3. 点击 **Done**。
### 创建 JSON 密钥
Pushwoosh 使用 JSON 密钥以服务账户身份进行身份验证。
1. 打开您创建的服务账户。
2. 转到 **Keys** → **Add key** → **Create new key**。
3. 选择 **JSON**。
Google Cloud 会将 JSON 密钥文件下载到您的计算机。
### 创建数据集
数据集是 Pushwoosh 存储流式事件表的地方。
1. 在 Google Cloud Console 中，打开 **BigQuery**。
2. 在 **Explorer** 中，选择您为集成准备的项目。
3. 点击 **Create dataset**。
4. 在 **Dataset ID** 中，输入一个数据集 ID，例如 `pushwoosh_data`。
5. 在 **Data location** 中，选择数据集区域。
6. 点击 **Create dataset**。
## 在 Pushwoosh 中配置集成
1. 在您的 Pushwoosh 账户中，为您要连接的应用程序转到 **Settings** → **3rd Party Integrations**。
2. 在可用服务列表中找到 **Google BigQuery**，然后点击 **Configure**。
3. 填写配置字段。
- **GCP Project ID：** 输入来自 Google Cloud 的项目 ID，例如 `my-company-12345`。
- **Service Account JSON：** 粘贴您从 Google Cloud 下载的 JSON 密钥文件的全部内容。
- **Dataset ID：** 填写 **GCP Project ID** 和 **Service Account JSON** 后，Pushwoosh 会获取您的服务账户可以访问的数据集。选择目标数据集。如果下拉列表为空，请检查服务账户是否具有访问权限以及数据集是否存在于您指定的项目中。
- **Dataset region：** 选择您的 BigQuery 数据集的区域。
- **Table name：** 留空以使用默认的 `pushwoosh_events` 表。Pushwoosh 会使用下面描述的模式创建该表。
- **Events：** 选择您想要流式传输的事件。您可以稍后更改此列表。
- **Stream events to BigQuery：** 启用此开关。关闭它以暂停流式传输而不删除配置。
4. 点击 **Test connection**。
Pushwoosh 会根据 BigQuery 验证凭据，而不会写入数据。
您可能会看到以下连接状态之一：
- **Connection successful：** 凭据有效，服务账户可以访问数据集。
- `auth_failed`：JSON 密钥无效或已被撤销。
- `dataset_not_found`：数据集 ID 不正确或服务账户无法访问它。
- `missing_permission`：服务账户缺少所需的角色之一。
5. 点击 **Apply**。
Pushwoosh 保存配置并在大约 30 秒内开始使用它。之后，选定的事件开始流式传输到 BigQuery。
## 验证集成
1. 发送一个测试推送，或触发另一个产生您所选事件类型的消息。
2. 等待大约 30 秒。
3. 打开 [BigQuery Studio](https://console.cloud.google.com/bigquery)。
4. 转到您的项目，然后打开您配置的数据集和目标表。如果您将 **Table name** 留空，请打开 `pushwoosh_events`。
5. 点击 **Preview**。
您应该会在表中看到事件行。
### 表格模式
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，然后点击 **Run**。
```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
```
要查看过去一小时的事件计数，请运行此查询：
```sql
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 & Admin** → **Service Accounts**。
2. 打开您的服务账户。
3. 转到 **Keys** 并创建一个新的 JSON 密钥。
4. 在确认新密钥有效之前，请保持旧密钥处于活动状态。
5. 在 Pushwoosh 中，打开 **Google BigQuery** 配置模态框。
6. 将新的 JSON 粘贴到 **Service Account JSON** 中。
7. 点击 **Apply**。
Pushwoosh 验证新密钥，替换存储的凭据，并在下一次配置重新加载后开始使用它，这大约需要 30 秒。
在您确认事件仍在流动后，请在 Google Cloud Console 中删除旧密钥。
### 更改目标数据集或表格
1. 在 Pushwoosh 中，转到 **Settings** → **3rd Party Integrations**。
2. 打开 **Google BigQuery** 设置。
3. 选择一个不同的数据集或输入一个新的表名。
4. 点击 **Apply**。
Pushwoosh 会在大约 30 秒内使用新的目标重新打开流。已经写入的行会保留在旧表中。Pushwoosh 不会回填历史数据。
要在更新其他设置时保持存储的服务账户密钥不变，请在点击 **Apply** 之前将 **Service Account JSON** 留空。
## 故障排除
| 问题 | 检查内容 |
| :---- | :---- |
| **测试连接失败，显示 `auth_failed`** | 服务账户 JSON 格式不正确或密钥已在 Google Cloud 中被撤销。创建一个新密钥并再次粘贴完整的 JSON 文件。该文件以 `{` 开头，以 `}` 结尾，并包含一个 `private_key` 块。 |
| **测试连接失败，显示 `dataset_not_found`** | **Dataset ID** 拼写错误或在您指定的项目中不存在。数据集 ID 区分大小写。从下拉列表中选择数据集以避免拼写错误。 |
| **测试连接失败，显示 `missing_permission`** | 服务账户缺少 **BigQuery Data Editor** 或 **BigQuery User**。在项目级别授予这两个角色，或在数据集级别授予它们以获得更严格的访问权限。 |
| **测试连接通过，但 BigQuery 中没有出现任何行** | 等待至少 30 秒。检查您发送的事件类型是否在 **Events** 中被选中。例如，如果只选择了 **Push Opened** 并且没有人打开推送，则不会出现任何行。 |
| **配置看起来正确，但模态框显示为空字段** | 重新加载页面。配置在每次打开模态框时获取，并由底层服务缓存 30 秒。如果您刚刚保存了设置，请稍等片刻再重新打开模态框。 |
## 常见问题解答
##### 我可以使用免费的 Google Cloud 账户吗？
可以，只要项目启用了结算功能。免费试用积分足以在整个试用期内以典型的数据量运行此集成。没有启用结算功能的 BigQuery Sandbox 将无法工作，因为 Storage Write API 需要结算功能。
##### Pushwoosh 能看到我的 BigQuery 数据吗？
不能。您上传的服务账户凭据授权 Pushwoosh 写入您选择的数据集。Pushwoosh 不会从您的数据集中读取数据，也无权访问您项目的其余部分。
##### 我可以导出到多个 BigQuery 数据集吗？
每个应用程序支持一个目标。如果您需要在两个数据集中使用相同的事件，请在您的项目中设置一个 BigQuery 计划查询，以将数据从 `pushwoosh_events` 复制到另一个表中。
##### 我可以更改表格模式吗？
该模式在所有客户中都是固定的。如果您需要额外的列，请在您自己的视图或计划查询中从 `properties` JSON 中提取它们。
##### 如果我暂时禁用集成会发生什么？
关闭 **Stream events to BigQuery** 并点击 **Apply**。Pushwoosh 会在大约 30 秒内停止为该应用程序追加事件。
当您重新启用集成时，在集成关闭期间产生的事件不会被缓冲或回填。Pushwoosh 会保留配置，包括凭据、数据集和事件选择。
##### 我如何完全删除集成？
请联系 [support@pushwoosh.com](mailto:support@pushwoosh.com) 以删除集成配置。已经写入 BigQuery 的数据集和行将保留在您的 Google Cloud 账户中。
##### 有交付保证吗？
该集成使用至少一次交付。在正常操作下，重复项很少见。在追加和提交之间进行进程重启可能会产生少量重复行。如果您的下游管道需要精确一次的结果，请在 SQL 中进行重复数据删除。
##### 为什么没有 Push Clicked 事件？
Pushwoosh 目前在此集成中为推送通知公开 **Push Sent**、**Push Delivered** 和 **Push Opened**。没有专门的推送点击步骤。电子邮件和短信有其自己的生命周期事件。