OneNet接入方案与RESTfulAPI接口.docx
《OneNet接入方案与RESTfulAPI接口.docx》由会员分享，可在线阅读，更多相关《OneNet接入方案与RESTfulAPI接口.docx（54页珍藏版）》请在冰豆网上搜索。
OneNet接入方案与RESTfulAPI接口
OneNet接入方案与RESTfulAPI接口
欢迎访问设备云门户网站注册用户，获取最新文档。
版本号
修订日期
修订内容
说明
V1.1
2014.10.30
EDP增加存储数据报文；
RESTAPI增加历史数据查询接口，用于上报数据点，或者上报的同时转发数据点。
V1.1.1
2014/11/3
EDP增加消息类型9，以支持对存储数据的确认。
V1.1.2
2015/01/10
1、修改3.5.3AB接口，增加获取每个数据流当前值。
2、数据点添加时若无数据流将自动添加数据流。
V1.2.2
2015/01/15
1、修改3.5.1，新增数据流返回uuid，唯一标识该数据流；
2、修改3.5.1，增加三种复合数据流的添加；
3、修改触发器相关操作接口。
一个触发器可同时监控不同设备的多个数据流。
4、修改触发器一些条件的设定方式。
V1.2.3
2015/06/18
1、去掉复合数据流定义
2、设备批量查看增加device_id参数
3、触发器增加title字段
4、新增触发器批量获取接口
5、修改key查看输出内容格式
V1.3.0
2015/06/24
1、命令操作，增加响应内容查询
V1.3.1
2015/07/28
1、修改4.6.3，新增数据点抽样和统计
V3.0
2016/06/20
1、4.3.3模糊查看设备信息,增加时间查询
V3.1
2016/08/04
1.增加4.10.3注册码创建接口
1概述
OneNet是中移物联网有限公司基于物联网技术和产业特点打造的开放平台和生态环境，适配各种网络环境和协议类型，支持各类传感器和智能硬件的快速接入和大数据服务，提供丰富的API和应用模板以支持各类行业应用和智能硬件的开发，能够有效降低物联网应用开发和部署成本，满足物联网领域设备连接、协议适配、数据存储、数据安全、大数据分析等平台级服务需求。
中国移动物联网开放平台始终秉承开放合作的态度，为智能硬件创客和创业企业提供硬件社区服务，为中小企业客户物联网应用需求提供数据展现、数据分析和应用生成服务，为重点行业领域/大客户提供行业PaaS服务和定制化开发服务。
是OneNet对外公开的门户，可以通过该门户了解到OneNet的最新进展。
本文档主要描述了OneNet基于HTTP方式向外提供API接口以及这些接口的调用方式、参数说明等等。
这些接口按照RESTful的方式向外提供服务。
2基于OneNet的应用系统的典型场景
设备层：
利用平台提供的EDPSDK，实现EDP协议，用于上报业务数据点到OnetNet。
若需要实时接收业务层下发的控制命令，需要保持EDP长连接。
业务应用层：
若要自定义实现业务平台，可通过HTTP协议的RESTfulAPI操作OnetNet提供的资源（设备、数据点、命令控制等资源的增删查改）。
适用场景：
在充分分析业务数据模型的基础上，认为OneNet提供的设备-数据流-数据点模型适合业务数据存储。
优先推荐新业务使用该模式。
3API资源模型
OneNetHTTPAPI按照RESTful的方式向外提供服务，其资源模型中包含的资源种类有：
用户、设备（device）、数据流（datastream）、数据点（datapoint）、触发器（trigger）、APIkey、命令等。
用户是指通过注册的用户。
每个用户可以建立多个项目，每个项目可以添加多个设备。
一个设备只能属于一个项目。
一个设备可以产生多个数据流，一个数据流可以理解为一类数据。
比如温度是一个数据流、经纬度是一个数据流等等。
数据流中的一个具体的数据称为数据点。
数据点采用Key-Value方式的存储的。
其中Key的组成包括设备id、数据流id、时间等信息，value部分可以为任何数据对象，如整数、字符串或者JSON数据类型。
APIKey用于对设备云进行操作的权限控制，在访问OneNetRestAPI时，http请求消息的头域必须携带api-key字段，设备云会依据api-key字段判别该用户是否具有对应操作的权限。
默认在上注册项目时会生成一个默认的APIKey，这个APIKey是masterkey，具有对本项目下所有设备最大的访问权限。
除了这个masterkey之外，还可以通过API命令创建具备不同权限的其他APIKey。
APIKey的权限模型是通过设定对某些设备和数据流、是否可以增加、查看、修改、删除等方式来描述的，最低的权限级别可细化到对某个数据流的访问权限。
触发器用于告知设备云当满足某种条件时主动触发某个动作。
命令是让设备云主动给设备推送数据的一种方式。
默认只有EDP设备或者MODBUS设备才可以接收设备云发送的命令。
大多数使用场景是设备主动向设备云发送数据，也就是数据上行传递；而通过命令的方式，可以控制设备云向设备发送命令，达到数据下行的目标。
这可以达到对远程终端进行控制的目的。
二进制数据是一类特别的数据，可以通过api上传到设备云，作为数据点存储在设备云上。
二进制数据主要是图片等等。
4RESTAPI
以下API需要在平台注册用户并创建项目的条件下使用。
RESTAPI基于HTTP协议（详见）和json数据格式（详见），适合平台与平台之间数据对接，或使用短连接上报终端数据。
外网运营地址：
端口80或端口80
统一说明：
Ø终端设备上行发送给设备云的日期时间格式统一为”2015-12-04T13:
00:
05”形式，日期和时间之间用大写字母T隔开。
包括消息中设计数据点的时间和URL参数中涉及到的时间都按照此格式；
Ø设备云下发的日期时间格式为”2015-12-0413:
00:
05”，中间用空格隔开，与上行格式不同，请注意；
4.1设计原则
●使用标准HTTP方法实现资源CURD操作；
●采用json作为API输入输出；
●以json输出错误信息。
HTTP方法
描述
POST
新增资源信息
PUT
更新资源信息
GET
查看资源信息
DELETE
删除资源
支持的返回码列表：
HTTP返回码
含义
详细描述
200
OK
在HTTPbody中以json格式指明详细成功或错误信息，例如：
{
"errno":
0,
"error":
“succ”
}
成功、失败指示，主要以errno是否为零来判断。
400
BadRequest
401
NotAuthorized
403
Forbidden
404
NotFound
406
NotAcceptable
422
UnprocessableEntity
500
InternalServerError
503
Noservererror
4.2HTTP原始报文格式
例1，自己封装HTTP报文，新增设备，格式如下，其中\r\n是两个字符（ASCII码里面的回车换行），长度32表示两个连续\r\n\r\n后数据的长度：
POST /devices HTTP/1.1\r\n
api-key:
\r\n
Host:
\r\n
Content-Length:
32\r\n
\r\n
{"title":
"898602B9"}
例2，看某个设备的详细情况，格式如下，
GET /devices/HTTP/1.1\r\n
api-key:
\r\n
Host:
\r\n
\r\n
4.3设备（device）
4.3.1新增
新增设备用于向设备云增加一个设备，通过HTTPPOST请求增加设备，增加成功后，会返回该设备的设备ID。
HTTP方法
POST
URL
http:
///devices
HTTP头部
api-key:
xxxx-ffff-zzzzz，必须为MasterKey
HTTP内容
{
//设备名，应在产品范围内唯一，对于MODBUS、EDP设备，应填写卡号
"title":
"mydevice1",
//设备描述
"desc":
"somedescription",
"tags":
[//可选
"Tag1",
"Tag2"
],
//设备位置
"location":
{//可选
//高度，double
"ele":
370000,
//经度，double
"lat":
17.609997,
//纬度，double
"lon":
177.03403
},
//本设备是否私有，公开的应用在上发现上会列出来
"private":
true,
"protocol":
"EDP|HTTP|JTEXT",
//可选对于MODBUS设备有效，需包含卡号（phone）和密码（svrpwd）形式为：
{“登录报文的phone字段”:
”登录报文的SVRPWD字段”}
"auth_info":
{…},
//可选，对modbus设备有效，TCP类设备，表示设备云主动查询设备的时间间隔，单位秒
"interval":
60,
“other":
{…}
}
HTTP响应响应消息内容
{
"errno":
0,
"error":
“succ”,
"data":
{
//平台分配唯一ID
"device_id":
"233444"
}
}
说明：
1、对于非MODBUS和EDP协议的设备，可以忽略auth_info和interval字段，可以参阅MODBUS接入协议对应的api文档；
2、other字段如果有可填写，如果也不影响设备的创建；
3、响应消息中errno表示错误码，error表示错误原因，如果创建设备失败，则没有device_id字段。
4.3.2更新
根据更新参数，需要更新哪些参数就选哪些参数？
。
HTTP方法
PUT
URL
http:
///devices/
HTTP头部
api-key:
xxxx-ffff-zzzzz，可为设备级别的Key
HTTP内容
{
"title":
"mydevice1",
"desc":
"somedescription",
”private":
true,
//可选
"tags":
[
"Tag1",
"Tag2"
],
"location":
{
"ele":
370000,
"lat":
17.787,
"lon":
177.73
},
"auth_info":
{…},
"interval":
60,
"other":
{}
}
请求返回
{
"errno":
0,
"error":
“succ”,
}
说明：
1、更新时，更新那个字段就只需要在json字符串中包括哪个字段，不需要包含所有内容。
2、Private字段表示是否私有。
私有的设备不会列在”->发现”栏目中。
3、auth_info和interval字段参见设备新增章节的解释。
4.3.3查看
a查看单个设备的信息
单个设备查看是在知道待查设备的设备ID的情况下查看设备的明细。
会返回待查设备的基本信息、所有数据流信息、apikey信息、二进制数据信息等等。
HTTP方法
GET
URL
http:
///devices/
HTTP头部
api-key:
xxxx-ffff-zzzzz，必须为可查看该设备的Key
请求返回
{
"errno":
0,
"error":
“succ”,
"data":
{
"id":
"device_id",
//表示EDP设备是否在线，只对EDP设备存在此字段
"online":
true|false,
"protocol":
"HTTP"
"title":
"mydevice1",
"desc":
"somedescription,ex:
url",
"create_time":
"xx-xx-xx10:
22:
22",
"private":
true|false,
//设备关联的图像或二进制数据
"binary":
[{
//二进制数据索引
“index”:
”FJWOPN9023899”,
//上传时间
“at”:
”2014-10-2320:
22:
22”,
//二进制数据大小
“size”:
2333（字节）,
”desc”:
”binarydescription”
}]
"tags":
["Tag1","Tag2"],
"location":
{"ele":
370000,"lat":
17.787,"lon":
177.},
//只对MODBUS和EDP设备有效
"auth_info":
{…},
"other":
{}
"keys":
[
{"title":
"device-auto-key","key":
"2JO3B12O1"},
{"title":
"key-name2","key":
"DFWfsfw1wfDF233"},
]，
//数据流
"datastreams":
[{
“create_time”:
”2014-10-2320:
22:
22”
"id":
"datastream_id1”,
"unit":
"celsius",
"unit_symbol":
"C",
"uuid":
"231a5aa9-9de4-5f2e-9e0f-015181c98429"
}]//enddata_streams
}//enddata
}
说明：
1、注意URL最后不能有多余的斜杠，比如http:
///devices/可以，但是http:
///devices//会查询不到。
具体如下：
请求
响应
{
"errno":
0,
"data":
{
"private":
true,
"protocol":
"HTTP",
"create_time":
"2015-11-0414:
27:
31",
"location":
{"lon":
106.01,"lat":
29.},
"id":
"564280",
"auth_info":
{"SYS":
"z=8QY3r7aTQ48UKfqPnB=PybYRo="},
"datastreams":
[
{
"unit":
"摄氏度",
"create_time":
"2015-11-2309:
35:
54",
"unit_symbol":
"℃",
"id":
"温度",
"uuid":
"231a5aa9-9de4-5f2e-9e0f-015181c98429"
},
{
"create_time":
"2015-11-2415:
10:
26",
"id":
"温度2",
"uuid":
"25346b97-01a8-461d-b98b-26139e67f6a8"
},
{
"create_time":
"2015-11-2415:
05:
01",
"id":
"温度_2",
"uuid":
"6eb512e5-3fad-45a8-bc83-a9eec7d2c792"
}
],
"title":
"设备1",
"desc":
"测试设备1",
"tags":
["aa,bb"]
},
"error":
"succ"
}
2、Online字段只对EDP设备有效，表示EDP设备是否在线，对于非EDP设备不存在该属性。
b模糊查看设备信息
批量查看是指模糊查找设备，会把所有符合条件的设备都列出来。
批量查找通过在URL中附带参数的形式向服务器端查询设备。
HTTP方法
GET
URL
URL参数
key_word=xxbbcc,//可选,会从设备id字段中去左匹配
tag=xxx//可选
online=true|false//可选
private=true|false//可选
page=1//指定页码,可选
per_page=30//指定每页输出设备个数,可选,默认30，最多100
device_id=235122//指定设备ID,可选,多个用逗号分隔，最多100个
begin=2016-06-20//可选，包括这天
end=2016-06-20//可选，包括这天
HTTP头部
api-key:
xxxx-ffff-zzzzz
请求返回
{
"errno":
0,
"error":
“succ”,
"data":
{
"total_count":
1,
"per_page":
30,
"page":
1,
"devices":
[
{
"id":
"dev_id",
"title":
"mydevice1",
“desc”:
”devicedesc”,
"private":
true,
"protocol":
"HTTP|EDP|JTEXT",
"online":
ture|false,
"tags":
["aa","bb"]
"location":
{"lon":
106.01,"lat":
29.},
"create_time":
"2013-02-1112:
22:
33",
"auth_info":
{"SYS":
"z=8QY3r7aTQ48UKfqPnB=PybYRo="}
}
]
}
}
4.3.4删除
HTTP方法
DELETE
URL
http:
///devices/
HTTP头部
api-key:
xxxx-ffff-zzzzz，可为设备级别的Key
HTTP内容
无
请求返回
{
"errno":
0,
"error":
“succ”
}
说明：
删除设备会删除该设备下所有数据流和数据点。
删除设备动作是异步的，系统会在后续逐步删除该设备下的数据流和数据点。
4.3.5批量查询设备状态
HTTP方法
GET
URL
http:
///devices/status
UTL参数
devIds=1221,12233,1123//设备id用逗号隔开,限制1000个设备
HTTP头部
api-key:
xxxx-ffff-zzzzz，可为设备级别的Key
HTTP内容
无
请求返回
{
"errno":
0,
"error":
“succ”,
"data":
{"total_count":
121,
"devices":
[
{
"id":
12323,
"title":
"daf",
"online":
false
},
{…..},
…..
]
}
}
4.3.6批量查询设备最新数据
HTTP方法
GET
URL
http:
///devices/datapoints
UTL参数
devIds=1221,12233,1123//设备id用逗号隔开,限制500个设备
HTTP头部
api-key:
xxxx-ffff-zzzzz，可为设备级别的Key
HTTP内容
无
请求返回
{
"errno":
0,
"error":
“succ”,
"data":
{
"devices":
[
{
"id":
12323,
"title":
"daf",
"datastreams":
[
{
"id":
"temperature",
"at":
"2017-02-1210:
22:
22",
"value":
12
},
{…..},
……
]
},
{…..},
…..
]
}
}
4.4数据流（datastream）
4.4.1新增
HTTP方法
POST
URL
http:
///devices//datastreams
HTTP头部
api-key:
xxxx-ffff-zzzzz，可以为设备级别的Key
HTTP内容
{
"id":
"datastream_id1”,
//以下参数可选
"tags":
["Tag1","Tag2"],
"unit":
"celsius",
"unit_symbol":
"C",
//只有MODBUS设备填写，MODBUS命令，16进制字节字符串
"cmd":
"4411",
//只有MODBUS设备填写，采集间隔，秒
"interval":
60,
//只有MODBUS设备填写，最终结果处理方法，寄存器地址从A0开始,多个公式用分号间隔
"formula":
"（A0+A1）*A2",
}
请求返回
{
"errno":
0,
"error":
“succ”,
"data":
{
"ds_uuid":
"FWFW-WFWW-EWFW-WW"//平台分配数据流唯一ID
}
}
说明：
✓对于普通的非modbus设备，不要添加cmd、interval、formula等字段，否则可能会导致增加数据流失败。
✓新增数据流的id字段不能为空，否则可能会添加失败
✓新增数据流的id字段支持中文，但最好为英文，这样可以规避字符编码带来的问题。
4.4.2更新
更新数据流主要更新数据流的单位、标签等信息。
HTTP方法
PUT
URL
http:
///devices//datastreams/
HTTP头部
api-key:
xxxx-ffff-zzzzz可以为数据流级别的key
HTTP内容
{
"tags":
["Tag1","Tag2"],
"unit":
"celsius",
"unit_symbol":
"C",
"cmd":
"4411",
"interval":
60,
"formula":
"（A0+A1）*A2",
}
请求返回
{
"errno":
0,
"error":
“succ”,
}
说明：
请求消息中的的任何字段都可以为空。
对于非MODBUS设备不要更新其cmd、interval、formula等字段，否则可能失败
。
4.4.3查看
A查看某设备单个数据流信息
HTTP方法
GET
URL
http:
///devices//datastreams/
HTTP头部
api-key:
xxxx-ffff-zzzzz可以为数据流级别的key
请求返回
{
"errn
升级会员 