> ## 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.

# Snowflake（旧版）

> 从 Snowflake 同步自定义事件到 OneSignal，以根据用户行为触发自动化 Journey 和个性化消息推送活动。

export const PLATFORM_0 = "Snowflake"

export const DATA_TYPE_0 = "event data"

export const COLUMN_HEADER_0 = "Snowflake Column"

export const PROPERTIES_DESCRIPTION_0 = "Event metadata as VARIANT/JSON"

<Frame caption="OneSignal Snowflake 集成概述">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4bd3285-onesignal-snowflake-integration-2.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=c41bc1d77c30e6c282bb0bfdbcd67767" width="1280" height="720" data-path="images/docs/4bd3285-onesignal-snowflake-integration-2.png" />
</Frame>

***

## 概述

OneSignal + Snowflake 集成支持两种强大的数据管道：

* **导出**：自动将 OneSignal 的消息事件数据（推送、电子邮件、短信、应用内消息）发送到 Snowflake 进行分析和报告。
* **导入**：将 Snowflake 数据集中的自定义用户事件同步到 OneSignal，以触发自动化 Journey 和个性化消息。

这些集成使您可以完全控制用户参与度数据——支持高级分析和实时行为驱动的消息推送。

***

## 将 OneSignal 事件导出到 Snowflake

将消息性能和参与度事件（例如发送、打开、点击）发送到 Snowflake，以便：

* 构建自定义仪表板和报告
* 跟踪跨渠道的投递和参与度趋势
* 将 OneSignal 数据与其他业务数据结合进行分析

**要求**

* OneSignal **专业版计划**（免费应用不可用）。
* [Snowflake 账户](https://docs.snowflake.com/en/user-guide/getting-started-tutorial)
* 确保您的 Snowflake 账户具有 `IMPORT SHARE` 和 `CREATE DATABASE` 角色。
  * 我们建议使用 `ACCOUNTADMIN` 角色来接受共享。

**设置步骤**

### 1. 注册

要激活 Snowflake 集成，您需要通过 [OneSignal Marketplace 列表](https://app.snowflake.com/marketplace/listing/GZ2FQZLH2NP/onesignal-message-events-data?search=onesignal\&originTab=provider\&providerName=OneSignal\&profileGlobalName=GZSTZLH2MW)请求访问消息事件数据。之后我们将与您的团队联系以获取更多信息。

### 2. 提供账户信息

与您的团队联系后，您需要向我们提供一些详细信息，以便我们与您共享数据。我们需要您的 **Snowflake 账户 ID** 和 **Snowflake 组织 ID**。获取该信息的最简单方法是点击"复制账户标识符"按钮（如下所示）。

<Info>
  您应该通过 [OneSignal Marketplace 列表](https://app.snowflake.com/marketplace/listing/GZ2FQZLH2NP/onesignal-message-events-data?search=onesignal\&originTab=provider\&providerName=OneSignal\&profileGlobalName=GZSTZLH2MW)与我们联系。但是，如果您对提供账户信息有任何其他疑问，可以发送电子邮件至 `snowflake-data-sharing@onesignal.com`
</Info>

<Frame caption="复制 Snowflake 账户标识符">
  <img src="https://mintcdn.com/onesignal/4HyuQPBpu-4xjmQC/images/docs/cf472c3-Screen_Shot_2023-06-27_at_4.08.19_PM.png?fit=max&auto=format&n=4HyuQPBpu-4xjmQC&q=85&s=ad89f70c336cfa9fc66849021cdab551" width="1554" height="620" data-path="images/docs/cf472c3-Screen_Shot_2023-06-27_at_4.08.19_PM.png" />
</Frame>

一旦您被接受加入该计划，请留意以下几项：

* OneSignal 发来的欢迎您加入该计划的电子邮件
* Snowflake 发来的通知数据共享已完成的电子邮件

<Frame caption="Snowflake 数据共享通知电子邮件">
  <img src="https://mintcdn.com/onesignal/jBdBk5XvQR5eKOks/images/docs/7219faf-Untitled.png?fit=max&auto=format&n=jBdBk5XvQR5eKOks&q=85&s=3c4af6e7ba0f66836b5a2e91689f282e" width="1238" height="1078" data-path="images/docs/7219faf-Untitled.png" />
</Frame>

### 3. 在 Snowflake 中接受数据共享

收到 Snowflake 发来的数据共享完成通知电子邮件后，您应该能够登录 Snowflake 应用并接受数据共享。

导航至**数据** → **私有共享**，您应该能够看到新的私有共享列表。点击 **Get** 后，您的数据将开始复制到您的区域。

<Frame caption="Snowflake 私有共享界面">
  <img src="https://mintcdn.com/onesignal/RWtLFPeffHrC81wI/images/docs/a8dfc31-Untitled_1.png?fit=max&auto=format&n=RWtLFPeffHrC81wI&q=85&s=cb692bad2c9be897bf1c40185911e594" width="1086" height="516" data-path="images/docs/a8dfc31-Untitled_1.png" />
</Frame>

**注意**：如果 **Get** 按钮不可用但有 **Request** 按钮，则表示尝试进行共享的角色权限不包括 `CREATE DATABASE` 或 `IMPORT SHARE`。我们建议切换到 `ACCOUNTADMIN` 角色。

数据复制需要一些时间。数据可用后，Snowflake 将发送另一封电子邮件。您应该会看到如下所示的对话框

<Frame caption="数据复制状态对话框">
  <img src="https://mintcdn.com/onesignal/YOTSrtBSoqdrJ37A/images/docs/4d78360-Untitled_2.png?fit=max&auto=format&n=YOTSrtBSoqdrJ37A&q=85&s=406c4f7f2884deea338e690e14d76e44" width="664" height="886" data-path="images/docs/4d78360-Untitled_2.png" />
</Frame>

数据准备就绪后，您的列表应该会显示一个新的 **Get** 按钮。点击 **Get** 按钮，您将看到一个新的对话框

<Frame caption="数据库配置对话框">
  <img src="https://mintcdn.com/onesignal/3zq1PvSaqvUE2bIx/images/docs/28ba7ca-Untitled_3.png?fit=max&auto=format&n=3zq1PvSaqvUE2bIx&q=85&s=55e9e64a31cd20e552196d80b0fe7196" width="1320" height="1314" data-path="images/docs/28ba7ca-Untitled_3.png" />
</Frame>

将数据库和数据库角色的名称设置为您喜欢的名称。然后点击 **Get**

<Frame caption="数据共享设置完成">
  <img src="https://mintcdn.com/onesignal/tc0EvmtSSX56SX0c/images/docs/8dae239-Untitled_4.png?fit=max&auto=format&n=tc0EvmtSSX56SX0c&q=85&s=6ee68952c4a8e3c2cb430ba2e20ec136" width="694" height="698" data-path="images/docs/8dae239-Untitled_4.png" />
</Frame>

<Check>
  完成！数据现在正在从 OneSignal 同步到 Snowflake。同步频率设置为每 24 小时一次，因此初始数据可能要到第二天才能获得。
</Check>

## 事件和属性

Snowflake Marketplace 上可用数据的概述

### 消息事件数据

有关更多详细信息，请参阅[事件流](./event-streams#event-data)。

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

| 列名                           | 类型              | 描述                                                        | 示例                                                    |
| ---------------------------- | --------------- | --------------------------------------------------------- | ----------------------------------------------------- |
| event\_id                    | UUID            | 表示事件的唯一 ID                                                | `dc76df03-287c-403a-aabd-b2d4fe44e5c6`                |
| event\_kind                  | string          | 发生的事件类型。事件类型列表可以在[此处](./snowflake#message-event-kinds)找到。 | `message.email.opened`                                |
| event\_impression\_timestamp | unix\_timestamp | OneSignal 处理事件的时间                                         | `1684951205`                                          |
| subscription\_id             | UUID            | 表示设备/订阅的唯一 ID                                             | `6e8b6978-75a4-4882-878c-2d15a78c2409`                |
| subscription\_language       | string          | 此订阅的语言                                                    | `en`                                                  |
| subscription\_timezone       | integer         | 此订阅的指定时区                                                  | `-25200`                                              |
| subscription\_device\_type   | string          | 此订阅使用的设备类型。                                               | `SMS`                                                 |
| onesignal\_id                | UUID            | 产生展示的用户的 onesignal\_id                                    | `dc76df03-287c-403a-aabd-b2d4fe44e5c6`                |
| external\_id                 | string          | 产生展示的用户的 external\_id                                     | `MyExternalId`                                        |
| message\_id                  | UUID            | 表示消息的唯一 ID                                                | `dc76df03-287c-403a-aabd-b2d4fe44e5c6`                |
| message\_name                | string          | 通知/消息的人类可读 ID                                             | `Campaign 1`                                          |
| message\_title               | string          | 通知/消息的标题。*目前仅限英语*                                         | `Bonus 50 coins when you play!`                       |
| message\_body                | string          | 消息的正文。（截断）*目前仅限英语。*                                       | `Play against your friends and earn an additional...` |

### 消息事件类型

有关更多详细信息，请参阅[事件流](./event-streams#event-data)。

消息事件是我们在 Snowflake Marketplace 上提供的第一类数据。如果您需要其他类别的数据，请通过 `snowflake-data-sharing@onesignal.com` 与我们联系！

### 数据保留

通过 Snowflake 从 OneSignal 共享的数据保留 30 天。为确保在此时间范围之外保留数据，我们建议您将相关数据复制到您自己的表中。

***

## 从 Snowflake 导入事件

将行为事件数据从 Snowflake 发送到 OneSignal，以便：

* 根据用户活动触发 Journey
* 根据行为数据个性化消息

**要求**

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

- 具有数据仓库访问权限的 **Snowflake 账户**
- 存储在 Snowflake 表或视图中的**事件数据**
- 从 OneSignal 到您的 Snowflake 实例的**网络连接**
- 具有适当权限的**用户凭证**

**设置步骤**

<Steps>
  <Step title="为 OneSignal 创建专用角色">
    按照 Snowflake 最佳实践创建角色层次结构：

    ```sql theme={null}
    -- Create a role for the census user
    CREATE ROLE CENSUS_ROLE;

    -- Ensure the sysadmin role inherits any privileges the census role is granted
    GRANT ROLE CENSUS_ROLE TO ROLE SYSADMIN;
    ```
  </Step>

  <Step title="创建专用数据仓库">
    为 OneSignal 操作创建经济高效的数据仓库：

    ```sql theme={null}
    -- Create a warehouse for the census role, optimizing for cost over performance
    CREATE WAREHOUSE CENSUS_WAREHOUSE WITH
        WAREHOUSE_SIZE = XSMALL
        AUTO_SUSPEND = 60
        AUTO_RESUME = TRUE
        INITIALLY_SUSPENDED = FALSE;

    GRANT USAGE ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
    GRANT OPERATE ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
    GRANT MONITOR ON WAREHOUSE CENSUS_WAREHOUSE TO ROLE CENSUS_ROLE;
    ```
  </Step>

  <Step title="创建用户并授予权限">
    创建 OneSignal 用户并授予对事件数据的访问权限：

    ```sql theme={null}
    -- Create the census user
    CREATE USER CENSUS WITH
        DEFAULT_ROLE = CENSUS_ROLE
        DEFAULT_WAREHOUSE = CENSUS_WAREHOUSE
        PASSWORD = '<strong-unique-password>';

    GRANT ROLE CENSUS_ROLE TO USER CENSUS;

    -- Grant access to your event data (replace with your actual database/schema)
    GRANT USAGE ON DATABASE "<your-database>" TO ROLE CENSUS_ROLE;
    GRANT USAGE ON SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON ALL TABLES IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON FUTURE TABLES IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON ALL VIEWS IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    GRANT SELECT ON FUTURE VIEWS IN SCHEMA "<your-database>"."<your-schema>" TO ROLE CENSUS_ROLE;
    ```
  </Step>

  <Step title="创建记账数据库（高级同步引擎）">
    为 OneSignal 的同步状态管理创建私有数据库：

    ```sql theme={null}
    -- Create a private bookkeeping database
    CREATE DATABASE "CENSUS";
    GRANT ALL PRIVILEGES ON DATABASE "CENSUS" TO ROLE CENSUS_ROLE;

    CREATE SCHEMA "CENSUS"."CENSUS";
    GRANT ALL PRIVILEGES ON SCHEMA "CENSUS"."CENSUS" TO ROLE CENSUS_ROLE;
    GRANT CREATE STAGE ON SCHEMA "CENSUS"."CENSUS" TO ROLE CENSUS_ROLE;
    ```

    <Warning>
      如果使用基本同步引擎或只读模式，请跳过此步骤。
    </Warning>
  </Step>

  <Step title="配置身份验证">
    设置密钥对身份验证（推荐）以增强安全性：

    1. 按照 [Snowflake 文档](https://docs.snowflake.com/en/user-guide/key-pair-auth)生成公钥/私钥对
    2. 在 Snowflake 用户上配置公钥
    3. 在 OneSignal 的连接设置中使用私钥

    或者，您可以使用密码身份验证（已弃用 - 将于 2025 年 11 月被阻止）。
  </Step>

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

    选择 **Snowflake** 并提供以下连接详细信息：

    * **账户名称：** 您的 Snowflake 账户标识符（例如 `abc123.us-east-1`）
    * **数据仓库：** `CENSUS_WAREHOUSE`
    * **用户：** `CENSUS`
    * **数据库：** 您的事件数据数据库名称
    * **架构：** 您的事件数据架构名称
    * **身份验证：** 密钥对（提供私钥和可选密码短语）
  </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} | 否  |

#### 示例事件表架构

```sql theme={null}
-- Example Snowflake event table
CREATE TABLE analytics.user_events (
    event_id STRING,
    event_name STRING NOT NULL,
    user_id STRING NOT NULL,
    event_timestamp TIMESTAMP_TZ DEFAULT CURRENT_TIMESTAMP(),
    event_properties VARIANT,
    session_id STRING,
    device_type STRING
);
```

#### SQL 查询模式

编写自定义 SQL 查询以转换您的事件数据：

```sql theme={null}
-- Example: Recent high-value events
SELECT
    event_name,
    user_id,
    event_timestamp,
    event_properties
FROM analytics.user_events
WHERE event_timestamp >= DATEADD(day, -7, CURRENT_TIMESTAMP())
    AND event_properties:value::NUMBER > 100
ORDER BY event_timestamp DESC;
```

### 高级配置

#### 管理数据仓库成本

* 使用 X-Small 数据仓库大小以优化成本
* 配置自动挂起（60 秒）和自动恢复
* 在非高峰时段安排同步
* 考虑与其他批处理系统共享数据仓库

#### 实时同步支持

要进行实时事件处理，请在事件表上启用变更跟踪：

```sql theme={null}
ALTER TABLE "analytics"."user_events" SET CHANGE_TRACKING = TRUE;
```

#### 网络安全

如果使用 Snowflake 的允许 IP 网络策略，请将 OneSignal 的 IP 地址添加到您的允许列表。请联系 OneSignal 支持以获取当前的 IP 范围。

***

## 限制

* 复杂的分析查询可能会影响数据仓库性能和成本
* 用户/密码身份验证将于 2025 年 11 月弃用
* CENSUS 数据库仅保留用于 OneSignal 操作

***

## 断开与 OneSignal 的数据共享

请发送电子邮件至 `snowflake-data-sharing@onesignal.com` 以请求停用您与 OneSignal 的数据共享。

***

## 常见问题

### 我应该使用哪种身份验证方法？

使用**密钥对身份验证**（推荐）。从 2025 年 11 月开始，Snowflake 将阻止用户/密码身份验证。

### 我可以使用现有的数据仓库吗？

可以，您可以与其他批处理系统（如 dbt 或 Fivetran）共享数据仓库以优化成本。确保数据仓库具有足够的容量来满足您的事件处理需求。

### 如何优化成本？

* 使用 X-Small 数据仓库大小
* 配置激进的自动挂起（60 秒）
* 在非高峰时段安排同步
* 使用每小时/每天同步而不是连续同步

***