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

# Azure Synapse

> 将 Azure Synapse 的自定义事件同步到 OneSignal，以基于用户行为触发自动化旅程和个性化消息活动。

export const PLATFORM_0 = "Azure Synapse"

export const DATA_TYPE_0 = "event data"

export const COLUMN_HEADER_0 = "Synapse Column"

export const PROPERTIES_DESCRIPTION_0 = "Event metadata as JSON string"

## 概述

OneSignal + Azure Synapse 集成可以将您的 Azure Synapse Analytics 工作区中的自定义事件同步到 OneSignal，以基于用户行为触发自动化消息活动和旅程。

Azure Synapse Analytics 是微软基于云的分析服务，结合了数据集成、数据仓库和分析功能。

***

## 要求

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

### Azure Synapse 要求

* 具有 SQL 池访问权限的 **Azure Synapse 工作区**
* 具有适当权限的**数据库用户**
* 包含结构化行为数据的**事件表**
* OneSignal IP 地址的**防火墙访问权限**

***

## 设置

<Steps>
  <Step title="为 OneSignal 创建专用登录">
    使用强密码和唯一密码创建专用登录和用户账户：

    ```sql theme={null}
    USE <your-database>;

    -- Create census login with the ability to sign in with a password
    CREATE LOGIN CENSUS WITH PASSWORD = '<strong-unique-password>';

    -- Create user for the login
    CREATE USER CENSUS FOR LOGIN CENSUS;

    -- Give the census user the ability to connect to database
    GRANT CONNECT TO CENSUS;
    ```

    <Info>
      将 `<your-database>` 替换为包含事件数据的实际数据库名称。
    </Info>
  </Step>

  <Step title="授予读取权限">
    为您的事件数据提供只读访问权限：

    ```sql theme={null}
    -- Give the census user the ability to read all tables
    EXEC sp_addrolemember 'db_datareader', CENSUS;

    -- Grant census user ability to read schema and data
    -- Run this for each schema you intend OneSignal to access
    GRANT SELECT, VIEW DEFINITION ON SCHEMA::<your-schema> TO CENSUS;
    ```

    <Info>
      将 `<your-schema>` 替换为包含事件数据的实际模式名称。为每个您希望 OneSignal 访问的模式重复此命令。
    </Info>
  </Step>

  <Step title="配置防火墙访问">
    配置 Azure Synapse 防火墙以允许 OneSignal IP 地址。

    使用 Windows Azure 管理门户或在主数据库上运行 **sp\_set\_firewall\_rule**：

    ```sql theme={null}
    -- Example: Add firewall rule for OneSignal IP range
    EXEC sp_set_firewall_rule
        N'OneSignal Access',
        'ONESIGNAL_IP_START',
        'ONESIGNAL_IP_END';
    ```

    <Warning>
      请联系 OneSignal 支持获取您所在地区的当前 IP 地址范围。
    </Warning>
  </Step>

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

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

    * **主机：** 您的 Synapse SQL 端点主机名
    * **端口：** 1433（默认值）
    * **数据库：** 您的数据库名称
    * **用户名：** `CENSUS`
    * **密码：** 步骤 1 中的密码
  </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 Azure Synapse event table
CREATE TABLE analytics.user_events (
    event_id BIGINT IDENTITY(1,1) PRIMARY KEY,
    event_name NVARCHAR(100) NOT NULL,
    user_id NVARCHAR(255) NOT NULL,
    event_timestamp DATETIME2 DEFAULT GETUTCDATE(),
    event_data NVARCHAR(MAX),
    session_id NVARCHAR(255),
    device_type NVARCHAR(50)
)
WITH (DISTRIBUTION = HASH(user_id), CLUSTERED COLUMNSTORE INDEX);
```

### SQL 查询模式

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

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

***

## Azure 特定功能

### 分布式架构

* 按 `user_id` 分布的事件，以获得最优查询性能
* 用于分析工作负载的聚集列存储索引
* 用于大规模事件数据的大规模并行处理 (MPP)

### 与 Azure 生态系统集成

* 连接到 Azure Data Factory 以实现自动化事件管道
* 与 Azure Event Hubs 集成实现实时事件流
* 利用 Azure Active Directory 进行身份验证

***

## 高级网络配置

OneSignal 可以成功连接到使用高级网络控制的 Azure Synapse 实例，包括区域限制、IP 地址允许列表或 SSH 隧道。

有关配置网络访问的更多信息，请联系您的 Azure Synapse 管理员或 OneSignal 支持。

***

## 限制

* 基于 SQL Server JDBC 驱动程序连接协议
* 需要为 OneSignal IP 地址设置显式防火墙规则
* 复杂查询可能影响 SQL 池性能和成本
* JSON 操作需要仔细的索引以获得最佳性能

***

## 常见问题

### 我可以连接到多个 Azure Synapse 模式吗？

是的，您可以通过为每个包含事件数据的模式运行 `GRANT SELECT, VIEW DEFINITION ON SCHEMA::<schema>` 语句来授予 CENSUS 用户访问多个模式的权限。

### 如何为 OneSignal 配置防火墙访问权限？

使用 Azure 管理门户或 `sp_set_firewall_rule` 添加 OneSignal 的 IP 地址。请联系 OneSignal 支持获取当前的 IP 范围。

### Azure Synapse 和 SQL Server 集成有什么区别？

Azure Synapse 使用相同的 SQL Server JDBC 驱动程序，但包含分布式架构功能，并需要特定的防火墙配置以进行云访问。