> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Databricks

> 将 OneSignal 消息事件导出到 Databricks，并将 Databricks 行为事件导入到 OneSignal，以触发旅程并个性化消息。

export const PLATFORM_0 = "Databricks"

export const DATA_TYPE_0 = "event table columns"

export const COLUMN_HEADER_0 = "Databricks Column"

export const PROPERTIES_DESCRIPTION_0 = "Additional columns as JSON"

## 概览

OneSignal + Databricks 集成支持**两种流程**：

* **导出**：将 OneSignal 消息事件发送到 Databricks 进行分析和报告。
* **导入**：将 Databricks 中的自定义事件发送到 OneSignal 以触发旅程并个性化活动。

<Info> 导出和导入是分别配置的。您可以只设置其中一个。 </Info>

***

## 将 OneSignal 消息事件导出到 Databricks

将所有消息事件从 OneSignal 同步到您的 Databricks 湖仓，以实现近实时分析和可见性。

**要求**

* [专业计划或更高版本](https://onesignal.com/pricing)
* 启用自定义事件（用于事件导入）
* Databricks 平台：AWS、Azure 或 GCP
* Databricks 计划：高级或更高版本
* Databricks Unity Catalog（推荐用于治理）
* 用于查询的 Databricks SQL 仓库
* Delta Lake 事件表（用于自定义事件导入）

**设置步骤**

### 1. 收集 SQL 仓库详细信息

<Steps>
  <Step title="登录到您的 Databricks 工作区">
    在您的 Databricks 工作区中转到 **SQL 仓库**。
  </Step>

  <Step title="选择您的仓库">
    选择您的仓库并打开**连接详细信息**选项卡。
  </Step>

  <Step title="保存以下详细信息">
    * 服务器主机名
    * 端口
    * HTTP 路径

    <Frame caption="用于 Fivetran 设置的 Databricks SQL 连接详细信息">
      <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1ce7c549df4a383336633d9f258bec12107a895dc9467134d672c12c2c85923f-cluster-databricks.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=1f03dbaa1a6cc6c4bdf804e49755cbf7" alt="用于 Fivetran 设置的 Databricks SQL 连接详细信息" width="1810" height="988" data-path="images/docs/1ce7c549df4a383336633d9f258bec12107a895dc9467134d672c12c2c85923f-cluster-databricks.png" />
    </Frame>
  </Step>
</Steps>

### 2. 创建服务主体

<Steps>
  <Step title="转到服务主体页面">
    转到**工作区设置 > 身份和访问 > 服务主体**。
  </Step>

  <Step title="添加新的服务主体">
    点击**添加服务主体**，然后点击**添加新建**。
  </Step>

  <Step title="命名服务主体">
    为其命名（例如 `onesignal-sync`）。

    <Frame caption="添加服务主体的模态窗口，突出显示'添加新建'选项">
      <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b8eeb211ceb77247f711eb312d3d68d1cb0da10788fd81fd37ae27e929e35cde-Screenshot_2025-04-01_at_9.16.12_PM.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=3bda750f12db717d630220bed24cdb2e" alt="添加服务主体的模态窗口，突出显示'添加新建'选项" width="932" height="392" data-path="images/docs/b8eeb211ceb77247f711eb312d3d68d1cb0da10788fd81fd37ae27e929e35cde-Screenshot_2025-04-01_at_9.16.12_PM.png" />
    </Frame>
  </Step>
</Steps>

### 3. 生成密钥

<Steps>
  <Step title="点击进入创建的主体" />

  <Step title="转到密钥选项卡" />

  <Step title="生成密钥">
    点击**生成密钥**并安全保存。

    <Warning>
      密钥只显示一次—请安全存储。
    </Warning>

    <Frame caption="显示用于 API 身份验证的 OAuth 密钥和客户端 ID 的 Databricks'生成密钥'模态窗口">
      <img src="https://mintcdn.com/onesignal/KSCNwSpBCNSQ8xdF/images/docs/ff24d4d5bf9b21e0cadf67055f1e1a5a4b517b82e9c006520a02b4fd404d259e-Screenshot_2025-03-28_at_4.14.17_PM.png?fit=max&auto=format&n=KSCNwSpBCNSQ8xdF&q=85&s=54eaae1d695bfad59b726ba005ff6f1f" alt="显示用于 API 身份验证的 OAuth 密钥和客户端 ID 的 Databricks'生成密钥'模态窗口" width="746" height="368" data-path="images/docs/ff24d4d5bf9b21e0cadf67055f1e1a5a4b517b82e9c006520a02b4fd404d259e-Screenshot_2025-03-28_at_4.14.17_PM.png" />
    </Frame>
  </Step>
</Steps>

### 4. 分配权限

<Steps>
  <Step title="导航到您的目录并打开权限选项卡" />

  <Step title="点击授权" />

  <Step title="为服务主体分配以下权限">
    * USE CATALOG
    * USE SCHEMA
    * SELECT
    * MODIFY
    * CREATE SCHEMA
    * CREATE TABLE

    <Frame caption="为 Databricks 主体分配权限的屏幕，已选择自定义目录权限。">
      <img src="https://mintcdn.com/onesignal/jFWn5xzleD8du3j6/images/docs/5755c8739fd66a0f35fec57b817d54d202c64ae95bf8219645ba76abdc8fbe0b-Screenshot_2025-04-01_at_9.19.14_PM.png?fit=max&auto=format&n=jFWn5xzleD8du3j6&q=85&s=0964053615467ebd7372edd7beaf33fe" alt="为 Databricks 主体分配权限的屏幕，已选择自定义目录权限" width="1034" height="812" data-path="images/docs/5755c8739fd66a0f35fec57b817d54d202c64ae95bf8219645ba76abdc8fbe0b-Screenshot_2025-04-01_at_9.19.14_PM.png" />
    </Frame>
  </Step>
</Steps>

### 5. 连接 OneSignal

<Steps>
  <Step title="激活集成">
    在 OneSignal 中，导航到**数据 > 集成 > Databricks**。
  </Step>

  <Step title="输入详细信息">
    * 服务器主机名
    * 端口
    * HTTP 路径
    * 目录名称
    * 架构名称
    * 服务主体凭据（ID + 密钥）

    <Frame caption="OneSignal Databricks 配置表单，包含目录、主机名、HTTP 路径和 OAuth 凭据字段。">
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/816a07ed459d3d19910630da0cb52b2075c06d6eaf85af98e969703edab88ad5-Screenshot_2025-03-28_at_4.12.07_PM.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=cd7ba1d76deff9922dc44b25a7528eb2" alt="OneSignal Databricks 配置表单，包含目录、主机名、HTTP 路径和 OAuth 凭据字段" width="718" height="796" data-path="images/docs/816a07ed459d3d19910630da0cb52b2075c06d6eaf85af98e969703edab88ad5-Screenshot_2025-03-28_at_4.12.07_PM.png" />
    </Frame>
  </Step>

  <Step title="配置集成">
    * **同步频率：** 最频繁每 15 分钟一次
    * **数据集/表名：** 预设为 `onesignal_events_<app-id>` 和 `message_events`（可编辑）
    * **事件类型：** 选择要同步的事件—选择全部或只选择您需要的
  </Step>

  <Step title="选择事件">
    选择您希望在 Databricks 目录中接收的事件。

    <Frame caption="OneSignal 事件导出设置屏幕，显示同步状态、数据集配置和选定的消息事件类型。">
      <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1a5ff2af7dc8fc42a91ce70583a03b361fd8a343bc57fd3123f26a5d21dabbf8-Screenshot_2025-04-09_at_11.56.58_AM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=ce7eee0983e2026b1847a4d2a45cbe96" alt="OneSignal 事件导出设置屏幕，显示同步状态、数据集配置和选定的消息事件类型" width="2738" height="1254" data-path="images/docs/1a5ff2af7dc8fc42a91ce70583a03b361fd8a343bc57fd3123f26a5d21dabbf8-Screenshot_2025-04-09_at_11.56.58_AM.png" />
    </Frame>
  </Step>

  <Step title="完成设置">
    点击**保存**并等待成功确认
  </Step>
</Steps>

<Note>
  初始数据同步可能需要 15-30 分钟才能在 BigQuery 中显示。

  在等待期间，通过推送、电子邮件、应用内或 SMS 发送消息以触发选定的事件。
</Note>

### 6. 在 Databricks 中查看数据

1. 在 Databricks 中打开您的**目录**。

2. 同步完成后，您配置的架构将出现。

3. 访问并查询 `message_events` 表。

   <Frame caption="Databricks 目录视图，显示生产架构下的 OneSignal 消息事件表。">
     <img src="https://mintcdn.com/onesignal/tNi1OgLc_p9hiq7_/images/docs/1b59f6eff2070490f194df8a7496fab6cf17f8fc9355cfb7b77c7c076799632e-Screenshot_2025-04-01_at_9.22.01_PM.png?fit=max&auto=format&n=tNi1OgLc_p9hiq7_&q=85&s=c5908557481f292b1a659b4f0ef210ed" alt="Databricks 目录视图，显示生产架构下的 OneSignal 消息事件表" width="854" height="618" data-path="images/docs/1b59f6eff2070490f194df8a7496fab6cf17f8fc9355cfb7b77c7c076799632e-Screenshot_2025-04-01_at_9.22.01_PM.png" />
   </Frame>

4. 点击进入表以预览示例数据。

   <Frame caption="来自 message_events_1 表的示例数据，包含同步的 OneSignal 事件字段。">
     <img src="https://mintcdn.com/onesignal/6v_cVPknFpo5qSVB/images/docs/112f17e471b8e29173429bfbbd4b34fb68923c9f76faa55b06161114249fcaab-Screenshot_2025-04-01_at_9.22.08_PM.png?fit=max&auto=format&n=6v_cVPknFpo5qSVB&q=85&s=a853fe144d238a24d86b5f989261f2be" alt="来自 message_events_1 表的示例数据，包含同步的 OneSignal 事件字段" width="1196" height="374" data-path="images/docs/112f17e471b8e29173429bfbbd4b34fb68923c9f76faa55b06161114249fcaab-Screenshot_2025-04-01_at_9.22.08_PM.png" />
   </Frame>

<Info>
  如果您遇到缺少架构、权限错误或格式错误的事件等问题，请联系 `support@onesignal.com`。
</Info>

## 消息事件和属性

### 消息事件类型

**属性：** `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.impression`     | 应用内消息已显示。       |
|       应用内点击      |       `message.iam.clicked`      | 应用内消息已点击。       |
|      应用内页面查看     |   `message.iam.page_displayed`   | 应用内页面已显示。       |
|       邮件已发送      |       `message.email.sent`       | 邮件已送达。          |
|       邮件已接收      |     `message.email.received`     | 邮件已被接收方邮件服务器接受。 |
|       邮件已打开      |      `message.email.opened`      | 用户已打开邮件。        |
|      邮件链接已点击     |      `message.email.clicked`     | 邮件中的链接已点击。      |
|      邮件已取消订阅     |   `message.email.unsubscribed`   | 接收方已取消订阅。       |
|    邮件已标记为垃圾邮件    | `message.email.reported_as_spam` | 用户将您的邮件标记为垃圾邮件。 |
|       邮件已退回      |      `message.email.bounced`     | 由于永久性送达失败而退回。   |
|       邮件失败       |      `message.email.failed`      | 送达失败。           |
|       邮件已抑制      |    `message.email.suppressed`    | 由于抑制列表而被抑制。     |
|       短信已发送      |        `message.sms.sent`        | 短信已发送。          |
|       短信已送达      |      `message.sms.delivered`     | 短信成功送达。         |
|       短信失败       |       `message.sms.failed`       | 短信送达失败。         |
|       短信未送达      |     `message.sms.undelivered`    | 短信被拒绝或无法到达。     |

### 事件数据架构

对于用户生成的每个消息事件，以下元数据将附加到记录中。

|                       列名称                       |     类型    | 描述                                 |
| :---------------------------------------------: | :-------: | ---------------------------------- |
|                    `event_id`                   |    UUID   | 事件的唯一标识符                           |
|                `event_timestamp`                | Timestamp | 事件发生时间                             |
|                   `event_kind`                  |   String  | [事件类型](#message-event-kinds)       |
|            `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  | 截断的消息正文（仅英语）                       |
|                 `failure_reason`                |   String  | 失败原因（适用于推送失败和邮件失败事件）               |
| `_created`, `_id`, `_index`, `_fivetran_synced` |   *内部使用*  | Fivetran 同步元数据                     |

### 注意事项

* 保存/激活后的同步可能需要额外 15-30 分钟才能完成。
* 停用后可能仍会进行最后一次同步。
* 为确保高效的数据同步，我们的系统会自动创建和管理暂存数据集。这些数据集以 `fivetran_{两个随机单词}_staging` 的模式命名，在处理过程中临时存储数据，然后再集成到您的主架构中。这些暂存数据集对于维护流畅的工作流程至关重要，不应删除，因为它们会被自动重新创建。

***

## 从 Databricks 导入事件

将行为事件数据从 Databricks 发送到 OneSignal 以：

* 根据用户活动触发旅程
* 基于行为数据个性化消息

**要求**

* 访问自定义事件（目前处于测试阶段）
* [升级账户计划](https://onesignal.com/pricing)（免费应用不可用）。

- 具有 SQL 仓库或计算集群的 **Databricks 工作区**
- 具有适当权限的**个人访问令牌**
- 包含 Delta Lake 格式行为数据的**事件数据表**
- **Unity Catalog**（推荐用于数据治理）

**设置步骤**

<Steps>
  <Step title="创建 Databricks 个人访问令牌">
    生成个人访问令牌供 OneSignal 访问您的 Databricks 工作区：

    1. 在您的 Databricks 工作区中导航到**用户设置**
    2. 点击**开发者**选项卡，然后点击**访问令牌**
    3. 点击**生成新令牌**
    4. 输入注释（如"OneSignal Integration"）并设置过期时间（推荐 90 天）
    5. 保存生成的令牌（您将在 OneSignal 中需要此令牌）
  </Step>

  <Step title="配置 SQL 仓库访问">
    确保 OneSignal 可以通过 SQL 仓库查询您的事件数据：

    1. 在您的 Databricks 工作区中导航到 **SQL 仓库**
    2. 为 OneSignal 访问选择或创建 SQL 仓库
    3. 从连接详细信息中记下**服务器主机名**和 **HTTP 路径**
    4. 确保仓库可以访问您的事件数据表
  </Step>

  <Step title="授予表权限">
    向 OneSignal 授予对包含事件数据的表的读取访问权限：

    ```sql theme={null}
    -- 对于启用了 Unity Catalog 的工作区
    GRANT SELECT ON TABLE catalog.schema.event_table TO `onesignal@yourdomain.com`;

    -- 对于 Hive 元存储表
    GRANT SELECT ON TABLE database.event_table TO `onesignal@yourdomain.com`;
    ```
  </Step>

  <Step title="在 OneSignal 中添加集成">
    在 OneSignal 中，前往 **数据 > 集成**，然后点击 **添加集成**。

    选择 **Databricks** 并提供：

    * **服务器主机名**：您的 Databricks SQL 仓库主机名
    * **HTTP 路径**：SQL 仓库 HTTP 路径
    * **个人访问令牌**：在步骤 1 中创建的令牌
    * **目录**（可选）：如果使用 Unity Catalog，则为 Unity Catalog 名称
  </Step>

  <Step title="配置事件数据源">
    指定包含您事件数据的 Databricks 表：

    * **数据库/架构**：包含事件表的数据库或架构名称
    * **表**：包含事件记录的表名称（例如 `user_events`）
    * **事件查询**：用于过滤或转换事件数据的可选 SQL 查询

    您的事件表应包含以下列：

    * 事件名称/类型（字符串）
    * 用户标识符（字符串）
    * 事件时间戳（时间戳）
    * 其他事件属性
  </Step>

  <Step title="测试连接">
    点击**测试连接**以验证 OneSignal 可以访问您的 Databricks 工作区并读取事件数据。
  </Step>
</Steps>

### 事件数据映射

将您的 {PLATFORM_0} {DATA_TYPE_0} 映射到 OneSignal 的自定义事件格式：

| OneSignal 字段  | {COLUMN_HEADER_0} | 描述                         | 必需 |
| ------------- | ----------------- | -------------------------- | -- |
| `name`        | `event_name`      | 事件标识符                      | 是  |
| `external_id` | `user_id`         | 用户标识符                      | 是  |
| `timestamp`   | `event_timestamp` | 事件发生时间                     | 否  |
| `properties`  | `event_data`      | {PROPERTIES_DESCRIPTION_0} | 否  |

### 高级配置

#### Unity Catalog 集成

利用 Unity Catalog 进行受管理的数据访问：

```sql theme={null}
SELECT
  event_name,
  user_id,
  event_timestamp,
  to_json(
    named_struct(
      'product_id', product_id,
      'purchase_amount', purchase_amount,
      'category', category
    )
  ) as payload
FROM catalog.schema.user_events
WHERE event_timestamp >= current_timestamp() - INTERVAL 7 DAYS
```

### Delta Lake 优化

为更好的查询性能优化事件表：

* **分区**：按日期（`event_date`）分区以加快基于时间的查询
* **Z-Ordering**：按 `user_id` 和 `event_name` 进行 Z 排序以提高过滤性能
* **Delta Lake 功能**：使用液体聚类进行自动优化

#### 流式事件处理

对于实时事件处理，请考虑：

* **结构化流**：在事件到达时处理事件
* **Delta Live Tables**：构建稳健的事件处理管道
* **Auto Loader**：持续摄取新的事件文件

<Warning>
  确保您的 SQL 仓库具有足够的计算资源来处理 OneSignal 的查询，而不会影响其他工作负载。
</Warning>

***

## 常见问题

### 为什么我看到具有相同内容的不同消息 ID？

当同一消息发送多次时会发生这种情况，可能通过事务流程或跨多个发送重用的消息模板。

### OneSignal 从 Databricks 同步事件的频率如何？

OneSignal 根据您配置的计划同步事件数据，最小间隔为 15 分钟。

### 我可以使用 Databricks 笔记本进行事件处理吗？

是的，您可以使用笔记本处理和准备事件数据，然后通过 OneSignal 可以查询的表公开它。

### 事件查询的成本优化如何？

考虑使用无服务器 SQL 仓库以获得经济高效的按需计算，它会根据查询负载自动扩展。

***