DB31/T 1492-2024 智能物联 城市智联平台数据接口技术要求

ICS35.240

CCSL79

31

上海市地方标准

DB31/T1492—2024

智能物联城市智联平台数据接口技术要

求

IntelligentIoT—Technicalrequirementsofdatainterfaceforurbandigitalservice

platform

2024-07-05发布2024-11-01实施

上海市市场监督管理局发布

DB31/T1492—2024

目次

前言II

引言III

1范围1

2规范性引用文件1

3术语和定义1

4缩略语2

5智联平台接口基本要求2

接口分类2

接口约束3

6传输要求5

网络传输带宽5

网络传输质量5

网络可靠性要求5

业务接口平均时延5

7应用类接口要求5

应用类通用接口要求6

对接一网通办接口要求8

对接行业应用接口要求15

对接一网统管接口要求20

8对接云边端协同通用接口要求22

接口列表22

接口交互流程23

接口定义27

9应用场景云边端协同接口要求39

应用场景的交互流程39

应用场景通用数据定义40

应用场景业务数据定义40

附录A（规范性）数据字典41

附录B（规范性）行政编码规则44

附录C（资料性）应用场景示例45

参考文献48

I

DB31/T1492—2024

前言

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

起草。

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

本文件由上海市经济和信息化委员会提出并组织实施。

本文件由上海市信息标准化技术委员会归口。

本文件起草单位：上海市通信制造业行业协会、城域智联（上海）科技有限公司、上海商汤智能科

技有限公司、中铁武汉电气化局集团上海电气有限公司、上海宝信软件股份有限公司、力信测量（上海）

有限公司、上海市政工程设计研究总院（集团）有限公司、同济大学、阿里云计算有限公司、中铁十五

局集团有限公司、同济大学建筑设计研究院（集团）有限公司、上海市物联网行业协会、上海计算机行

业协会、上海有倕信息科技有限公司。

本文件主要起草人：顾伟华、李发致、叶建云、缪克华、黄海、刘毅、钟仲钢、黄祝、李春强、张

义保、周美华、徐平、孙逸瑾、张西利、张晓日、徐晓宇、周向红、冷冰、陈琪、任逸帆、吴晓明、金

立、徐慧敏、徐万鹏、杨一峰、赵怡、黄钰梅、叶晓华、潘君才、裘维东、施夏松、卢亦斌、杨伟新、

欧阳树生。

II

DB31/T1492—2024

引言

城市智联平台充分利用超大规模城市的海量数据资源，全流程采集来自商贸、交通、物流、医疗、

教育等行业的业务数据与行为数据，聚焦城市更新、老旧社区改造、社区环境改良以及居民生活条件改

善等热点、难点问题，以智能电梯、智能停车场（库）、智能社（园）区、智能道路公共设施等重点应

用场景为切入点，实现新一代城市智联平台的跨越式发展。城市智联平台数据接口技术要求用于解决应

用场景数据便捷接入城市智联平台，促进城市智联新业态的健康发展。

III

DB31/T1492—2024

智能物联城市智联平台数据接口技术要求

1范围

本文件规定了城市智联平台对外提供的智联平台接口基本要求、传输要求、应用类接口要求、对接

云边端协同通用接口要求、应用场景云边端协同接口要求。

本文件适用于接入城市智联平台的应用场景的数据接口设计与开发。

2规范性引用文件

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

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

文件。

GB/T2260中华人民共和国行政区划代码

GB7588电梯制造与安装安全规范

GB21240—2007液压电梯制造与安装安全规范

3术语和定义

GB7588和GB21240—2007界定的以及下列术语和定义适用于本文件。

城市智联平台urbanintelligentIoTdigitalserviceplatform

智联平台

以提升城市运行安全及运行效率为目的，基于物联网的传输途径，接收智能终端设备、智能网关的

信息，进行数据治理、挖掘等处理，为政府、企业、个人提供应用场景服务所建立的数字服务平台。

智能网关intelligentgateway

对智能终端设备进行控制、管理，汇聚、存储、传输交换智能终端设备的数据，进行面向场景的数

据分析、处理和应用，处于智联平台与智能终端设备之间的一种网关设备。

智能终端设备intelligentenddevice

通过标准协议与智能网关及智联平台通信的前端数据采集、识别、存储的设备。

事件event

智联平台运行中引发业务状态或软硬件设备健康状态变化的过程。

云边端协同cloud-edge-endcollaboration

云（智联平台）、边（智能网关）、端（智能终端）三者之间通过接口交互实现数据同步、设备管

理、业务应用的过程。

1

DB31/T1492—2024

业务影子businessshadow

用来保证云边端业务相关信息的及时性和最终一致性的一种面向业务应用的设备持久化配置。

4缩略语

下列缩略语适用于本文件。

AES：高级加密标准(AdvancedEncryptionStandard)

AK/SK：访问标识/访问密钥(AccessKeyId/SecretAccessKey)

CA：证书颁发机构(CertificationAuthority)

HAMC：哈希消息认证码(Hash-basedMessageAuthenticationCode)

HTTP：超文本传输协议(HypertextTransferProtocol)

HTTPS：超文本传输安全协议(HyperTextTransferProtocoloverSecureSocketLayer)

IAM：身份识别与访问管理(IdentityandAccessManagement)

IP：网际互联协议(InternetProtocol)

JSON：JavaScript对象标记(JavaScriptObjectNotation)

MD5：消息摘要算法(Message-DigestAlgorithm)

MQTT：消息队列遥测传输(MessageQueuingTelemetryTransport)

RESTful：表征状态转移(RepresentationalStateTransfer)

SHA：安全散列算法(SecureHashAlgorithm)

SN：序列号(SerialNumber)

TCP：传输控制协议(TransmissionControlProtocol)

TLS：传输层安全协议(TransportLayerSecurity)

URI：统一资源标识符(UniformResourceIdentifier，URI)

5智联平台接口基本要求

接口分类

5.1.1接口关系

智联平台接口由云边端协同接口与应用接口组成。接口关系见图1。

2

DB31/T1492—2024

图1接口关系图

5.1.2云边端协同接口

云边端协同接口包括设备注册、业务影子同步、库同步等通用接口以及各场景应用中的业务数据上

下行、文件上传下载等接口，规定了端与边之间、边与云之间的数据交互协议。

5.1.3应用接口

C端应用接口

C端应用接口包括与终端用户相关的应用场景业务接口，规定了智联平台与一网通办平台之间的数

据交互协议，或者智联平台与其他面向C端用户平台之间的数据交互协议。

B端应用接口

B端应用接口包括行业应用业务相关接口，规定了智联平台与行业应用平台之间的数据交互协议。

G端应用接口

G端应用接口包括应用场景的事件数据接口，规定了智联平台与一网统管平台之间的数据交互协议，

或者智联平台与其他政府管理治理平台之间的数据交互协议。

开发者接口

开发者接口包括面向应用、算法、数据的各类开发接口，定义了开发者调用智联平台开放能力的开

发工具集。

接口约束

5.2.1接口协议要求

3

DB31/T1492—2024

智联平台的云边端协同接口、应用接口在涉及接口协议、数据格式及安全性定义时均应遵守以下要

求。

a)网络层级关系符合表1的规定。

表1网络层级关系对应表

TCP/IP网络层次协议

应用层MQTT/HTTP/HTTPS

TCP/IP网络层次协议

传输层TCP

网络层IP

b)接口协议规定如下：

1)消息类接口：采用MQTT协议，用于云边端协同通信，接口格式符合MQTT协议规范；

2)RESTful接口：采用HTTP/HTTPS协议，接口设计符合RESTful风格，接口路径清晰明确，

支持长连接和短连接，实现机制符合IETFRFC2616中的相关规定。

5.2.2数据格式要求

智联平台的云边端协同接口、应用接口在涉及接口协议、数据格式及安全性定义时均应符合以下要

求：

a)序列化格式：采用JSON或ProtoBuf；

b)字段类型及缺省值约束：

1)string规则符合表2的规定；

表2string规则表

类型描述

字符串表示的数字类型，受JSON中Number类型的精度限制，若数字值过大（2^31以上），应

string(int64)

以字符串形式表示，如"1000000"

字符串表示的二进制数据类型，将二进制数据以Base64编码后，以字符串形式表示，如

string(byte)

"5Ya35Yaw"

2)字段缺省值符合表3的规定；

表3字段缺省值表

类型缺省值描述

string""空字符串

int32/int640数值0

float0.0数值0.0

boolfalse条件假

objectnull空对象

array[]空数组

3)字段定义要求：包括字段名称、数据类型、是否为可选参数、字段的注释性描述；

4

DB31/T1492—2024

4)字段命名规范：由多个部分组成，每个部分由小写英文单词、常用缩略语、数字构成，

各部分使用下划线进行连接；

5)数据字典值：明确取值范围。

c)字符集：符合IETFRFC3629中的规定。

5.2.3接口安全性要求

智联平台的云边端协同接口、应用接口在涉及接口协议、数据格式及安全性定义时均应符合以下要

求：

a)数据安全：

1)采集个人敏感数据：采用AES256或更高等级加密后传输；

2)使用个人敏感数据：加密或脱敏后使用，其中人像数据应加密或模糊化处理。

b)传输安全：MQTT/HTTP类接口采用TLS加密；

c)认证与鉴权：接口具备认证与鉴权机制，选用AK/SK、CA证书等方式。

6传输要求

网络传输带宽

联网系统传输带宽应符合以下要求：

a)联网系统网络带宽设计满足智能终端设备接入智能网关、智能网关接入智联平台、智联平台

为应用平台提供业务服务的带宽要求，并留有余量；

b)智能终端设备接入智能网关的支持千兆以太网接口，业务带宽不少于100MB/s；

c)智能网关接入智联平台支持千兆以太网接口，业务带宽不少于100MB/s；

d)智联平台为应用平台提供业务服务以千兆以太网接口或者万兆以太网接口接入网络。

网络传输质量

联网系统IP网络传输质量(如传输时延、包丢失率、包误差率等)应符合以下要求：

a)网络时延上限值为400ms；

b)时延抖动上限值为50ms；

c)丢包率上限值为1×10-3。

网络可靠性要求

年服务可用性（一年总分钟数扣除一年服务不可用分钟数后，与一年总分钟数的比值）不低于99.9%。

业务接口平均时延

应用场景的业务数据报送智联平台应符合如下要求：

a)消息类接口平均时延：边、端设备到智联平台的消息传输平均时延不大于2s；

b)RESTful接口平均时延如下所示：

1)应用平台与智联平台间非批量操作接口平均时延不大于3s；

2)应用平台与智联平台间批量操作接口平均时延不大于10s。

7应用类接口要求

5

DB31/T1492—2024

应用类通用接口要求

7.1.1认证与鉴权

认证与鉴权流程

认证与鉴权流程见图2。

权限认证

场景应用平台接入网关业务接口服务

（IAM）

发起API请求

身份认证

IAM鉴权

鉴权通过

访问数据服务

返回数据

图2认证与鉴权流程图

认证与鉴权流程包括：

a)认证：依据请求字段生成签名，网关对签名采用相同的HAMC算法进行验证，如果一致则放行，

否则返回401，认证失败；

b)鉴权：请求认证通过后，网关将请求转发到IAM模块进行权限鉴定，如果通过则转发到数字

服务平台对应的接口服务，否则返回401，授权失败；

c)授权：相关字段统一通过请求头传递，主要包括AK、签名等字段。

认证与鉴权算法

智联平台统一提供AK/SK，用于接口请求的认证和鉴权。请求头中应包括“date”和“authorization”

字段。请求签名由HAMC算法生成，请求签名的字段应包括当前时间、请求方法、请求URI、HTTP协议及

版本。

7.1.2接口列表

通用接口列表应符合表4的规定。

表4通用接口列表

分类接口编码用途

APP-COM01设置数据回调接口，用于接收准实时数据，如事件告警、设备状态更新等

通用接口

APP-COM02取消数据回调接口，用于取消数据回调接口的设置

7.1.3交互流程

6

DB31/T1492—2024

设置、取消数据回调接口交互流程见图3。

各应用平台智联平台

HTTPS：设置回调地址

回调设置结果

HTTPS：取消回调地址设置

取消结果

图3设置、取消数据回调接口交互流程图

7.1.4接口定义

设置实时数据回调接口定义

设置实时数据回调接口定义应符合表5的规定。

表5设置准实时数据回调接口表

编号APP-COM01

名称设置数据回调接口

协议HTTPS

方法POST

URI/v1/app/com/callback

序列化格式JSON

说明用于接收准实时数据，如事件告警、设备状态更新等，支持的类型应符合附录A.7。回调请求超时时间

为5s，超时后重试，重试5次后若仍超时则终止该接口调用。

消息体字段名称数据类型可空描述

请求request_idstringN请求标识，uuid

callback_urlstringN回调地址，支持HTTP/HTTPS

响应codeinteger(int32)N响应码

msgstringN响应消息

注：可空的取值为“N”表示此参数不可为空，为“Y”表示此参数可为空，余同。

取消准实时数据回调接口定义

取消准实时数据回调接口定义应符合表6的规定。

7

DB31/T1492—2024

表6取消准实时数据回调接口表

编号APP-COM02

名称取消数据回调接口

协议HTTPS

方法DELETE

URI/v1/app/com/callback

序列化格式JSON

说明取消数据回调接口的设置

消息体字段名称数据类型可空描述

请求request_idstringN请求标识，uuid

响应codeinteger(int32)N响应码

msgstringN响应消息

对接一网通办接口要求

7.2.1接口列表

对接一网通办接口应包含认证与鉴权、以及公告、社区、业主、项目和项目阶段等数据的上报，其

中认证与鉴权应符合7.1.1的规定，其他应符合表7的规定。

表7对接一网通办接口列表

分类接口编码用途

APP-YWTB01上报公告数据接口，用于上报公告数据

APP-YWTB02上报社区数据接口，用于上报社区数据

对接一网通办接口

APP-YWTB03上报业主数据接口，用于上报业主数据

APP-YWTB04上报项目数据接口，用于上报项目数据

对接一网通办接口APP-YWTB05更新项目阶段接口，用于更新项目阶段

7.2.2交互流程

对接一网通办接口交互流程见图4。

8

DB31/T1492—2024

一网通办平台智联平台

HTTPS：上报公告数据接口

上报结果

HTTPS：上报社区数据接口

上报结果

HTTPS：上报业主数据接口

上报结果

HTTPS：上报项目数据接口

上报结果

HTTPS：更新项目阶段数据接口

更新结果

图4对接一网通办接口交互流程图

7.2.3接口定义

上报公告数据接口

上报公告数据接口应符合表8的规定。

表8上报公告数据接口表

编号APP-YWTB01

名称上报公告数据

协议HTTPS

方法POST

URI/v1/app/ywtb/vote/announcements

序列化格式JSON

说明上报公告数据，每次不宜超过100条

消息体字段名称数据类型可空描述

请求request_idstringN请求标识，uuid

itemsarray(Announcement)N公告列表

Announcement

9

DB31/T1492—2024

表8（续）

消息体字段名称数据类型可空描述

请求codestringN公告编号

typeinteger(int32)N公告类型1:通知2:公示3:投票4:申请

titlestringN公告标题

announce_datestringN发布日期如:2020-12-1400:00:00

expiration_datestringN有效期,格式:yyyy-MM-dd,-1为永久有效

如:2020-12-14

vote_start_datestringY投票开始日期如:2020-12-14

00:00:00；type为3即投票类型的公告时,

该字段有值

vote_end_datestringY投票结束日期如:2020-12-14

00:00:00；type为3即投票类型的公告时，

该字段有值

area_codestringN行政区划编码，应符合附录B，如：

310101002001001016

areastringN行政区划格式地址，如：上海市/市辖区/

黄浦区/南京东路街道/云南中路居委会

/XX小区/16号楼

addressstringN地址，如：梅陇路555弄

totalinteger(int32)Y应参与户数；type为3即投票类型并且

status为3(已发布)时该字段有值

participantinteger(int32)Y实参与户数；type为3即投票类型并且

status为3(已发布)时该字段有值

vote_house_percentstringY投票的户数占应参与投票的户数的百分

点，四舍五入，保留两位小数；type为3

即投票类型并且status为3(已发布)时该

字段有值

vote_agree_house_perstringY投票赞同的户数占应参与投票的户数的

cent百分点，四舍五入，保留两位小数；type

为3即投票类型并且status为3(已发布)

时该字段有值

vote_area_percentstringY投票的房屋面积占应参与投票的总面积

的百分点，四舍五入，保留两位小数；type

为3即投票类型并且status为3(已发布)

时该字段有值

10

DB31/T1492—2024

表8（续）

消息体字段名称数据类型可空描述

请求vote_agree_area_percstringY投票赞成的房屋面积占应参与投票的总

ent面积的百分点,百分点，四舍五入，保留

两位小数；type为3即投票类型并且

status为3(已发布)时该字段有值

validstringY投票是否有效,投票的户数和房屋面积都

超过总数的2/3为有效；type为3即投票

类型并且status为3(已发布)时该字段有

值

passedbooleanY投票是否通过,投票赞同的户数和房屋面

积都超过总数的3/4为通过；type为3即

投票类型并且status为3(已发布)时该字

段有值

browsestringN浏览数

feedbackstringN反馈数

statusstringN公告状态1:待审核2:待发布3:已发布4:

驳回5:取消

optionsarray(Option)Y投票选项统计,统计详细信息；type为3即

投票类型并且status为3(已发布)时该字

段有值

Option

titlestringN选项名,投票设置的选项,如“赞成”,“反

对”,“申请”,“弃权”等

valuestringN选项的值,可以理解为该选项在数据库中

的标识

personsarray(Person)N选择该选项的用户列表

Person

idinteger(int32)N用户标识如:56

room_numberstringN户号,如:202

namestringN用户名称,如:张*国，脱敏

card_numberstringY人员身份证号码,前六位用*代替

如:******197201181637；未登记身份证

号时该字段值为空，脱敏

join_datestringN加入时间如:2021-02-0