中移动OneNet物联平台“第三方平台开发”数据接入功能描述及其配置开发流程概览

金耳朵先生2019-02-10 15:16:58

功能描述



“第三方平台开发”数据推送服务主要功能是当OneNet平台接收到项目相关设备的数据时,如果用户通过平台的“第三方平台开发”功能设置了数据接收地址,OneNet平台会把数据推送到用户指定的接收地址。数据推送服务以项目为单位,数据推送的消息模式可以设置为明文模式和加密模式,为了数据的安全,推荐使用加密模式。

配置开发流程概览



开发用户配置和使用第三方平台整个流程如下图:


根据上图,开发用户要配置和使用“第三方平台开发”数据推送服务,并且能接收到OneNet平台推送的数据的前提条件是:

1.      OneNet创建了相关项目,项目有真实设备并且能正常上报数据。

2.      用户方已经开发并部署了OneNet平台能访问的数据接收服务程序。此程序必须包含如下两个接口:


URL及token验证

功能

数据推送服务URL及token验证

HTTP请求方式

GET

请求URL

http://ip:port/URI//此接口URI和“数据接收”接口的URI一样,并且和OneNet平台的“第三方配置开发”基本配置的“服务器地址”的值一样

请求参数

参数名称

类型

必须

描述

msg

String

URL及token验证消息内容

nonce

String

用于验证时使用的随机串

signature

String

验证消息签名

返回结果

验证成功直接返回请求参数msg的值 //不要包含任何其他如换行、空格等不可见字符


数据接收

功能

数据接收

HTTP请求方式

POST

请求URL

http://ip:port/URI

请求Body

消息格式详见数据接收服务程序开发详述“数据消息格式”章节

返回结果

OneNet平台检测到数据推送请求状态为http 200即视为数据推送成功,否则视为推送失败,会重新发送。并且平台测在限定的时间内(目前是2秒)收不到响应也会认为此次推送失败,所以如果用户的业务逻辑复杂,处理时间久,建议收到消息时先缓存并返回响应,再处理业务逻辑。

 


数据接收服务程序开发详述

URL及token验证



在用户提交与修改第三方配置时,OneNet平台会向填写URL地址发送http GET请求进行“URL及token”的验证,当平台接收到期望的请求响应时则配置会被保存成功并且能接收到相应的数据推送消息。平台发送的“URL及token”请求形式如http://ip:port/test?msg=xxx&nonce=xxx&signature=xxx,阴影部分为用户在平台配置的URL。用户数据接收服务程序在接收到OneNet平台发送的 “URL及token”验证请求时,常规的验证流程如下: 


1.在请求中获取参数“nonce”、“msg”、“signature”的值,将“token”(此为页面配置参数token的值)、“nonce”、“msg”的值计算MD5(token+nonce+msg)加密值,并且编码为Base64字符串值。
2.将上一步中Base64字符串值通过URL Decode计算后的值与请求参数“signature”的值进行对比,如果相等则表示token验证成功。
3.如果token验证成功,返回“msg”参数值,否则返回其他值。
 注:如果用户不想验证token的有效性,可以选择忽略上述验证

数据接收



当用户成功在OneNet配置了第三方开发平台服务器地址后,OneNet平台在收到相关项目下设备数据时,会推送到推送的服务器地址。在开发数据接收服务程序,要注意:

1.OneNet平台为了保证数据不丢失,有重发机制,如果重复数据对业务有影响,数据接收端需要对重复数据进行排除重复处理。

2.OneNet每一次post数据请求后,等待客户端的响应都设有时限(目前是2秒),在规定时限内没有收到响应会认为发送失败。接收程序接收到数据时,尽量先缓存起来,再做业务逻辑处理。

3.OneNet平台接在规定时限内收到http 200的响应,才会认为数据推送成功,否则会重发。

4.同一产品下数据推送失败次数达到2000次,平台会停止向该产品接收数据的URL推送数据,第三方推送会被置为停用状态。

推送的数据会根据用户的配置被分为加密模式、明文模式,加密模式下要先解密后,才能看到对应的数据消息格式,数据消息格式如下:

1.1 数据消息格式
     平台以HTTP POST请求形式向第三方平台注册地址推送数据,推送数据相关信息以JSON串的形式置于HTTP请求中的body部分。
     第三方平台在接收数据时,根据加密选择,会接收到数据的明文消息或者密文消息。
     
明文格式:
1.  数据点消息(type=1)
示例:

 {

         "msg": {

                       "type": 1,

                        "dev_id": 2016617,

                        "ds_id": "datastream_id",

                        "at": 1466133706841,

                        "value": 42

                 },

                     "msg_signature": "message signature",

                      "nonce": "abcdefgh"

                      }

 2.  数据点消息批量形式(type=1)

示例:

 {

     "msg": [

                  {

                     "type": 1,

                      "dev_id": 2016617,

                      "ds_id": "datastream_id",

                      "at": 1466133706841,

                       "value": 42

                      },

                    {

                        "type": 1,

                        "dev_id": 2016617,

                        "ds_id": datastream_id",

                        "at": 1466133706842, "value":43

                        },

                      ...

               ], 

                   "msg_signature": message signature",

                   "nonce": "abcdefgh"

                     }

3.  设备上下线消息(type=2)
示例:

   {

      "msg": {

                    "type": 2,

                    "dev_id": 2016617,

                    "status": 0,

                    "login_type": 1,

                    "at": 1466133706841,

          },

              "msg_signature": "message signature",

               "nonce": abcdefgh"

                   }   

密文格式:
 {

             "enc_msg":"xxxx",

             "msg_signature":

             "message signature",

             "nonce":"abcdefgh"

           }      

说明:

1. 如果通过api上传二进制数据点(详情见公开协议二进制数据文档),此时value("value":{"indx":"2258292", "bin_data":"7b64613a64617d"})中包括该二进制数据的索引indx和二进制数据bin_data(二进制数据限制长度为2048个字节,如果超过该限制将不存在bin_data字段),bin_data为字符串形式代表二进制数据的十六进制字符;

2. 在明文传输时,存在msg、msg_signature、nonce字段,分别表示明文传输的数据、msg部分的消息摘要、用于摘要计算的随机字符串;在加密传输时,存在enc_msg、msg_signat。

上述格式中,相关字段的具体意义说明如下:

字段字段说明
type标识数据类型,当前版本范围[1,5]
dev_id设备ID
ds_id公开协议中的数据流ID
at平台时间戳,单位ms
value具体数据部分,为设备上传至平台或触发的相关数据
status

设备上下线标识

0-下线, 1-上线

login_type

设备登陆协议类型

1-EDP, 2-nwx, 3-JTEXT, 5-JT808, 6-MODBUS, 7-MQTT, 8-gr20

cmd_type

命令响应的类型

1-设备收到cmd的ACK响应信息, 2-设备收到cmd的Confirm响应信息

cmd_id 命令ID
msg_signature消息摘要
nonce用于计算消息摘要的随机串
enc_msg加密密文消息体,对明文JSON串(msg字段)的加密

1.2 加密算法详述

平台基于AES算法提供加解密技术,具体如下:

1.  EncodingAESKey即消息加解密Key的BASE64编码形式,长度固定为43个字符,从a-z,A-Z,0-9共62个字符中选取。由服务开启时填写,后也可申请修改。
2. AES密钥计算为 AESKey=Base64_Decode(EncodingAESKey + “=”),EncodingAESKey尾部填充一个字符的“=”,用Base64_Decode生成32个字节的AESKey。
3. AES采用CBC模式,秘钥长度为32个字节(256位),数据采用PKCS#7填充 ,初始化iv向量取秘钥前16字节; PKCS#7:K为秘钥字节数(采用32),buf为待加密的内容,N为其字节数。Buf 需要被填充为K的整数倍。在buf的尾部填充(K-N%K)个字节,每个字节的内容 是(K- N%K)。
具体详见://tools.ietf.org/html/rfc2315
 4. BASE64采用MIME格式,字符包括大小写字母各26个,加上10个数字,和加号“+”,斜杠“/”,一共64个字符,等号“=”用作后缀填充;
 5. 出于安全考虑,平台网站提供了修改EncodingAESKey的功能(在EncodingAESKey可能泄漏时进行修改,对应上第三方平台申请时填写的接收消息的加密对称密钥),所以建议保存当前的和上一次的EncodingAESKey,若当前EncodingAESKey生成的AESKey解密失败,则尝试用上一次的AESKey的解密。
 6. 平台的加密消息部分为enc_msg= Base64_Encode( AES_Encrypt [random(16B)+msg_len(4B)+msg] ),即以16字节随机字节串拼接4字节表示消息体长度的字节串(此处4字节长度表示为网络字节序),再加上消息本身的字节串作为AES加密的明文,再 以AES算法对明文进行加密生成密文,最后对密文进行BASE64的编码操作生成加密消息体。
 7. 对加密消息体的解密流程为:1)首先进行加密消息体的BASE64解码操作,aes_msg=Base64_Decode(enc_msg);2)对获取的解码内容以AES算法进行解密操作,获取明文部分,plain_msg=AES_Decrypt(aes_msg),解密中使用的秘钥由EncodingAESKey计算得来,使用的初始化iv向量为计算出的aes秘钥的前16字节;3)去掉plain_msg的前16字节,再以前4字节取出消息体长度,根据消息体长度获取真实的消息部分(推荐以消息体长度获取真实消息,以兼容plain_msg未来可能出现的结构变更)。表示加密传输的数据,后两字段与明文传输一致。详细的加密算法见下一章节。


相关SDK

相关SDK


关于第三方平台URL&Token验证和数据接收的相关SDK,目前平台提供的版本有Javaphp,Nodejs,C#

下载地址:https://open.iot.10086.cn/doc/art380.html#68

数据接收地址配置说明及常见问题

数据接收地址配置说明



Step1 点击进入配置页


Step2  填写第三方URL地址

URL地址应为一个可达地址,并提供token验证的get方法。


Step3  写用户Token

Token作为用户在平台侧的身份标识,用于消息摘要。


Step4 随机生成EncodingAESKey


Step5  选择消息加解密方式

常见问题


1.EncodingAESKey解密失败,可能为EncodingAESKey在平台侧进行的修改还未生效,尝试使用修改前的EncodingAESKey进行解密操作;

2.在使用java编写第三方代码时,出现异常java.security.InvalidKey Exception:illegal Key Size。解决方案为在官方网站下载JCE无限制权限策略文件,下载后解压,可以看到local_policy.jar和US_export_policy.jar以及readme.txt,如果安装了JRE,将两个jar文件放到%JRE_HOME%\lib\ security目录下覆盖原来的文件;如果安装了JDK,将两个jar文件放到%JDK_ HOME%\jre\lib\security目录下覆盖原来文件




Copyright © 古田计算器虚拟社区@2017