DB36_T 1845-2023 农村人居环境长效管护平台数据交换规范.docx

《DB36_T 1845-2023 农村人居环境长效管护平台数据交换规范.docx》由会员分享，可在线阅读，更多相关《DB36_T 1845-2023 农村人居环境长效管护平台数据交换规范.docx（61页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、ICS35.100.20CCSL72DB36江西省地方标准DB36/T18452023农村人居环境长效管护平台数据交换规范Dataexchangespecificationforlong-termmanagementandprotectionplatformofrurallivingenvironment2023-09-18发布2024-03-01实施江西省市场监督管理局发布DB36/T18452023目次前言.II引言.III1范围.12规范性引用文件.13术语和定义.14数据交换流程.15接口要求.26接口设计.37设备上报频次.48设备离线存储、断点续传.4附录A（资料性）接口设计标准.

2、5附录B（资料性）返回接口示例.22IDB36/T18452023前言本文件按照GB/T1.12020标准化工作导则第1部分：标准化文件的结构和起草规则的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由江西省农业农村厅提出并归口。本文件起草单位：江西省农业技术推广中心、江西电信信息产业有限公司、江西省数字乡村研究院。本文件主要起草人：陈勋洪、钟志宏、杨眉、黄建昌、张敏、徐军亮、姜凯文、邓碧岩、官文峰。IIDB36/T18452023引言当前农村人居环境长效管护平台接入的物联网监测平台较多，涉及设备品牌繁多，各厂家平台及设备数据标准不一，从而导致对接成

3、本、维护成本、运营成本的增加，制约了平台的快速建设推广。为有效加强全省农村人居环境长效管护平台建设的统一规划、统一管理、协调运行和维护服务，建立健全全省农村人居环境长效管护平台的数据交换标准，推动农村人居环境长效管护平台的建设运营有序发展，提升各级政府及其部门的农村人居环境治理水平，现根据国家、地方相关文件要求和标准，结合我省农村人居环境治理现状和发展要求，制定本文件。IIIDB36/T18452023农村人居环境长效管护平台数据交换规范1范围本文件规定了农村人居环境长效管护平台接口数据交换的相关术语和定义、数据交换流程、接口要求、接口设计、设备数据上报频次、设备数据断点续传。本文件适用于农村

4、人居环境长效管护平台接口设计。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T28168信息技术中间件消息中间件技术规范GB/T337452017物联网术语GB/T36478.12018物联网信息交换和共享第1部分：总体架构3术语和定义GB/T337452017、GB/T36478.12018界定的以及下列术语和定义适用于本文件。3.1农村人居环境长效管护平台rurallivingenvironmentlong-termmanageme

5、ntplatform采用物联网、云计算、大数据、AI等新一代信息技术建设的农村人居环境长效管护信息平台。包含物联云判、管护调度、乡村大脑、四大治理、“万村码上通”小程序等模块，具有针对农村人居环境事件“投诉、整改、反馈、监督”和人、车、事、物、情“一图统揽、一网统调”等功能。3.2数据采集终端dataacquisitionterminal用于监测农村人居环境的设备，如垃圾桶满溢监测设备、人员作业跟踪定位卡牌、厕所气味探测设备、污水水质检测设备、车载跟踪定位设备。3.3物联网监测数据共享模块/系统IoTmonitoringdatasharingmodule/system农村人居环境长效管护平台中

6、采集物联网动态监测数据并提供数据共享服务的模块/系统。4数据交换流程1DB36/T18452023依据GB/T36478.12018中的规定，通过数据接口方式，数据提供方通过物联网系统将交换和共享的数据导入到对应的模块/系统；数据需求方从物联网相应模块/系统获取物联网数据，数据交换流程如图1所示。图1数据交换示意图5接口要求5.1约定5.1.1数据交换基于RESTfulAPI，采用标准JSON数据格式。5.1.2为便于提供方和需求方统一调用数据，接口方法和参数宜采用英文单词命名。5.2协议使用HTTPS协议。5.3消息格式5.3.1请求头不同的接口应具有同一请求头，请求头的名称和含义描述应符合

7、表1。2名称描述必选Host指定请求的服务器的域名和端口号必选Connection表示是否需要持久连接必选Accept表示接受所接收的内容类型必选Content-type请求的与实体对应的MIME信息必选Content-Length请求的内容长度必选CookieHTTP请求发送时，会把保存在该请求域名下的所有cookie值一起发送给网站服务器可选User-agent内容包含发出请求的用户信息可选参数名必选类型说明给出字段所代表的参数名描述参数是否为必选描述数据的数据类型对参数的描述及补充说明DB36/T18452023表1请求头5.3.2请求参数不同接口功能，其请求参数存在差异。请求参数格式示

8、例见表2。表2请求参数格式示例5.4返回数据格式返回数据应包含：返回状态码、返回状态信息、具体数据。以json格式为例。code:0,msg:success,data:/json格式的具体数据6接口设计6.1基本要求接口设计应满足如下要求：接口地址：http:/服务器地址:端口号/api/open/接口方法名。接口协议：WebService。编码方式：UTF-8。交换格式：JSON。接口设计参考附录A，接口返回示例见附录B。3参数名code值描述0成功999失败1111正在处理DB36/T184520236.2返回状态码code接口返回状态码见表3。表3返回状态码code及描述7设备上报频次设

9、备主要数据上报频次如下：智能垃圾桶：1条/6小时。水质监测设备：1条/6小时。气味探测器：1条/6小时。车载：1条/分钟。卡牌：1条/5分钟。环境探测器：1条/2小时。8设备离线存储、断点续传设备应具备在网络不佳时本地存储数据，待网络通畅时上传未上报数据的功能。消息机制应符合GB/T28168的规定。4参数名必选类型说明appId是String由平台颁发appSecret是String由平台颁发DB36/T18452023附录A（资料性）接口设计标准A.1服务调用步骤A.1.1数据需求方将授权Id（appId）和密钥（appSecret）进行SHA-2加密传输，数据提供方在SHA-2加密算法的

10、基础上进行了加盐操作。盐是随机生成的字符串。我们将盐与原始数据连接在一起，然后将连接后的字符串加密处理返回token令牌。后续在调用设备管理和设备数据管理相关接口时需使用该令牌。获取令牌接口参考A.2.1。A.1.2数据提供方数据提供方应满足如下要求：获取请求数据进行相关业务处理；根据数据需求方的请求输出数据；返回调用结果给数据需求方。A.2身份认证获取令牌接口应满足如下要求：接口方法：getToken；接口路径：api/open/oauth/；请求方式：POST。请求参数见表A.1。表A.1getToken返回示例见附录B.1。A.3设备管理A.3.1产品列表获取农村人居环境长效管护平台标准

11、物联网产品，接口要求如下：接口方法：getProductList；接口路径：api/open/product/；请求方式：POST。参数见表A.2。表A.2getProductList5参数名必选类型说明token是String通信证keyproductName否String产品名称productProtocol否integer产品协议：integer,产品协议：1.T-LINK协议2.MQTT协议3.LWM2M协议4.TUP协议5.HTTP协议6.JT/T8087.TCP协议8.私有TCP(网关子设备协议)9.私有UDP(网关子设备协议)10.网关产品MQTT(网关产品协议)11.南向云pr

12、oductId是int产品id参数名必选类型说明token是String通信证keynetStatus否int设备状态deviceNo否String设备编号productId是String产品idgridCode是String区域code（依据中国行政区域编码划分规则）DB36/T18452023返回示例见附录B.2。A.3.2设备列表获取农村人居环境长效管护平台设备列表的接口要求如下：接口方法：getDeviceList；接口路径：api/open/device/；请求方式：POST。请求参数见表A.3。表A.3getDeviceList返回示例见附录B.3。A.3.3新建产品添加产品（产品

13、为设备直连+非NB网关协议）的接口要求如下：接口方法：createProduct；接口路径：api/open/product/；请求方式：POST。请求参数见表A.4。6参数名必选类型说明token是String通信证keyDB36/T18452023表A.4createProduct请求body（数据类型application/json;charset=utf-8）accessType:1,authType:0,dataEncryption:0,deviceModel:string,encryptionType:0,endpointFormat:0,lwm2mEdrxTime:null,ma

14、nufacturerId:string,networkType:0,nodeType:1,payloadFormat:0,powerModel:0,productDesc:string,productName:string,productProtocol:0,productType:string,secondaryType:string,thirdType:string,tupIsThrough:0,tupDeviceModel:string描述：productName：产品名称（必填）：产品名称最多64个字符，产品名称必须包含数字或字母或汉字，产品名称不能重复productType：产品分类

15、（必填）secondaryType：二级分类（必填）thirdType：三级分类（必填）nodeType：节点类型（必填）：1.设备，2.网关accessType：接入类型（必填）:1.设备直连，2.网关接入，3.南向云接入（只支持1）networkType：网络类型（必填）:1.WIFI,2.移动蜂窝数据3.NB-IoT,4.以太网,5.蓝牙,6.ZigBee（只支持1/2/3/4）productProtocol：产品协议（必填）：只支持1.T-LINK协议2.MQTT协议3.LWM2M协议5.HTTP协议6.JT/T8087.TCP协议10.网关MQTT协议authType：认证方式1:特

16、征串认证,2:SM9认证,3:证书认证,4:IMEI认证，5:SIMID认证，6:SM2认证，7:IPV6标识认证payloadFormat：消息格式1:json，2:紧凑二进制7参数名必选类型说明token是String通信证keymasterKey是StringmasterKey在该设备所属产品的概况中可以查看productId是int产品idgridCode是String区域code(依据中国行政区域编码划分规则）DB36/T18452023dataEncryption：数据加密方式1:sm1,2:sm2,3:sm4,4:dtls,5:明文（只支持MQTT/LWM2M）encryptio

17、nType：安全类型(只支持MQTT,TCP协议)0:一机一密，1:一型一密tupIsThrough：是否透传：0.透传，1不透传（JT/T808，tcp协议，只有透传，消息格式必须只能传null）deviceModel：JT/T808协议设备型号manufacturerId：JT/T808协议制造商IDendpointFormat:Endpoint格式（LWM2M协议必填）:1.IMEI2.URN:IMEI:#3.URN:IMEI-IMSI:#-#4.URN:IMEI+SM9powerModel：省电模式（LWM2M协议必填）：1.PSM2.DRX3.eDRXlwm2mEdrxTime:eD

18、RX模式时间窗(LWM2M协议,当省电模式为3时,必填):2010485.76间的值,精确到小数点后两位productDesc：产品描述（选填）：产品描述最多100个字符tupDeviceModel:设备型号，选填，设备直连并且非JT/T808协议产品必填返回示例见附录B.4。A.3.4删除产品删除产品数据，如果产品下有设备数据，则无法删除产品。删除产品的接口要求如下：接口方法：deleteProduct；接口路径：api/open/product/；请求方式：DELETE。请求参数见表A.5。表A.5deleteProduct返回示例见附录B.5A.3.5更新产品更新产品数据的接口要求如下：

19、接口方法：updateProduct；接口路径：api/open/product/；请求方式：PUT。请求参数见表A.6。8参数名必选类型说明token是String通信证keymasterKey是StringmasterKey在该设备所属产品的概况中可以查看gridCode是String区域code(依据中国行政区域编码划分规则）参数名必选类型说明token是String通信证keygridCode是String区域code(依据中国行政区域编码划分规则）DB36/T18452023表A.6updateProduct请求body（数据类型application/json;charset=ut

20、f-8）endpointFormat:null,powerModel:null,productDesc:string,productId:0,productName:string,lwm2mEdrxTime:null描述：productId:产品ID，必填productName：产品名称，产品名称租户内不能重复，必填productDesc：产品描述，选填endpointFormat：endpoint类型（Lwm2m协议必填）1.IMEI2.URN:IMEI:#3.URN:IMEI-IMSI:#-#4.URN:IMEI+SM9注：认证方式为SM9认证时，endpoint类型为4认证方式为IMEI

21、认证、sm2认证时，endpoint类型为1、2、3powerModel：省电模式（Lwm2m协议必填）1.PSM2.DRX3.eDRXlwm2mEdrxTime：eDRX模式时间窗（LWM2M协议，当省电模式为3时，必填）:2010485.76间的值，精确到小数点后两位返回示例见附录B.6。A.3.6创建设备增加设备的接口要求如下：接口方法：createDevice；接口路径：api/open/device/；请求方式：POST。请求参数见表A.7。表A.7createDevice9参数名必选类型说明token是String通信证keyproductId是int产品iddeviceIds是S

22、tring可以删除多个设备（最多支持200个设备）。多个设备id，中间以逗号,隔开。masterKey是StringmasterKey在该设备所属产品的概况中可以查看gridCode是String区域code（依据中国行政区域编码划分规则）deviseName是String设备名称deviceSn是String设备编号imei是String设备imei号productId是int产品idoperator是String操作人参数名必选类型说明token是String通信证keymasterKey是StringmasterKey在该设备所属产品的概况中可以查看gridCode是String区域co

23、de（依据中国行政区域编码划分规则）DB36/T18452023返回示例见附录B.7。A.3.7删除设备删除设备数据的接口要求如下：接口方法：deleteDevice；接口路径：api/open/device/；请求方式：DELETE。请求参数见表A.8。表A.8deleteDevice返回示例见附录B.8。A.3.8更新设备更新设备数据的接口要求如下：接口方法：updateDevice；接口路径：api/open/device/；请求方式：PUT。请求参数见表A.9。表A.9updateDevice请求body（数据类型application/json;charset=utf-8）10参数名

24、必选类型说明token是String通行证keymasterKey是StringmasterKey在该设备所属产品的概况中可以查看productId是int产品IdsearchValue否String可填值：属性名称，属性gridCode否String区域code（依据中国行政区域编码划分规则）pageNow否int当前页数pageSize否int每页记录数DB36/T18452023返回示例见附录B.9。A.3.9获取物模型查询属性列表信息，获取标准数据参数名称及数据类型的接口要求如下：接口方法：queryPropertyList；接口路径：api/open/model/properties

25、/；请求方式：GET。请求参数见表A.10。表A.10queryPropertyList返回示例见附录B.10。A.3.10获取标准产品物模型标准农村人居环境长效管护平台标准物模型的接口要求如下：接口方法：queryStandardModel；11参数名必选类型说明token是String通信证keymasterKey是StringmasterKey在该设备所属产品的概况中可以查看productId是int产品IdsearchValue否String可填值：属性名称，属性标识符gridCode是String区域code（依据中国行政区域编码划分规则）pageNow否int当前页数pageSiz

26、e否int每页记录数参数名必选类型说明token是String通信证keymasterKey是StringmasterKey在该设备所属产品的概况中可以查看standardVersion否String标准物模型版本号thirdType否int三级分类idDB36/T18452023接口路径：api/open/standardModel/；请求方式：GET。请求参数见表A.11。表A.11queryStandardModel返回示例见附录B.11。A.3.11获取服务列表信息获取农村人居环境长效管护平台服务列表信息的接口要求如下：接口方法：queryPropertyList；接口路径：api/o

27、pen/model/properties/；请求方式：GET。请求参数见表A.12。表A.12queryPropertyList返回示例见附录B.12。A.3.12智能垃圾桶数据上报智能垃圾桶设备上报数据的接口要求如下：接口方法：uploadRubbishData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表A.13。表A.13uploadRubbishData12参数名必选类型说明token是String通信证keybody是String智能垃圾桶标准物模型DB36/T18452023请求Body（数据类型application/json;charse

28、t=utf-8）deviceId:be04c3519c5740c1b82fe0fceb9d2e82,uploadTime:2021-07-1916:29:41,latitude:0.0,longitude:0.0,errorCode:0000,fireState:0,tiltAngle:0,powerState:0,temperature:24,deviceState:null,batteryValue:0,locationFlag:null,fireThreshold:0,fullThreshold:0,tiltThreshold:null,batteryVoltage:3.63,power

29、Threshold:0,fullState:0,inclineState:0,high:464,deviceNo:null,imei:null返回示例见附录B.13。A.3.13人员卡牌设备数据上报卡牌设备上报数据的接口要求如下：接口方法：uploadCardData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表A.14。表A.14uploadCardData13参数名必选类型说明token是String通信证keybody是String智慧厕改设备标准物模型参数名必选类型说明token是String通信证keybody是String人员卡牌标准物模型D

30、B36/T18452023请求bodydeviceId:e978A.35e8c6d4e9fbe9286cedc6aedcd,uploadTime:null,longitude:114.1700000,latitude:26.4400000,speed:2,direction:null,signal:null,battery:31,gpsFlag:null,receiveTime:2021-07-2118:13:06.133,createTime:2021-07-2209:55:54,heading:null,valid:0,imei:null返回示例见附录B.14。A.3.14智慧厕改设备数据

31、上报厕改设备上报数据的接口要求如下：接口方法：uploadToiletData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表A.15。表A.15uploadToiletData请求bodydeviceId:15067733001,deviceName:null,uploadTime:2021-08-2715:49:00,humWoman:null,14参数名必选类型说明token是String通信证keybody是String污水监测设备标准物模型DB36/T18452023tempWoman:null,h2sWoman:null,nh3Woman:nu

32、ll,humMan:81.108642578125,tempMan:28.8987979888916,h2sMan:0.0010200000833719969,nh3Man:0.004118899814784527,squatIdleWoman:0,squatIdleMan:0,pfWoman:null,pfMan:null,createTime:null,imei:null返回示例见附录B.15。A.3.15污水监测设备上报数据污水监测设备上报数据的接口要求如下：接口方法：uploadWaterData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表A.

33、16。表A.16uploadWaterData请求bodydeviceId:15036215BK7201SN001625,uploadTime:2021-08-0417:01:03,temperature:29,conductivity:1,turbidity:1348.2,ph:7.31,doxygen:5.670000076293945,imei:null返回示例见附录B.16。15参数名必选类型说明token是String通信证keybody是String车载设备标准物模型DB36/T18452023A.3.16车载设备数据上报车载设备上报数据的接口要求如下：接口方法：uploadCarData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表A.17。表A.17uploadCarData请求body：deviceId:a6fdce27e9844ba5b0b9f97ae7d40136,uploadTime:2021-04-0215:42:17,batteryVoltage:360,batteryStatus:0