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

ICS 35.100.20CCS L 72DB36江西省地方标准DB36/T 18452023农村人居环境长效管护平台数据交换规范Data exchange specification for long-term management and protection platform ofrural living environment2023 - 09 - 18 发布2024 - 03 - 01 实施江西省市场监督管理局发 布DB36/T 18452023目次前言 . II引言 . III1  范围 . 12  规范性引用文件 . 13  术语和定义 . 14  数据交换流程 . 15  接口要求 . 26  接口设计 . 37  设备上报频次 . 48  设备离线存储、断点续传 . 4附录 A（资料性）接口设计标准 .5附录 B（资料性）返回接口示例 .22IDB36/T 18452023前言本文件按照GB/T 1.12020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由江西省农业农村厅提出并归口。本文件起草单位：江西省农业技术推广中心、江西电信信息产业有限公司、江西省数字乡村研究院。本文件主要起草人：陈勋洪、钟志宏、杨眉、黄建昌、张敏、徐军亮、姜凯文、邓碧岩、官文峰。IIDB36/T 18452023引言当前农村人居环境长效管护平台接入的物联网监测平台较多，涉及设备品牌繁多，各厂家平台及设备数据标准不一，从而导致对接成本、维护成本、运营成本的增加，制约了平台的快速建设推广。为有效加强全省农村人居环境长效管护平台建设的统一规划、统一管理、协调运行和维护服务，建立健全全省农村人居环境长效管护平台的数据交换标准，推动农村人居环境长效管护平台的建设运营有序发展，提升各级政府及其部门的农村人居环境治理水平，现根据国家、地方相关文件要求和标准，结合我省农村人居环境治理现状和发展要求，制定本文件。IIIDB36/T 18452023农村人居环境长效管护平台数据交换规范1 范围本文件规定了农村人居环境长效管护平台接口数据交换的相关术语和定义、数据交换流程、接口要求、接口设计、设备数据上报频次、设备数据断点续传。本文件适用于农村人居环境长效管护平台接口设计。2 规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 28168  信息技术  中间件  消息中间件技术规范GB/T 337452017物联网 术语GB/T 36478.12018 物联网 信息交换和共享 第1部分：总体架构3 术语和定义GB/T 337452017、GB/T 36478.12018界定的以及下列术语和定义适用于本文件。3.1农村人居环境长效管护平台 rural living environment long-term management platform采用物联网、云计算、大数据、AI等新一代信息技术建设的农村人居环境长效管护信息平台。包含物联云判、管护调度、乡村大脑、四大治理、“万村码上通”小程序等模块，具有针对农村人居环境事件“投诉、整改、反馈、监督”和人、车、事、物、情“一图统揽、一网统调”等功能。3.2数据采集终端 data acquisition terminal用于监测农村人居环境的设备，如垃圾桶满溢监测设备、人员作业跟踪定位卡牌、厕所气味探测设备、污水水质检测设备、车载跟踪定位设备。3.3物联网监测数据共享模块/系统 IoT monitoring data sharing module / system农村人居环境长效管护平台中采集物联网动态监测数据并提供数据共享服务的模块/系统。4 数据交换流程1DB36/T 18452023依据GB/T 36478.12018中的规定，通过数据接口方式，数据提供方通过物联网系统将交换和共享的数据导入到对应的模块/系统；数据需求方从物联网相应模块/系统获取物联网数据，数据交换流程如图1所示。图1 数据交换示意图5 接口要求5.1 约定5.1.1 数据交换基于 RESTful API，采用标准 JSON 数据格式。5.1.2 为便于提供方和需求方统一调用数据，接口方法和参数宜采用英文单词命名。5.2 协议使用HTTPS协议。5.3 消息格式5.3.1 请求头不同的接口应具有同一请求头，请求头的名称和含义描述应符合表1。2名称描述必选Host指定请求的服务器的域名和端口号必选Connection表示是否需要持久连接必选Accept表示接受所接收的内容类型必选Content-type请求的与实体对应的 MIME 信息必选Content-Length请求的内容长度必选CookieHTTP 请求发送时，会把保存在该请求域名下的所有cookie 值一起发送给网站服务器可选User-agent内容包含发出请求的用户信息可选参数名必选类型说明给出字段所代表的参数名描述参数是否为必选描述数据的数据类型对参数的描述及补充说明DB36/T 18452023表 1  请求头5.3.2 请求参数不同接口功能，其请求参数存在差异。请求参数格式示例见表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/T 184520236.2 返回状态码 code接口返回状态码见表3。表 3 返回状态码 code 及描述7 设备上报频次设备主要数据上报频次如下：智能垃圾桶：1 条/6 小时。水质监测设备：1 条/6 小时。气味探测器：1 条/6 小时。车载：1 条/分钟。卡牌：1 条/5 分钟。环境探测器：1 条/2 小时。8 设备离线存储、断点续传设备应具备在网络不佳时本地存储数据，待网络通畅时上传未上报数据的功能。消息机制应符合GB/T 28168的规定。4参数名必选类型说明appId是String由平台颁发appSecret是String由平台颁发DB36/T 18452023附 录 A（资料性）接口设计标准A.1 服务调用步骤A.1.1 数据需求方将授权Id（appId）和密钥（appSecret）进行SHA-2加密传输，数据提供方在SHA-2加密算法的基础上进行了加盐操作。盐是随机生成的字符串。我们将盐与原始数据连接在一起，然后将连接后的字符串加密处理返回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 产品列表获取农村人居环境长效管护平台标准物联网产品，接口要求如下：接口方法：getProductList；接口路径：api/open/product/；请求方式：POST。参数见表A.2。表 A.2 getProductList5参数名必选类型说明token是String通信证 keyproductName否String产品名称productProtocol否integer产品协议：integer,产品协议：1.T-LINK 协议 2.MQTT 协议 3.LWM2M协议 4.TUP 协议 5.HTTP 协议6.JT/T808 7.TCP 协议 8.私有 TCP(网关子设备协议) 9.私有 UDP(网关子设备协议) 10.网关产品 MQTT(网关产品协议) 11.南向云productId是int产品 id参数名必选类型说明token是String通信证 keynetStatus否int设备状态deviceNo否String设备编号productId是String产品 idgridCode是String区域 code（依据中国行政区域编码划分规则）DB36/T  18452023返回示例见附录B.2。A.3.2 设备列表获取农村人居环境长效管护平台设备列表的接口要求如下：接口方法：getDeviceList；接口路径：api/open/device/；请求方式：POST。请求参数见表A.3。表 A.3 getDeviceList返回示例见附录 B.3。A.3.3 新建产品添加产品（产品为设备直连+非NB网关协议）的接口要求如下：接口方法：createProduct；接口路径：api/open/product/；请求方式：POST。请求参数见表A.4。6参数名必选类型说明token是String通信证 keyDB36/T 18452023表 A.4 createProduct请求body（数据类型application/json;charset=utf-8）"accessType": 1,"authType": 0,"dataEncryption": 0,"deviceModel": "string","encryptionType": 0,"endpointFormat": 0,"lwm2mEdrxTime": null,"manufacturerId": "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：产品分类（必填）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/T808 7.TCP协议 10.网关MQTT协议authType：认证方式 1:特征串认证,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/T 18452023dataEncryption：数据加密方式 1:sm1,2:sm2,3:sm4,4:dtls,5:明文（只支持MQTT/LWM2M）encryptionType：安全类型(只支持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.PSM 2.DRX 3.eDRXlwm2mEdrxTime:eDRX模式时间窗(LWM2M协议,当省电模式为3时,必填):20  10485.76 间的值,精确到小数点后两位productDesc：产品描述（选填）：产品描述最多100个字符tupDeviceModel:设备型号，选填，设备直连并且非JT/T808协议产品必填返回示例见附录 B.4。A.3.4 删除产品删除产品数据，如果产品下有设备数据，则无法删除产品。删除产品的接口要求如下：接口方法：deleteProduct；接口路径：api/open/product/；请求方式：DELETE。请求参数见表 A.5。表 A.5 deleteProduct返回示例见附录 B.5A.3.5 更新产品更新产品数据的接口要求如下：接口方法：updateProduct；接口路径：api/open/product/；请求方式：PUT。请求参数见表 A.6。8参数名必选类型说明token是String通信证 keymasterKey是StringmasterKey 在该设备所属产品的概况中可以查看gridCode是String区域 code(依据中国行政区域编码划分规则）参数名必选类型说明token是String通信证 keygridCode是String区域 code(依据中国行政区域编码划分规则）DB36/T 18452023表 A.6 updateProduct请求 body（数据类型 application/json;charset=utf-8）"endpointFormat": null,"powerModel": null,"productDesc": "string","productId": 0,"productName": "string","lwm2mEdrxTime": null描述：productId: 产品 ID，必填productName：产品名称，产品名称租户内不能重复，必填productDesc：产品描述，选填endpointFormat ： endpoint 类 型 （ Lwm2m 协 议 必 填 ）1.IMEI 2.URN:IMEI:#3.URN:IMEI-IMSI: #-# 4.URN:IMEI+SM9注：认证方式为 SM9 认证时，endpoint 类型为 4认证方式为 IMEI 认证、sm2 认证时，endpoint 类型为 1、2、3powerModel：省电模式（Lwm2m 协议必填） 1.PSM 2.DRX 3.eDRXlwm2mEdrxTime：eDRX 模式时间窗（LWM2M 协议，当省电模式为 3 时，必填）:20  10485.76间的值，精确到小数点后两位返回示例见附录 B.6。A.3.6 创建设备增加设备的接口要求如下：接口方法：createDevice；接口路径：api/open/device/；请求方式：POST。请求参数见表 A.7。表 A.7 createDevice9参数名必选类型说明token是String通信证 keyproductId是int产品 iddeviceIds是String可以删除多个设备（最多支持 200 个设备）。多个设备 id，中间以逗号 "," 隔开 。masterKey是StringmasterKey 在该设备所属产品的概况中可以查看gridCode是String区域 code（依据中国行政区域编码划分规则）deviseName是String设备名称deviceSn是String设备编号imei是String设备 imei 号productId是int产品 idoperator是String操作人参数名必选类型说明token是String通信证 keymasterKey是StringmasterKey 在该设备所属产品的概况中可以查看gridCode是String区域 code（依据中国行政区域编码划分规则）DB36/T  18452023返回示例见附录 B.7。A.3.7 删除设备删除设备数据的接口要求如下：接口方法：deleteDevice；接口路径：api/open/device/；请求方式：DELETE。请求参数见表 A.8。表 A.8 deleteDevice返回示例见附录 B.8。A.3.8 更新设备更新设备数据的接口要求如下：接口方法：updateDevice；接口路径：api/open/device/；请求方式：PUT。请求参数见表 A.9。表 A.9 updateDevice请求 body（数据类型 application/json;charset=utf-8）10参数名必选类型说明token是String通行证 keymasterKey是StringmasterKey 在该设备所属产品的概况中可以查看productId是int产品 IdsearchValue否String可填值：属性名称，属性gridCode否String区域 code（依据中国行政区域编码划分规则）pageNow否int当前页数pageSize否int每页记录数DB36/T 18452023返回示例见附录 B.9。A.3.9 获取物模型查询属性列表信息，获取标准数据参数名称及数据类型的接口要求如下：接口方法：queryPropertyList；接口路径：api/open/model/properties/；请求方式：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当前页数pageSize否int每页记录数参数名必选类型说明token是String通信证 keymasterKey是StringmasterKey 在该设备所属产品的概况中可以查看standardVersion否String标准物模型版本号thirdType否int三级分类 idDB36/T 18452023接口路径：api/open /standardModel/；请求方式：GET。请求参数见表 A.11。表 A.11 queryStandardModel返回示例见附录 B.11。A.3.11 获取服务列表信息获取农村人居环境长效管护平台服务列表信息的接口要求如下：接口方法：queryPropertyList；接口路径：api/open/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/T  18452023请求 Body（数据类型 application/json;charset=utf-8）"deviceId": "be04c3519c5740c1b82fe0fceb9d2e82","uploadTime": "2021-07-19 16: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,"powerThreshold": 0,"fullState": "0","inclineState": "0","high": 464,"deviceNo": null,"imei": null返回示例见附录 B.13。A.3.13 人员卡牌设备数据上报卡牌设备上报数据的接口要求如下：接口方法：uploadCardData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表 A.14。表 A.14 uploadCardData13参数名必选类型说明token是String通信证 keybody是String智慧厕改设备标准物模型参数名必选类型说明token是String通信证 keybody是String人员卡牌标准物模型DB36/T  18452023请求 body"deviceId": "e978A.35e8c6d4e9fbe9286cedc6aedcd","uploadTime": null,"longitude": "114.1700000","latitude": "26.4400000","speed": 2,"direction": null,"signal": null,"battery": "31","gpsFlag": null,"receiveTime": "2021-07-21 18:13:06.133","createTime": "2021-07-22 09:55:54","heading": null,"valid": "0","imei": null返回示例见附录 B.14。A.3.14 智慧厕改设备数据上报厕改设备上报数据的接口要求如下：接口方法：uploadToiletData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表 A.15。表 A.15 uploadToiletData请求 body"deviceId": "15067733001","deviceName": null,"uploadTime": "2021-08-27 15:49:00","humWoman": null,14参数名必选类型说明token是String通信证 keybody是String污水监测设备标准物模型DB36/T 18452023"tempWoman": null,"h2sWoman": null,"nh3Woman": null,"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.16。表 A.16 uploadWaterData请求 body"deviceId": "15036215BK7201SN001625","uploadTime": "2021-08-04 17: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/T 18452023A.3.16 车载设备数据上报车载设备上报数据的接口要求如下：接口方法：uploadCarData；接口路径：api/open/uploadData/；请求方式：POST。请求参数见表 A.17。表 A.17  uploadCarData请求 body："deviceId": "a6fdce27e9844ba5b0b9f97ae7d40136","uploadTime": "2021-04-02 15:42:17","batteryVoltage": 360,"batteryStatus": 0