DB36/T 1845-2023 农村人居环境长效管护平台数据交换规范

ICS35.100.20

CCSL72

DB36

江西省地方标准

DB36/T1845—2023

农村人居环境长效管护平台数据交换规范

Dataexchangespecificationforlong-termmanagementandprotectionplatformof

rurallivingenvironment

2023-09-18发布2024-03-01实施

江西省市场监督管理局发布

DB36/T1845—2023

目  次

前言II

引言III

1范围1

2规范性引用文件1

3术语和定义1

4数据交换流程1

5接口要求2

6接口设计3

7设备上报频次4

8设备离线存储、断点续传4

附录A（资料性）接口设计标准5

附录B（资料性）返回接口示例22

I

DB36/T1845—2023

前  言

本文件按照GB/T1.1－2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起

草。

请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。

本文件由江西省农业农村厅提出并归口。

本文件起草单位：江西省农业技术推广中心、江西电信信息产业有限公司、江西省数字乡村研究院。

本文件主要起草人：陈勋洪、钟志宏、杨眉、黄建昌、张敏、徐军亮、姜凯文、邓碧岩、官文峰。

II

DB36/T1845—2023

引  言

当前农村人居环境长效管护平台接入的物联网监测平台较多，涉及设备品牌繁多，各厂家平台及设

备数据标准不一，从而导致对接成本、维护成本、运营成本的增加，制约了平台的快速建设推广。为有

效加强全省农村人居环境长效管护平台建设的统一规划、统一管理、协调运行和维护服务，建立健全全

省农村人居环境长效管护平台的数据交换标准，推动农村人居环境长效管护平台的建设运营有序发展，

提升各级政府及其部门的农村人居环境治理水平，现根据国家、地方相关文件要求和标准，结合我省农

村人居环境治理现状和发展要求，制定本文件。

III

DB36/T1845—2023

农村人居环境长效管护平台数据交换规范

1范围

本文件规定了农村人居环境长效管护平台接口数据交换的相关术语和定义、数据交换流程、接口要

求、接口设计、设备数据上报频次、设备数据断点续传。

本文件适用于农村人居环境长效管护平台接口设计。

2规范性引用文件

下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，

仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本

文件。

GB/T28168信息技术中间件消息中间件技术规范

GB/T33745—2017物联网术语

GB/T36478.1—2018物联网信息交换和共享第1部分：总体架构

3术语和定义

GB/T33745—2017、GB/T36478.1—2018界定的以及下列术语和定义适用于本文件。

3.1

农村人居环境长效管护平台rurallivingenvironmentlong-termmanagementplatform

采用物联网、云计算、大数据、AI等新一代信息技术建设的农村人居环境长效管护信息平台。包含

物联云判、管护调度、乡村大脑、四大治理、“万村码上通”小程序等模块，具有针对农村人居环境事

件“投诉、整改、反馈、监督”和人、车、事、物、情“一图统揽、一网统调”等功能。

3.2

数据采集终端dataacquisitionterminal

用于监测农村人居环境的设备，如垃圾桶满溢监测设备、人员作业跟踪定位卡牌、厕所气味探测设

备、污水水质检测设备、车载跟踪定位设备。

3.3

物联网监测数据共享模块/系统IoTmonitoringdatasharingmodule/system

农村人居环境长效管护平台中采集物联网动态监测数据并提供数据共享服务的模块/系统。

4数据交换流程

1

DB36/T1845—2023

依据GB/T36478.1—2018中的规定，通过数据接口方式，数据提供方通过物联网系统将交换和共享

的数据导入到对应的模块/系统；数据需求方从物联网相应模块/系统获取物联网数据，数据交换流程如

图1所示。

图1数据交换示意图

5接口要求

5.1约定

5.1.1数据交换基于RESTfulAPI，采用标准JSON数据格式。

5.1.2为便于提供方和需求方统一调用数据，接口方法和参数宜采用英文单词命名。

5.2协议

使用HTTPS协议。

5.3消息格式

5.3.1请求头

不同的接口应具有同一请求头，请求头的名称和含义描述应符合表1。

2

DB36/T1845—2023

表1请求头

名称描述必选

Host指定请求的服务器的域名和端口号必选

Connection表示是否需要持久连接必选

Accept表示接受所接收的内容类型必选

Content-type请求的与实体对应的MIME信息必选

Content-Length请求的内容长度必选

HTTP请求发送时，会把保存在该请求域名下的所有

Cookie可选

cookie值一起发送给网站服务器

User-agent内容包含发出请求的用户信息可选

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

DB36/T1845—2023

6.2返回状态码code

接口返回状态码见表3。

表3返回状态码code及描述

参数名code值描述

0成功

999失败

1111正在处理

7设备上报频次

设备主要数据上报频次如下：

——智能垃圾桶：1条/6小时。

——水质监测设备：1条/6小时。

——气味探测器：1条/6小时。

——车载：1条/分钟。

——卡牌：1条/5分钟。

——环境探测器：1条/2小时。

8设备离线存储、断点续传

设备应具备在网络不佳时本地存储数据，待网络通畅时上传未上报数据的功能。消息机制应符合

GB/T28168的规定。

4

DB36/T1845—2023

附录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

参数名必选类型说明

appId是String由平台颁发

appSecret是String由平台颁发

返回示例见附录B.1。

A.3设备管理

A.3.1产品列表

获取农村人居环境长效管护平台标准物联网产品，接口要求如下：

——接口方法：getProductList；

——接口路径：api/open/product/；

——请求方式：POST。

参数见表A.2。

表A.2getProductList

5

DB36/T1845—2023

参数名必选类型说明

token是String通信证key

productName否String产品名称

产品协议：integer,产品协议：

1.T-LINK协议2.MQTT协议3.LWM2M

协议4.TUP协议5.HTTP协议

productProtocol否integer6.JT/T8087.TCP协议8.私有TCP(网

关子设备协议)9.私有UDP(网关子设

备协议)10.网关产品MQTT(网关产品

协议)11.南向云

productId是int产品id

返回示例见附录B.2。

A.3.2设备列表

获取农村人居环境长效管护平台设备列表的接口要求如下：

——接口方法：getDeviceList；

——接口路径：api/open/device/；

——请求方式：POST。

请求参数见表A.3。

表A.3getDeviceList

参数名必选类型说明

token是String通信证key

netStatus否int设备状态

deviceNo否String设备编号

productId是String产品id

gridCode是String区域code（依据中国行政区域编码划分规则）

返回示例见附录B.3。

A.3.3新建产品

添加产品（产品为设备直连+非NB网关协议）的接口要求如下：

——接口方法：createProduct；

——接口路径：api/open/product/；

——请求方式：POST。

请求参数见表A.4。

6

DB36/T1845—2023

表A.4createProduct

参数名必选类型说明

token是String通信证key

请求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/T8087.TCP协议10.网关MQTT协议

authType：认证方式1:特征串认证,2:SM9认证,3:证书认证,4:IMEI认证，5:SIMID认证，6:SM2认证，

7:IPV6标识认证

payloadFormat：消息格式1:json，2:紧凑二进制

7

DB36/T1845—2023

dataEncryption：数据加密方式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协议制造商ID

endpointFormat:Endpoint格式（LWM2M协议必

填）:1.IMEI2.URN:IMEI:###############3.URN:IMEI-IMSI:###############-###############

4.URN:IMEI+SM9

powerModel：省电模式（LWM2M协议必填）：1.PSM2.DRX3.eDRX

lwm2mEdrxTime:eDRX模式时间窗(LWM2M协议,当省电模式为3时,必填):20～10485.76间的值,

精确到小数点后两位

productDesc：产品描述（选填）：产品描述最多100个字符

tupDeviceModel:设备型号，选填，设备直连并且非JT/T808协议产品必填

返回示例见附录B.4。

A.3.4删除产品

删除产品数据，如果产品下有设备数据，则无法删除产品。删除产品的接口要求如下：

——接口方法：deleteProduct；

——接口路径：api/open/product/；

——请求方式：DELETE。

请求参数见表A.5。

表A.5deleteProduct

参数名必选类型说明

token是String通信证key

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

productId是int产品id

gridCode是String区域code(依据中国行政区域编码划分规则）

返回示例见附录B.5

A.3.5更新产品

更新产品数据的接口要求如下：

——接口方法：updateProduct；

——接口路径：api/open/product/；

——请求方式：PUT。

请求参数见表A.6。

8

DB36/T1845—2023

表A.6updateProduct

参数名必选类型说明

token是String通信证key

gridCode是String区域code(依据中国行政区域编码划分规则）

请求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.IMEI2.URN:IMEI:###############

3.URN:IMEI-IMSI:###############-###############4.URN:IMEI+SM9

注：认证方式为SM9认证时，endpoint类型为4

认证方式为IMEI认证、sm2认证时，endpoint类型为1、2、3

powerModel：省电模式（Lwm2m协议必填）1.PSM2.DRX3.eDRX

lwm2mEdrxTime：eDRX模式时间窗（LWM2M协议，当省电模式为3时，必填）:20～10485.76

间的值，精确到小数点后两位

返回示例见附录B.6。

A.3.6创建设备

增加设备的接口要求如下：

——接口方法：createDevice；

——接口路径：api/open/device/；

——请求方式：POST。

请求参数见表A.7。

表A.7createDevice

参数名必选类型说明

token是String通信证key

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

gridCode是String区域code(依据中国行政区域编码划分规则）

9

DB36/T1845—2023

deviseName是String设备名称

deviceSn是String设备编号

imei是String设备imei号

productId是int产品id

operator是String操作人

返回示例见附录B.7。

A.3.7删除设备

删除设备数据的接口要求如下：

——接口方法：deleteDevice；

——接口路径：api/open/device/；

——请求方式：DELETE。

请求参数见表A.8。

表A.8deleteDevice

参数名必选类型说明

token是String通信证key

productId是int产品id

可以删除多个设备（最多支持200个设备）。多个设备id，中间以逗

deviceIds是String

号","隔开。

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

gridCode是String区域code（依据中国行政区域编码划分规则）

返回示例见附录B.8。

A.3.8更新设备

更新设备数据的接口要求如下：

——接口方法：updateDevice；

——接口路径：api/open/device/；

——请求方式：PUT。

请求参数见表A.9。

表A.9updateDevice

参数名必选类型说明

token是String通信证key

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

gridCode是String区域code（依据中国行政区域编码划分规则）

请求body（数据类型application/json;charset=utf-8）

10

DB36/T1845—2023

返回示例见附录B.9。

A.3.9获取物模型

查询属性列表信息，获取标准数据参数名称及数据类型的接口要求如下：

——接口方法：queryPropertyList；

——接口路径：api/open/model/properties/；

——请求方式：GET。

请求参数见表A.10。

表A.10queryPropertyList

参数名必选类型说明

token是String通行证key

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

productId是int产品Id

searchValue否String可填值：属性名称，属性

gridCode否String区域code（依据中国行政区域编码划分规则）

pageNow否int当前页数

pageSize否int每页记录数

返回示例见附录B.10。

A.3.10获取标准产品物模型

标准农村人居环境长效管护平台标准物模型的接口要求如下：

——接口方法：queryStandardModel；

11

DB36/T1845—2023

——接口路径：api/open/standardModel/；

——请求方式：GET。

请求参数见表A.11。

表A.11queryStandardModel

参数名必选类型说明

token是String通信证key

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

standardVersion否String标准物模型版本号

thirdType否int三级分类id

返回示例见附录B.11。

A.3.11获取服务列表信息

获取农村人居环境长效管护平台服务列表信息的接口要求如下：

——接口方法：queryPropertyList；

——接口路径：api/open/model/properties/；

——请求方式：GET。

请求参数见表A.12。

表A.12queryPropertyList

参数名必选类型说明

token是String通信证key

masterKey是StringmasterKey在该设备所属产品的概况中可以查看

productId是int产品Id

searchValue否String可填值：属性名称，属性标识符

gridCode是String区域code（依据中国行政区域编码划分规则）

pageNow否int当前页数

pageSize否int每页记录数

返回示例见附录B.12。

A.3.12智能垃圾桶数据上报

智能垃圾桶设备上报数据的接口要求如下：

——接口方法：uploadRubbishData；

——接口路径：api/open/uploadData/；

——请求方式：POST。

请求参数见表A.13。

表A.13uploadRubbishData

12

DB36/T1845—2023

参数名必选类型说明

token是String通信证key

body是String智能垃圾桶标准物模型

请求Body（数据类型application/json;charset=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,

"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.14uploadCardData

13

DB36/T1845—2023

参数名必选类型说明

token是String通信证key

body是String人员卡牌标准物模型

请求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-2118:13:06.133",

"createTime":"2021-07-2209:55:54",

"heading":null,

"valid":"0",

"imei":null

}

返回示例见附录B.14。

A.3.14智慧厕改设备数据上报

厕改设备上报数据的接口要求如下：

——接口方法：uploadToiletData；

——接口路径：api/open/uploadData/；

——请求方式：POST。

请求参数见表A.15。

表A.15uploadToiletData

参数名必选类型说明

token是String通信证key

body是String智慧厕改设备标准物模型

请求body

{

"deviceId":"15067733001",

"deviceName":null,

"uploadTime":"2021-08-2715:49:00",

"humWoman":null,

14

DB36/T1845—2023

"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":