物联网云平台对外数据接口（PDF40页）

浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档1物联网云平台对外数据接口设计说明书文件标示研发部当前版本V1.2作者谢朝明文件状态【】初稿【√】修改【】发布日期2015-07-22浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档2修订历史记录日期版本说明作者2015-07-22V1.0设计初稿谢朝明2015-07-23V1.0修改稿宁应财2015-07-23V1.1修正修改，增加设备控制的定时控制参数，增加通过终端获取所有传感器和控制设备协议，获取最后一组数据协议，修改部分参数名称谢朝明2015-10-08V1.2增加地块及地块相关数据查询功能陈旭浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档31简介物联网子系统对外服务接口是物联网系统平台对外部终端设备或第三方应用调用本系统的功能服务接口。2接口使用注意事项1、接口标准符合Rest风格2、Get方式表示获取,Post方式表示添加，Put方式表示修改，Delete方式表示删除。当有不支持Put或Delete方式的客户端时，可使用Post代替，在URL后面增加参数_method服务端可自动转为Put或Delete方式。3、使用Get方式时需要注意对参数URLEncode4、使用格式http://{url}/api/{版本}/{资源}/{动作}或者http://{url}/api/{版本}/{资源}/{id}id为整数，表示对某一个资源的一个编号所对应的记录的操作。5、需要登录的操作在URL后增加ut参数来表示用户令牌的字符串。6、使用统一的格式返回{code:10100a,msg:错误信息,result:{JsonObject}}7、code为0时表示执行成功，其他六位编码为状态码，使用16进制字符串，如10057e等，错误编码有英文字母存在的则全为小写。msg为状态描述，当借口需要数据返回时Result为JsonObject或JsonArray，当操作无数据返回时则该参数在返回对象中不存在。3接口说明注意所有的数据返回的格式是指{code:10100a,msg:错误信息,result:{JsonObject}}中的JsonObject的数据内容。浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档43.1登录接口说明：用户登录有效期为2小时。接口URL{user_name:myusertest,password:y6r7uej34}登录成功返回结果参数类型必选可空默认值说明示例user_tokenSTRING必须不可空用户令牌D58E3582AFA99040E27B92B13C8F2280user_idINT必须不可空用户id1示例{user_token:D58E3582AFA99040E27B92B13C8F2280,user_id:1}3.2获取终端下所有设备说明：用户必须先登录才能获取数据。接口URL{id}/deviceHTTP方法GET浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档5返回格式JSON授权/登录需要相关说明获取终端下的所有设备传入参数通过URL传递参数参数类型必选可空默认值说明示例{id}INT必须不可空终端id1示例/openapi/v1/terminal/1/device返回结果参数类型必选可空默认值说明示例countINT必须不可空数据总条数1data_arrayJSONArr必须不可空┣━device_idINT必须不可空设备编号（可用在传感器的sensor_id或控制设备的ctrl_device_id）1┣━device_type_idINT必须不可空设备类型编号见附录1┣━sensor_type_idINT必须不可空传感器类型编号见附录当非传感器类型时为0161示例{count:1,data_array:[{device_id:1,device_type_id:1,sensor_type_id:161}]浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档6}3.3获取终端下的最后一组数据说明：用户必须先登录才能获取数据。接口URL{id}/lastdataHTTP方法GET返回格式JSON授权/登录需要相关说明获取终端下的最后一组数据传入参数通过URL传递参数参数类型必选可空默认值说明示例{id}INT必须不可空终端id1示例/openapi/v1/terminal/1/lastdata返回结果参数类型必选可空默认值说明示例countINT必须不可空数据总条数1data_arrayJSONArr必须不可空┣━sensor_idINT必须不可空设备编号（可用在传感器的sensor_id或控制设备的ctrl_device_id）1┣━data_idINT必须不可空数据ID1┣━data_valueSTRING必须不可空数据值1065浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档7┣━sensor_type_idINT必须不可空传感器类型编号见附录161┣━collect_timeSTRING必须不可空采集时间2015-03-0508:08:05示例{count:1,data_array:[{sensor_id:1,“data_id”:1,“data_value”:1065sensor_type_id:161collect_time:“2015-03-0508:08:05”}]}3.4分页获取传感器数据说明：用户必须先登录才能获取数据。接口URL┣━data_idINT必须不可空数据ID1┣━data_valueSTRING必须不可空数据值1065┣━collect_timeSTRING必须不可空采集时间2015-03-0508:08:05┣━sensor_idINT必须不可空设备ID25示例{count:23,data_array:[{data_id:1,data_value:1065,collect_time:2015-03-0508:08:05,sensor_id:25}浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档9]}3.5地块查询接口URL（如果参数中带有ut的话，可不输入该参数，系统将会自动去取ut相关参数进行判断，当ut与user_id同时存在时，将优先使用ut相关参数）1示例user_id=1返回结果参数类型必选可空默认值说明示例countINT必须不可空地块总数1land_arrayJSONArr必须不可空┣━land_idINT必须不可空地块编号1┣━land_nameSTRING必须不可空地块名称实验地块浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档10┣━app_typeINT必须不可空所属应用类型，1：设施农业,2：农林四情，3：虫情监测，4：墒情监测，5：温室大棚，6：大田种植2┣━station_idINT必须不可空所属站点ID1┣━geologyINT必须可空地块性质类型，0：褐土，1：石质土，2：山地草甸土，3：滨海盐土，4：棕壤，5：红粘土1┣━acreageINT必须可空单位(亩)161┣━longitudeDecimal必须不可空经度11.123456┣━latitudedecimal必须不可空纬度120.123456┣━create_dateDate必须不可空地块创建日期2015-10-1811:10┣━remarkSTRING必须可空备注这是实验用地块┣━pic_urlSTRING必须可空地块图片地址：{count:2,land_array:[{land_id:1,land_name:实验地块1,app_type:2,station_id:1,geology:2,浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档11acreage:123,longitude:11.123456,latitude:120.123456,create_date:2015-10-0810:11,remark:这是实验地块,pic_url:},{land_id:2,land_name:实验地块2,app_type:3,station_id:2,geology:3,acreage:12,longitude:11.123456,latitude:120.123456,create_date:2015-10-0810:15,remark:这是实验地块2,pic_url:}]}3.6根据用户编号获得相关登陆TOKEN接口URL{user_token:D58E3582AFA99040E27B92B13C8F2280,user_id:1}3.7获取站点编号下所有设备接口URL{id}/deviceHTTP方法GET返回格式JSON授权/登录不需要相关说明获取站点下所有设备信息传入参数通过URL传递参数参数类型必选可空默认说明示例浙江托普云农科技股份有限公司致力于农业信息化的发展研发部内部文档13值{id}INT必须不可空站点id1user_idINT非必须不可空物联网用户登陆成功后的ID（如果参数中带有