
OneSignal Databricks 集成概览
概览
OneSignal + Databricks 集成支持双向数据同步:- 将 OneSignal 消息事件导出到 Databricks 用于分析、仪表板和报告。
- 从 Databricks 导入自定义事件到 OneSignal 以触发旅程和个性化活动。
将 OneSignal 事件导出到 Databricks
将推送、电子邮件、应用内和 SMS 事件从 OneSignal 同步到您的 Databricks 湖仓,以实现近实时分析和可见性。 要求- 专业计划
- 启用自定义事件(用于事件导入)
- Databricks 平台:AWS、Azure 或 GCP
- Databricks 计划:高级或更高版本
- Databricks Unity Catalog(推荐用于治理)
- 用于查询的 Databricks SQL 仓库
- Delta Lake 事件表(用于自定义事件导入)
1. 收集 SQL 仓库详细信息
1
登录到您的 Databricks 工作区
在您的 Databricks 工作区中转到 SQL 仓库。
2
选择您的仓库
选择您的仓库并打开连接详细信息选项卡。
3
保存以下详细信息
- 服务器主机名
- 端口
- HTTP 路径

用于 Fivetran 设置的 Databricks SQL 连接详细信息
2. 创建服务主体
1
转到服务主体页面
转到工作区设置 > 身份和访问 > 服务主体。
2
添加新的服务主体
点击添加服务主体,然后点击添加新建。
3
命名服务主体
为其命名(例如 
onesignal-sync
)。
添加服务主体的模态窗口,突出显示'添加新建'选项
3. 生成密钥
1
点击进入创建的主体
2
转到密钥选项卡
3
生成密钥
点击生成密钥并安全保存。
密钥只显示一次—请安全存储。

显示用于 API 身份验证的 OAuth 密钥和客户端 ID 的 Databricks'生成密钥'模态窗口
4. 分配权限
1
导航到您的目录并打开权限选项卡
2
点击授权
3
为服务主体分配以下权限
- USE CATALOG
- USE SCHEMA
- SELECT
- MODIFY
- CREATE SCHEMA
- CREATE TABLE

为 Databricks 主体分配权限的屏幕,已选择自定义目录权限。
5. 连接 OneSignal
1
激活集成
在 OneSignal 中,导航到数据 > 集成 > Databricks。
2
输入详细信息
- 服务器主机名
- 端口
- HTTP 路径
- 目录名称
- 架构名称
- 服务主体凭据(ID + 密钥)

OneSignal Databricks 配置表单,包含目录、主机名、HTTP 路径和 OAuth 凭据字段。
3
配置集成
- 同步频率: 最频繁每 15 分钟一次
- 数据集/表名: 预设为
onesignal_events_<app-id>
和message_events
(可编辑) - 事件类型: 选择要同步的事件—选择全部或只选择您需要的
4
选择事件
选择您希望在 Databricks 目录中接收的事件。

OneSignal 事件导出设置屏幕,显示同步状态、数据集配置和选定的消息事件类型。
5
完成设置
点击保存并等待成功确认
初始数据同步可能需要 15-30 分钟才能在 BigQuery 中显示。在等待期间,通过推送、电子邮件、应用内或 SMS 发送消息以触发选定的事件。
6. 在 Databricks 中查看数据
- 在 Databricks 中打开您的目录。
- 同步完成后,您配置的架构将出现。
-
访问并查询
message_events
表。Databricks 目录视图,显示生产架构下的 OneSignal 消息事件表。
-
点击进入表以预览示例数据。
来自 message_events_1 表的示例数据,包含同步的 OneSignal 事件字段。
如果您遇到缺少架构、权限错误或格式错误的事件等问题,请联系
support@onesignal.com
。消息事件和属性
消息事件类型
属性:event_kind
类型: String
消息和事件的类型(例如 message.push.received
、message.push.sent
)。
消息事件 (OneSignal) | event_kind | 描述 |
---|---|---|
推送已发送 | message.push.sent | 推送通知成功发送。 |
推送已接收 | message.push.received | 推送确认已送达并被用户接收。 |
推送已点击 | message.push.clicked | 用户点击了推送。 |
推送失败 | message.push.failed | 送达失败。查看消息报告。 |
推送已取消订阅 | message.push.unsubscribed | 用户取消订阅推送。 |
应用内展示 | message.iam.displayed | 应用内消息已显示。 |
应用内点击 | message.iam.clicked | 应用内消息已点击。 |
应用内页面查看 | message.iam.pagedisplayed | 应用内页面已显示。 |
邮件已发送 | message.email.sent | 邮件已送达。 |
邮件已接收 | message.email.received | 邮件已被接收方邮件服务器接受。 |
邮件已打开 | message.email.opened | 用户已打开邮件。 |
邮件链接已点击 | message.email.clicked | 邮件中的链接已点击。 |
邮件已取消订阅 | message.email.unsubscribed | 接收方已取消订阅。 |
邮件已标记为垃圾邮件 | message.email.resporedasspam | 用户将您的邮件标记为垃圾邮件。 |
邮件已退回 | message.email.hardbounced | 由于永久性送达失败而退回。 |
邮件失败 | message.email.failed | 送达失败。 |
邮件已抑制 | message.email.supressed | 由于抑制列表而被抑制。 |
短信已发送 | message.sms.sent | 短信已发送。 |
短信已送达 | message.sms.delivered | 短信成功送达。 |
短信失败 | message.sms.failed | 短信送达失败。 |
短信未送达 | message.sms.undelivered | 短信被拒绝或无法到达。 |
事件数据架构
对于用户生成的每个消息事件,以下元数据将附加到记录中。列名称 | 类型 | 描述 |
---|---|---|
event_id | UUID | 事件的唯一标识符 |
event_timestamp | Timestamp | 事件发生时间 |
event_kind | String | 事件类型 |
subscription_device_type | String | 设备类型(例如,iOS、Android、Web、Email、SMS) |
language | String | 订阅语言代码 |
version | String | 集成版本 |
device_os | String | 设备操作系统版本 |
device_type | Number | 数字设备类型 |
token | String | 推送令牌、电话号码或邮箱 |
subscription_id | UUID | 订阅 ID |
subscribed | Boolean | 订阅状态 |
onesignal_id | UUID | OneSignal 用户 ID |
last_active | String | 上次活跃时间戳 |
sdk | String | OneSignal SDK 版本 |
external_id | String | 应与集成用户 ID 匹配的外部用户 ID |
app_id | UUID | 来自 OneSignal 的应用 ID |
template_id | UUID | 模板 ID(如适用) |
message_id | UUID | 消息批处理/请求 ID |
message_name | String | 消息名称 |
message_title | String | 消息标题(仅英语) |
message_contents | String | 截断的消息正文(仅英语) |
_created , _id , _index , _fivetran_synced | 内部使用 | Fivetran 同步元数据 |
注意事项
- 保存/激活后的同步可能需要额外 15-30 分钟才能完成。
- 停用后可能仍会进行最后一次同步。
- 为确保高效的数据同步,我们的系统会自动创建和管理暂存数据集。这些数据集以
fivetran_{两个随机单词}_staging
的模式命名,在处理过程中临时存储数据,然后再集成到您的主架构中。这些暂存数据集对于维护流畅的工作流程至关重要,不应删除,因为它们会被自动重新创建。
从 Databricks 导入事件
将行为事件数据从 Databricks 发送到 OneSignal 以:- 根据用户活动触发旅程
- 基于行为数据个性化消息
- 访问自定义事件(目前处于测试阶段)
- 升级账户计划(免费应用不可用)。
- 具有 SQL 仓库或计算集群的 Databricks 工作区
- 具有适当权限的个人访问令牌
- 包含 Delta Lake 格式行为数据的事件数据表
- Unity Catalog(推荐用于数据治理)
1
创建 Databricks 个人访问令牌
生成个人访问令牌供 OneSignal 访问您的 Databricks 工作区:
- 在您的 Databricks 工作区中导航到用户设置
- 点击开发者选项卡,然后点击访问令牌
- 点击生成新令牌
- 输入注释(如”OneSignal Integration”)并设置过期时间(推荐 90 天)
- 保存生成的令牌(您将在 OneSignal 中需要此令牌)
2
配置 SQL 仓库访问
确保 OneSignal 可以通过 SQL 仓库查询您的事件数据:
- 在您的 Databricks 工作区中导航到 SQL 仓库
- 为 OneSignal 访问选择或创建 SQL 仓库
- 从连接详细信息中记下服务器主机名和 HTTP 路径
- 确保仓库可以访问您的事件数据表
3
授予表权限
向 OneSignal 授予对包含事件数据的表的读取访问权限:
4
在 OneSignal 中添加集成
在 OneSignal 中,前往 数据 > 集成,然后点击 添加集成。选择 Databricks 并提供:
- 服务器主机名:您的 Databricks SQL 仓库主机名
- HTTP 路径:SQL 仓库 HTTP 路径
- 个人访问令牌:在步骤 1 中创建的令牌
- 目录(可选):如果使用 Unity Catalog,则为 Unity Catalog 名称
5
配置事件数据源
指定包含您事件数据的 Databricks 表:
- 数据库/架构:包含事件表的数据库或架构名称
- 表:包含事件记录的表名称(例如
user_events
) - 事件查询:用于过滤或转换事件数据的可选 SQL 查询
- 事件名称/类型(字符串)
- 用户标识符(字符串)
- 事件时间戳(时间戳)
- 其他事件属性
6
测试连接
点击测试连接以验证 OneSignal 可以访问您的 Databricks 工作区并读取事件数据。
事件数据映射
将您的 映射到 OneSignal 的自定义事件格式:OneSignal 字段 | 描述 | 必需 | |
---|---|---|---|
name | event_name | 事件标识符 | 是 |
external_id | user_id | 用户标识符 | 是 |
timestamp | event_timestamp | 事件发生时间 | 否 |
properties | event_data | 否 |
高级配置
Unity Catalog 集成
利用 Unity Catalog 进行受管理的数据访问:Delta Lake 优化
为更好的查询性能优化事件表:- 分区:按日期(
event_date
)分区以加快基于时间的查询 - Z-Ordering:按
user_id
和event_name
进行 Z 排序以提高过滤性能 - Delta Lake 功能:使用液体聚类进行自动优化
流式事件处理
对于实时事件处理,请考虑:- 结构化流:在事件到达时处理事件
- Delta Live Tables:构建稳健的事件处理管道
- Auto Loader:持续摄取新的事件文件
确保您的 SQL 仓库具有足够的计算资源来处理 OneSignal 的查询,而不会影响其他工作负载。