设备数据HTTP方式推送

更新时间:2019-01-23 17:31:29

设备数据(如设备状态数据、设备控制记录等),我们更推荐使用HTTP/2的方式推送,推送颗粒度可以细化到项目和产品,查看 设备数据HTTP/2方式推送
用户数据(如用户绑定、解绑数据等),我们推荐使用本文描述的HTTP的方式推送,会对所有数据全局推送,不区分项目或产品。具体方式请见下文:

一. 接入方式

智能生活开放平台支持使用HTTP/HTTPS协议的__POST方法__,调用第三方云提供的URL接口,实现实时上报设备相关数据。

说明:点击控制台-首页-右上角的“云端设置”,出现如图所示的界面,在服务器地址一栏,填入URL(支持HTTP/HTTPS),点击开启按钮,之后当有设备相关数据产生时,平台会主动调用该URL接口进行实时数据推送。

接入示意图如下:

image.png | left | 747x374

二. 数据类型和字段

目前平台会默认推送五种消息,消息名称和消息字段类型如下所示:

(1) 物的属性变更消息(thing_properties_post)

消息字段说明:

参数
类型
含义
gmtCreate
Long
消息创建时间, 自1970-1-1起流逝的毫秒值
iotId
String
物的唯一id
batchId
String
上报批次id
productKey
String
设备所属产品
deviceName
String
设备名称
tenantId
String
租户id
items
JSON
变更的状态列表,列表元素包括:
attribute - 变更属性, value - 变更值, time - 采样时间

消息范例:

{
    "batchId": "test_batch_id_001",
    "gmtCreate": 1510292739881,
    "iotId": "0300MSKL03667c544f69342a74Sv4Za4",
    "items": {
        "attribute_9": {
            "time": 1510292697471,
            "value": 560542025
        },
        "attribute_8": {
            "time": 1510292697470,
            "value": 715665571
        }
    },
    "productKey": "X5eCzh6fEH7",
    "deviceName": "xxxxxxxxxxxxxxxx",
    "tenantId": "xxxxxxxxxxxxxx"
}

(2) 物的事件变更消息(thing_event_post)

消息字段说明:

参数
类型
含义
gmtCreate
Long
消息创建时间, 自1970-1-1日流逝的毫秒值
iotId
String
物的唯一id
batchId
String
上报批次id
productKey
String
设备所属产品
deviceName
String
设备名称
eventCode
String
​事件标识符,对应事件的 identifier
eventName
String
事件名称
eventType
String
事件类型
tenantId
String
租户id
time
Long
设备上报value对应的时间戳(毫秒)
value
JSON
变更的事件属性列表:key - value 键值对

消息范例:

{
    "batchId": "2e27fa589dbb4a77a5519086ab77a7a6",
    "eventCode": "BrokenInfo",
    "eventName": "损坏率上报",
    "eventType": "info",
    "iotId": "4z819VQHl6VSLmmBNfrf00107ee200",
    "value": {
        "Power": "on",
        "structParam": {
            "param1": "abc",
            "param2": 123
        }
    },
    "time": 1510799670074,
    "productKey": "5RS5XTnNADg",
    "deviceName": "xxxxxxxxxxxxxxxx",
    "gmtCreate": 1510799670074,
    "tenantId": "xxxxxxxxxxxxxx"
}

(3) 物的服务变更消息(thing_service_post)

消息字段说明:

参数
类型
含义
gmtCreate
Long
消息创建时间, 自1970-1-1起流逝的毫秒值
iotId
String
物的唯一id
batchId
String
上报批次id
productKey
String
设备所属产品
deviceName
String
设备名称
tenantId
String
租户id
serviceCode
String
​服务标识符, 对应服务的 identifier
serviceName
String
服务名称
input
JSON
服务入参
output
JSON
服务出参

消息范例:

{
    "batchId": "4b7ddae8c6b142a49e1b5fb20d123225",
    "iotId": "Z4Bt2jBJ7PPx0eSrPwLi0010f7f501",
    "productKey": "p1gsv0teUBd",
    "deviceName": "xxxxxxxxxxxxxxxx",
    "serviceCode": "TimeReset",
    "serviceName": "设备校时服务",
    "gmtCreate": 1510799670074,
    "tenantId": "xxxxxxxxxxxxxx",
    "input": {
        "time": 1513683454039,
        "value": {
            "param1": "edge_test",
            "param2": "edge_test"
        }
    },
    "output": {
        "time": 1513683454039,
        "value": {
            "param1": "edge_test",
            "param2": "edge_test"
        }
    }
}

(4) 物的状态变更消息(thing_status_post)

消息字段说明:

参数
类型
含义
iotId
String
物的唯一id
productKey
String
设备所属产品
deviceName
String
设备名称
tenantId
String
租户id
status
JSON
状态信息,元素包括:
value - 状态值, time - 采样时间
value状态值定义:
0(未激活), 1(在线), 3(离线), 8(禁用)

消息范例:

{
  "productKey":"JgdsgIGHSDAweraQ",
  "deviceName" :"testDevice123",
  "iotId" :"AEGabcGHj",
  "tenantId": "xxxxxxxxxxxxxx",
  "status":{
      "time":1510292697471,
      "value":"0"                      
  }
}

(5) 设备绑定关系变更消息(thing_user_bind_post)

消息字段说明:

参数
类型
含义
iotId
String
物的唯一id
bind
Boolean
true-绑定;false-解绑
identityInfos
JSON
用户列表,每个元素包含:
identityId: 账号id, scopeId: 资源隔离id, tenantId: 租户id,owned:拥有标记(0:分享者;1:拥有者)

消息范例:

{
    "bind":true,
    "identityInfos":[
        {
            "identityId":"5034op980470862060259",
            "scopeId":"",
            "tenantId":"1D89B59983D3413E82999AD4861678FF",
            "owned":1
        }
    ],
    "iotId":"4MvN99UgCbiImQCV2mcc0010033801"
}

三. 接入教程

(1) HTTP POST方法推送的数据体内容

  • message : 消息内容

  • appKey : 线上环境Appkey

  • msgCode : 消息名称(英文)

  • sign : 生成的签名字符串

备注:msgCode是第二部分消息的英文名称。

(2) 加签和验签

为了保证推送数据的完整性,需要对数据进行加签,签名生成规则如下:

  • 参与生成签名的参数

    在请求参数列表中,除去sign参数外,其他需要使用到的参数皆是要参与签名的参数。
    我们这里参与签名的参数是appKey、message和msgCode。

  • 生成待签名字符串

    对于如下参数数组:
    string[] parameters={

       "appKey=xxx",
       "message=xxx",
       "msgCode=xxx"
    }; 
    对数组里的每一个参数值按照字典顺序排序,若遇到相同首字母,则看第二个字母, 以此类推。排序完成之后,再把所有数组值以“&”字符连接起来, 例如appKey=xxx&message=xxx&msgCode=xxx, 这串字符串便是待签名的字符串。
    
  • 使用MD5生成签名

    在MD5签名时,需要appsecret参与签名。__其中appsecret需要与appKey是匹配的__。
    

    当得到待签名字符串后,需要把私钥直接拼接到待签名字符串后面,形成新的字符串,利用 MD5 的签名函数对这个新的字符串进行签名运算,从而得到 32 位签名结果字符串。
    例如:私钥为:291GSDFSK9023842KJSDJFSDS23849JS, 则sign=MD5(appKey=xxx&message=xxx&msgCode=xxx291GSDFSK9023842KJSDJFSDS23849JS)。

  • 校验签名

    当收到请求后,同理,需要把appsecret直接拼接到待签名字符串后面,形成新的字符串,利用 MD5 的签名函数对这个新的字符串进行签名运算, 从而得到 32 位签名结果字符串。此时这个签名结果字符串需要与请求参数中的参数 sign 的值进行验证是否相等,来判断签名是否验证通过。
    

(3) URL接口返回值

  如果第三方云的URL接口正确收到推送的消息,期望返回的数据格式为:{"code":200,"message":"success","data":"OK"},同时HTTP CODE为200。

(4) 重试

  如果URL接口未正确返回数据格式或HTTP CODE返回非200,那么平台会采用退避策略重新推送该消息,最多推送16次。

results matching ""

    No results matching ""