# 将 MQTT 数据写入到 Azure SQL Database

[Azure SQL Database](https://azure.microsoft.com/en-us/products/azure-sql/database) 是微软提供的一种全托管关系型数据库服务，具备高可用性、安全性和可扩展性，专门用于存储结构化数据。EMQX 平台与 Azure SQL Database 的集成，使用户能够可靠地存储和管理 MQTT 数据，并支持实时分析、报表和后续处理。通过这一集成，EMQX 可以作为 MQTT 设备与 Azure SQL Database 之间的桥梁，实现 IoT 遥测数据的无缝写入，同时也便于与其他 Azure 服务（如 Power BI、Azure Synapse、Logic Apps）进行集成，用于高级分析、可视化和自动化工作流。

本页提供了 EMQX Cloud 与 Azure SQL Database 数据集成的全面介绍，并提供了创建和验证数据集成的实用指导。

## 工作原理

Azure SQL Database 数据集成是 EMQX 平台的开箱即用特性，它结合了 EMQX 的实时设备连接与消息处理能力，以及 Azure SQL Database 的结构化存储和查询能力。借助 EMQX 内置的 [规则引擎](https://docs.emqx.com/zh/cloud/latest/data_integration/rules.html)，用户无需编写复杂代码，即可将 MQTT 消息进行转换、丰富并存储到 Azure SQL Database。

完整流程如下：

1. **物联网设备发布消息：** 设备通过 MQTT 协议连接到 EMQX，并将遥测数据、状态更新或传感器读数发布到特定主题。每条消息进入后都会触发规则引擎进行处理。
2. **规则引擎处理消息：** EMQX 的 SQL 风格规则引擎会根据定义的规则对消息进行评估。消息可以被过滤、转换，或添加额外上下文（如时间戳、设备元数据）后再存储。
3. **写入 Azure SQL Database：** 按照规则配置，处理后的消息会被插入或更新到 Azure SQL Database 的指定表和列中。通过 SQL 模板，消息字段可以精准映射到数据库字段，保证存储的结构化与一致性。
4. **数据存储与使用：** 一旦数据写入 Azure SQL Database，就可以立即进行查询、报表或分析。同时，它也能无缝集成到 Power BI、Synapse Analytics 和 Logic Apps 等服务中，用于可视化、自动化工作流和高级处理。

借助这一集成，企业能够构建完整托管的 IoT 数据管道，实现实时数据采集、结构化存储和无缝分析，从而快速获取洞察，提升运营智能。

## 功能与优势

EMQX 平台与 Azure SQL Database 的数据集成，能为业务带来以下功能与好处：

**实时 IoT 数据接入：** EMQX 可高频处理并转发 MQTT 消息到 Azure SQL Database，实现即时存储和实时可用，用于监控、分析或业务流程。

**结构化可查询存储：** Azure SQL Database 将 IoT 数据存储在关系型表中，支持模式、约束和索引。结构化存储便于精确查询、报表和历史分析，帮助更轻松地获取有价值的洞察。

**预处理与数据转换：** EMQX 的 SQL 规则引擎支持在数据写入前进行过滤、丰富、聚合或重格式化，确保只有有价值且结构化的数据被存储，降低后续处理的复杂度。

**可扩展与高性能：** EMQX 与 Azure SQL Database 都支持水平和垂直扩展。EMQX 能处理百万级 MQTT 连接，而 Azure SQL Database 能自动扩展计算和存储资源，以适应数据增长而不损失性能。

## 开始之前

本节介绍了在 EMQX Cloud 中创建 Azure SQL Database 数据集成之前需要做的准备工作。

### 前提条件

* 理解 [规则](https://docs.emqx.com/zh/cloud/latest/data_integration/rules.html)。
* 理解 [数据集成](https://docs.emqx.com/zh/cloud/latest/data_integration/introduction.html)。

### 配置网络

<!--@include: ./network-setting.md-->

### 配置 Azure SQL Database

本节介绍如何创建 Azure SQL Database 实例用于存储 MQTT 消息。如果你已有数据库，可以跳过此步骤，直接进入专用终结点的创建。

1. 在 Azure 门户中，进入 **Azure SQL | SQL databases** 服务页面，选择 **创建**。
2. 在 **创建 SQL 数据库** 界面的 **基本** 页签中：

   * **订阅**：选择目标订阅。
   * **资源组**：选择已有资源组或点击 **新建** 新建。
   * **数据库名称**：输入数据库名称（本文档使用 `emqx`）。
   * **服务器**：选择 **新建** 并填写表单：

     * **服务器名称**：输入服务器名称。
     * **位置**：选择与 EMQX 部署相同的区域。
     * **身份验证方法**：选择 **使用 SQL 身份验证**。
     * **使用 SQL 身份验证 / 密码**：输入符合 Azure 要求的用户名和密码，并记录下来，后续连接和创建连接器时会用到。
3. 根据需要配置剩余选项。
4. 点击 **完成** 创建 SQL 服务器。
5. 回到 **创建 SQL 数据库** 界面，点击 **下一步：网络** 继续。

### 创建专用终结点

为了安全访问 Azure SQL Database，需要创建一个专用终结点。

* 如果已有数据库：进入 **概述 → 属性 → 网络 → 专用 → + 添加专用终结点**。
* 如果是新建数据库：在 **网络** 标签页中，**连接方法** 选择 **专用连接点** 后点击 **+ 添加专用终结点**。

1. 在 **创建专用终结点** 表单中，选择订阅、资源组、虚拟网络和子网。
2. 在 DNS 配置中，保持 **与专用 DNS 区域集成** 为 **是**，并使用默认 **专用 DNS 区域**。
3. 点击确定，创建完成后状态应显示 **成功**。
4. 记录 **IP 地址** 和 **FQDN**（路径：**专用终结点 → 设置 → DNS 配置**）。

### 创建数据库与数据表

本节介绍如何连接到 Azure SQL Database 并创建存储 MQTT 数据的表。可选择多种方式连接数据库（详细见 [Azure 官方文档](https://learn.microsoft.com/zh-cn/azure/azure-sql/database/design-first-database-tutorial?view=azuresql&tabs=queryeditor)）。本文演示在 Azure 门户中通过 **查询编辑器** 创建表。

1. 按照 [此文档](https://learn.microsoft.com/zh-cn/azure/azure-sql/database/design-first-database-tutorial?view=azuresql&tabs=queryeditor#create-a-server-level-ip-firewall-rule) 创建服务器级别的 IP 防火墙规则。
2. 在 SQL 数据库 **概述** 页面左侧选择 **查询编辑器 (预览)**。
3. 使用之前设置的登录凭据登录数据库。
4. 执行以下 SQL 命令创建 `temp_hum` 表，用于存储设备上报的温湿度数据：

```sql
 CREATE TABLE temp_hum(
   client_id VARCHAR(64) NULL,
   temp NVARCHAR(100) NULL,
   hum NVARCHAR(100) NULL,
   up_timestamp DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
 );
 GO;
```

## 创建 Microsoft SQL Server 连接器

在创建数据集成规则之前，需要先创建一个 Microsoft SQL Server 连接器来访问 Azure SQL Database。

1. 在部署菜单中选择 **数据集成**，在数据持久化服务分类下选择 Microsoft SQL Server 服务。如果您已经创建了其他的连接器，点击**新建连接器**，然后在数据持久化服务分类下选择 Microsoft SQL Server 服务。

2. **连接器名称**：系统将自动生成一个连接器的名称。
3. 输入连接信息：

   * **服务器地址**：服务器 IP 地址和端口（默认端口 1433）。
   * **数据库名字**：输入已创建的数据库名（如 `emqx`）。
   * **用户名**：格式为 `username@FQDN`。例如用户名为 `sa`，FQDN 为 `emqx-test.database.windows.net`，则输入 `sa@emqx-test.database.windows.net`。
   * **密码**：输入 SQL Server 账号密码。
   * **SQL Server Driver 名称**：输入 `ODBC Driver 17 for SQL Server`（EMQX 平台默认已安装）。
4. 点击**测试连接**按钮，如果 Microsoft SQL Server 服务能够正常访问，则会返回成功提示。

5. 点击**新建**按钮完成连接器的创建。

## 创建规则

接下来您需要创建一条规则来指定需要写入的数据，并在规则中添加响应动作以将经规则处理的数据转发到 Azure SQL Database。

1. 点击连接器列表**操作**列下的新建规则图标或在**规则列表**中点击**新建规则**进入**新建规则**步骤页。

2. 在 SQL 编辑器中输入规则，客户端将温湿度消息发送到 `temp_hum/emqx` 主题时，就会触发引擎。这里需要对 SQL 进行一定的处理：

   ```sql
     SELECT
       timestamp as up_timestamp,
       clientid as client_id,
       payload.temp as temp,
       payload.hum as hum
     FROM
       "temp_hum/emqx"
   ```

   ::: tip

   如果您初次使用 SQL，可以点击 **SQL 示例**和**启用调试**来学习和测试规则 SQL 的结果。

   :::

3. 点击**下一步**开始创建动作。

4. 从**使用连接器**下拉框中选择您之前创建的连接器。

5. 配置 SQL 模板，使用如下 SQL 完成数据插入，此处为预处理 SQL，字段不应当包含引号，SQL 末尾不要带分号 `;`：

   ```sql
    INSERT INTO temp_hum(client_id, temp, hum)
    VALUES (
      ${client_id},
      ${temp},
      ${hum}
    )
   ```

   如果在模板中使用未定义的占位符变量，您可以切换**未定义变量作为 NULL** 开关（位于 **SQL 模板** 上方）来定义规则引擎的行为：

   - **关闭**（默认）：规则引擎可以将字符串 `undefined` 插入数据库。

   - **启用**：允许规则引擎在变量未定义时将 `NULL` 插入数据库。

   ::: tip

   如果可能，应始终启用此选项；关闭该选项仅用于确保向后兼容性。

   :::

6. 根据需要配置高级设置选项（可选）。

7. 点击**确认**按钮完成动作的配置。

8. 在弹出的**成功创建规则**提示框中点击**返回规则列表**，从而完成了整个数据集成的配置链路。

## 测试规则

推荐使用 [MQTTX](https://mqttx.app/) 模拟温湿度数据上报，同时您也可以使用其他任意客户端完成。

1. 使用 MQTTX 连接到部署，并向以下 Topic 发送消息。

   - topic: `temp_hum/emqx`

   - payload:

     ```json
     {
       "temp": "27.5",
       "hum": "41.8"
     }
     ```

2. 检查消息是否已写入 Azure SQL Database。

3. 在控制台查看运行数据，点击规则 ID 可查看规则统计信息及其所有动作的执行情况。