Webhook

如果开发者不能对接 MQTT 服务,可以使用 Webhook 推送的方式接收实时数据的推送。Webhook 的功能是将传感器数据和事件消息通过 HTTP POST 命令实时发送到指定的 URL(服务器),为保护您的数据安全,请使用 HTTPS URL。

SENSORO 服务器在 5 秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。假如服务器无法保证在五秒内处理并回复,可以直接回复空字符串,SENSORO 服务器不会对此作任何处理,并且不会发起重试。

一、填写服务器配置

登陆 IoT 云平台官网后,在平台官网的 开发者- 消息推送设置,填写开发者 Webhook 地址, 其中 URL 必须支持 POST 请求方法,因为数据是通过 POST 的方式推送。

在平台官网 高级功能 - 开发者, 得到对应的 AppID, AppKey 和 AppSecret。

  • AppID 作为应用唯一标示符
  • AppKey 作为消息加密解密秘钥
  • AppSecret 作为消息签名密钥

同时,开发者可选择消息加解密方式:

  • 明文模式
  • 安全模式

模式的选择与服务器配置在提交后都会立即生效,开发者谨慎填写及选择。加解密方式的默认状态为明文模式,选择安全模式需要提前配置好相关加解密代码。

注: 推送数据包括三种内容: 传感器上报的实时数据、传感器状态改变相关数据、传感器下行任务的结果

二、传感器数据推送(传感器上报的实时数据)

终端 向云平台上传数据包时,SENSORO 服务器将 JSON 数据包 POST 请求到开发者填写的 Webhook 地址。

标准设备上只有一个传感器,所以推送的数据包中只有一种传感器数据,以下请求示例枚举所有传感器类型的数据.

注意:

1. α 开发者套件或者 α 传输模块推送的传感器数据只有 `customer` 字段, 需要对 customer 做数据解析。
2. α 开发者套件默认解析规则如下:
    第 0 个字节: 前缀,解析时跳过
    第 1~4 个字节: 温度数据,float型小端模式
    第 5~8 个字节: 湿度数据,float型小端模式
    第 9~12 个字节: 光线数据,float型小端模式
请求参数举例
Request: {
    appId: '123456789ABC',
    sn: '0117C9XXXX',
    type: 'text', // 消息类型, text 普通消息
    deviceType: 'node',
    createdTime: '',
    msgId: '', //消息 id
    band: 'SE433', // 频段
    rssi: -50, // 信号强度
    snr: 11.5, // 信噪比
    data: { // 明文
        battery: Int, //电池电量
        temperature: float,
        light: float,
        humidity: float
    },
    encryptData: '' // 安全模式开启后的加密密文
}
参数说明
  • 所有设备类型必有字段
参数说明 是否必有 类型 示例值 说明
appId String 123456789ABC 系统分配给应用的唯一标示符, 可在云平台 开发者 -基本设置获取
sn String 1122334455667788 终端设备标示符, 即升哲传感器或者传输模块的唯一序列号
type String text 表明此数据包是传感器数据推送消息
deviceType String chip 设备类型
createdTime Number 1490611396441 云平台接收到消息的时间
msgId Number 587c90931755e87f7fb41361 消息 Id,为避免重复, 传感器或传输模块上传的每条数据 id 不同
band String SE433 设备所属频段取值范围: ['SE433', 'US915', 'SE915', 'SE470', 'SE780', 'EU868', 'EU433', 'AS923']
rssi Number -50 信号强度, 取值范围:[-127,127]
snr Number 11.2 信噪比,取值范围:[-20, 20]
data Object { co2: 20, interval:60 } 包含各设备类型特有字段
hardwareVersion String C2 表明此数据包是传感器数据推送消息
firmwareVersion String 1.2 表明此数据包是传感器数据推送消息

注: 以下各表中 . 表明包含层级。

  • 1.设备类型: α 芯片 和 α 模块, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String chip 取值范围: module or chip
data.customer String '10080018003202100538c601' 用户自定义传感器数据
  • 2.设备类型: α 传感器, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String node 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.temperature Number 20 温度值 (°C)
data.humidity Number 20 湿度值 (%)
data.light Number 20 光线值 (Lux)
  • 3.设备类型: α 一氧化碳 参数说明
参数说明 是否必有 类型 示例值 说明
deviceType String co 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.co Number 20 一氧化碳浓度(ppm)
threshold.co.alarmHigh Number 20 一氧化碳浓度紧急报警阈值(ppm)
  • 4.设备类型: α 二氧化碳, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String co2 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.co2 Number 20 二氧化碳浓度 (ppm)
threshold.co2.alarmHigh Number 20 二化碳浓度紧急报警阈值(ppm)
  • 5.设备类型: α 二氧化氮, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String no2 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.no2 Number 20 二氧化氮浓度(ppm)
threshold.no2.alarmHigh Number 20 二化氮浓度紧急报警阈值(ppm)
  • 6.设备类型: α 二氧化硫, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String so2 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.so2 Number 20 二氧化硫浓度(ppm)
threshold.so2.alarmHigh Number 20 二化硫浓度紧急报警阈值(ppm)
  • 7.设备类型: α 天然气, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String ch4 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.ch4 Number 20 甲烷浓度(ppm)
threshold.ch4.alarmHigh Number 20 甲烷浓度紧急报警阈值(ppm)
  • 8.设备类型: α 臭氧, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String o3 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.o3 Number 20 臭氧浓度(ppm)
threshold.o3.alarmHigh Number 20 臭氧浓度紧急报警阈值(ppm)
  • 9.设备类型: α 氨气, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String nh3 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.nh3 Number 20 氨气浓度(ppm)
threshold.nh3.alarmHigh Number 20 氨气浓度紧急报警阈值(ppm)
  • 10.设备类型: α TVOC, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String tvoc 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.ch2o Number 20 甲醛浓度
threshold.ch2o.alarmHigh Number 20 甲醛浓度紧急报警阈值(ppm)
  • 11.设备类型: α PM, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String pm 设备类型取值固定为示例值
interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.pm1 Number 20 空气质量 pm1 (ug/m3)
data.pm2_5 Number 20 空气质量 pm2.5(ug/m3)
data.pm10 Number 20 空气质量 pm10(ug/m3)
threshold.pm1.alarmHigh Number 20 pm1 紧急报警阈值(ug/m3)
threshold.pm2_5.alarmHigh Number 20 pm2.5 紧急报警阈值(ug/m3)
threshold.pm10.alarmHigh Number 20 pm10 紧急报警阈值(ug/m3)
  • 12.设备类型: α 液化石油气, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String lpg 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.lpg Number 20 液化石油气浓度(ppm)
threshold.lpg.alarmHigh Number 20 液化石油气浓度紧急报警阈值(ppm)
  • 13.设备类型: α 烟雾, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String smoke 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.smoke Number 1 传感器是否报警(1:报警,0:正常)
  • 14.设备类型: α 倾角, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String angle 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.angle Number 20 温度值
  • 15.设备类型: α 温湿度, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String humi_temp 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.temperature Number 20 温度值 (°C)
data.humidity Number 20 湿度值 (%)
threshold.temperature.alarmHigh Number 200 温度紧急报警阈值(°C)
threshold.temperature.alarmLow Number 20 温度紧急报警阈值(°C)
threshold.humidity.alarmHigh Number 200 湿度紧急报警阈值(%)
threshold.humidity.alarmLow Number 20 湿度紧急报警阈值(%)
  • 16.设备类型: α 跑冒滴漏, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String leak 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.leak Bool false 是否跑冒滴漏
  • 17.设备类型: α 灯井, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String cover 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.cover Bool true 井盖是否存在
data.level Bool true 液位是否到达标定位置
  • 18.设备类型: α 温湿光, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String op_node 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.temperature Number 20 温度值 (°C)
data.humidity Number 20 湿度值 (%)
data.light Number 20 光线值 (Lux)
threshold.temperature.alarmHigh Number 200 温度紧急报警阈值(°C)
threshold.temperature.alarmLow Number 20 温度紧急报警阈值(°C)
threshold.humidity.alarmHigh Number 200 湿度紧急报警阈值(%)
threshold.humidity.alarmLow Number 20 湿度紧急报警阈值(%)
threshold.light.alarmHigh Number 200 光线紧急报警阈值(Lux)
threshold.light.alarmLow Number 20 光线紧急报警阈值(Lux)
  • 19.设备类型: α 追踪器, 特有字段及deviceType取值说明
参数说明 是否必有 类型 示例值 说明
deviceType String tracker 设备类型取值固定为示例值
data.interval Number 60 设备传输周期
data.battery Number 90 剩余电量百分比
data.customer Number 10080018003202100538c601 原始数据
data.gps.latitude Number 20 纬度值
data.gps.longitude Number 20 经度值
data.gps.altitude Number 20 高度值
返回参数说明
参数 是否必有 类型 示例值 说明
messages × String 'success' 返回参数,可返回空字符串

三、任务事件推送(传感器下行任务的结果)

任务下发修改 终端 上传数据周期时,任务完成时的事件推送。

请求参数举例
Request: {
    appId: '123456789ABC',
    sn: '0117C9XXXX',
    taskId: 123,
    type: 'event', //event: 事件消息
    createdTime: timestamp,
    msgId: '', //消息 id
    resultCode: 0, //0 成功,1,失败
    resultData: {}
}
参数说明
参数 是否必有 类型 示例值 说明
appId String 系统分配给应用的唯一标示符,可在云平台 开发者 -基本设置获取
sn String 1122334455667788 终端设备标示符, 即升哲传感器或者传输模块的唯一序列号
taskId String 下行任务的唯一 Id
type String event 当为终端执行云端下发任务的返回值时, type值为'event'
createdTime Timestamp 云平台接收到消息的时间
msgId Number 消息 Id, 为避免重复, 传感器或传输模块上传的每条数据 id 不同
resultCode Number 0 任务执行结果, 0 表示成功, 1 表示失败
resultData × Object 任务回执消息详情
返回参数说明
参数 是否必有 类型 示例值 说明
messages × String 'success' 返回参数,可返回空字符串

四、传感器状态改变相关数据推送

根据设备何时上报数据及上报数据的内容,使得设备具有多种状态,当设备状态改变时,推送此种消息。

请求参数举例
Request: {
    appId: '123456789ABC',
    sn: '0117C9XXXX',
    type: 'statusChanged',
    createdTime: timestamp,
    msgId: '', //消息 id
    band: 'SE433',
    snType: 'device',
    normalStatus: 0
}
参数说明
参数 是否必有 类型 示例值 说明
appId String 系统分配给应用的唯一标示符,可在云平台 开发者 -基本设置获取
sn String 1122334455667788 终端设备标示符, 即升哲传感器或者传输模块的唯一序列号
taskId String 下行任务的唯一 Id
type String event 当为终端执行云端下发任务的返回值时, type值为'event'
createdTime Timestamp 云平台接收到消息的时间
msgId Number 消息 Id, 为避免重复, 传感器或传输模块上传的每条数据 id 不同
snType String device 基站(station)或终端设备(device)
normalStatus Number 0 设备当前状态

normalStatus 取值及含义:

normalStatus 名称 说明
-1 未激活 从未上报过数据
0 正常 设备正常上报数据并且上报数据未超出阈值
1 报警 超过设备的报警阈值
2 紧急报警 -
3 超时未上报 连续8倍周期未上报数据
4 离线 超时超过两天
返回参数说明
参数 是否必有 类型 示例值 说明
messages × String 'success' 返回参数,可返回空字符串

五、接收响应

当开发者服务器接收到请求后,请响应 2xx 的 HTTP 状态码。如果接收到其他 HTTP 状态码,SENSORO 会尝试重新推送 3 次,失败 3 次后将不再推送此条数据。

六、验证消息是否来自 SENSORO

为了验证消息体的合法性,开发者可用以验证消息体是来自 SENSORO 请求真实性,并对验证通过的消息体进行解密。

消息签名具体在 API权限检验 - 消息体签名

七 、推送消息加密

选择安全模式,开发者在接收消息需要进行消息加解密, 接收事件不需要加密。通过 API 主动调用接口(修改终端配置和下行终端数据)时,不需要进行加密。

消息加密具体在 API权限校验- 消息体加密