DB3305_T 252-2022物联中台接入与数据转发技术规范.docx

ICS 03.080.99CCS A 01DB3305浙 江 省 湖 州 市 地 方 标 准DB3305/T 2522022物联中台接入与数据转发技术规范 2022 - 12 - 7 发布2022 - 12 - 9 实施湖州市市场监督管理局发 布Internet of Things Platform Access and Data Forwarding Technical Specification 目次前言II1 范围12 规范性引用文件13 术语和定义14 缩略语35 接入管理36 数据转发9附录 A（资料性）公开 API 使用示例13前言本标准旨在指导湖州市物联中台物联感知体系规划、建设及改造，夯实全域感知的基础。 本标准编写原则：遵循国家感知终端有关法律法规，保证本文档内容能适用于物联中台建设需求， 规范终端接入、数据转发以及安全等相关活动。 本文件由 湖州市大数据发展管理局提出并归口。 本文件起草单位：湖州市大数据发展管理局、湖州市数据服务中心、湖州市吴兴区大数据服务中心、湖州市南浔区大数据服务中心、德清县大数据发展管理局、长兴县大数据发展管理局、安吉县大数据发展管理局、湖州南太湖产业集聚区管理委员会、湖州经济技术开发区管理委员会、湖州市标准化研究院、中移物联网有限公司、中国移动通信集团浙江有限公司湖州分公司。 本文件主要起草人：蔡丰、笪猛霄、马红斌、陈玮萍、许彪、范俊、梅勇、张加林、姚朔舟、冯凌、张建勇、杨志杰、茅恒达、陆一鸣、秦琪波、吕一品、潘健、沈一雄、钱建国、卢浩、朱阳、敬威、朱云杰、郑京天、王硕。 物联中台接入与数据转发技术规范1 范围本文件规定了物联中台的接入和数据转发规范等内容。 本文件适用于指导感知终端硬件开发者、物联网应用开发者用户使用物联中台进行设备接入和数据转发工作。 2 规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 33745-2017 物联网 术语 GB/T 36951-2018 信息安全技术 物联网感知终端应用安全技术要求GB/T 38637.2-2020 物联网 感知控制设备接入 第2部分：数据管理要求 下列术语和定义适用于本文件。 3.1物联中台 Internet of Things Platform物联中台是一个集成了设备管理、消息订阅等能力的一体化软件系统。它向下实现各类感知终端统一接入和集中管理，向上面向第三方应用系统提供数据推送以及API接口服务，实现物联数据统一标准汇聚以及多方共享。 3.2感知数据 sensing data通过数据采集获取的原始数据或在此基础上进行加工处理的表征对象信息的数据统称。GB/T38637.2-2020，定义3.1 3.3感知终端 sensing terminal能对物或环境进行信息采集和/或执行操作，并能联网进行通信的装置。GB/T36951-2018，定义3.1.2 3.4物联网应用 IoT Service3 术语和定义物联网在具体场景中的使用实例，向用户提供物联网服务的集合。GB/T 33745-2017 物联网 术语 3.5产品 product产品是一组具有相同功能定义的设备集合。 3.6设备 device归属于某一个产品下，是真实设备在物联中台的映射，用于和真实设备通过连接报文建立连接关系， 是物联中台资源分配的最小单位。 3.7物模型 physical model物模型是对设备的数字化抽象描述，从属性、服务和事件三个维度分别描述该型号设备是什么，能做什么，能对外提供哪些服务。 3.8用于描述物模型的具体指标、参数类型，功能点包括标准功能点、自定义功能点功及系统功能点。例如冰箱，功能点中设备功能可以包括开关、速冻模式、速冷模式、温度设定、童锁、电量统计、故障告警等参数；系统功能可以包括信号强度、经纬度、版本等参数。 3.9协议适配 protocol adaptation是指实现对通信协议（如MQTT、LwM2M 、CoAP等）的连接、鉴权、路由、应答、解析、管理等功能的过程。 3.10心跳包 heartbeat packet平台与物联感知终端之间通过周期性发送信息，判断物联感知终端的健康状况，判断对方是否“存活”。 3.11边缘物联网平台 edge IoT platform是指在边缘侧提供应用、物联网设备管理、工业终端协议适配、云边协同、海量数据处理等功能的物联网平台。 3.12应用开发者 application developers功能点 function points指利用物联中台提供能力把已接入平台设备进行集中管理，并将设备数据转发至第三方平台以支撑上层物联网应用开发的人员。 3.13第三方平台 the third-party platform承载具体物联网应用并提供服务的第三方系统。 4 缩略语下列缩略语适用于本文件。 API：应用程序接口（Application Programming Interface） CoAP：受约束的应用协议（Constrained Application Protocol） HTTPS：超文本传输安全协议（Hyper Text Transfer Protocol over Secure Socket Layer） IETF：国际互联网工程任务组（The Internet Engineering Task Force） JSON： 对 象 简 谱 （JavaScript Object Notation） LwM2M：轻量级M2M协议 (Lightweight Machine-to-Machine) MQTT：消息队列遥测传输（Message Queue Telemetry Transport） OMA：开放移动联盟（Open Mobile Alliance） UDP：用户数据包协议（User Datagram Protocol） URI：统一资源标识符（Uniform Resource Identifier） 5 接入管理5.1 总体接入框架5.1.1 总体接入框架应包含感知层（与总体技术要求）、网络层、平台层、应用层等，四层架构如图1 所示。 REST：表述性状态传递（Representational State Transfer） SDK：软件开发工具包（Software Development Kit） 图 1 总体接入框架图5.1.2 感知层主要包括生态环境、农村农业、交通运输、市政、管廊等场景的感知终端。 5.1.3 网络层主要包括实现感知层到平台层数据传输的商用传输网络或专网。 5.1.5 应用层主要提供各种物联网应用服务。应用层宜基于平台层数据转发等服务设计、构建物联网应用。 5.2 通用接入要求5.2.1 网络要求设备直连、网关接入、第三方平台以及边缘物联网平台总计四种接入方式均应该和互联网打通。 5.2.2 物模型要求设备接入物联中台应在物联中台上对产品设置物模型，用于实现不同设备能够以统一的物模型标准对接应用平台，不同应用之间能够以统一物模型标准进行数据互通。 5.2.3 设备健壮性要求设备健壮性要求包括： 主动上报心跳包功能； 主动离线断开连接功能； 异常离线检测功能； 异常离线重连机制； 上报离线原因的功能； 命令回复机制； 上报固件版本信息功能； 上报设备型号功能； 上报网络信号强度功能（对于用无线方式接入的设备）。 5.1.4 平台层是物联中台，提供感知终端协议适配、设备管理、数据转发、运维监控等功能。 5.3 接入流程5.3.1 概述各类感知终端接入物联中台总体上应遵循以下流程，见图2： 图 2 接入流程5.3.2 创建产品设备接入的第一步是创建产品。产品为同种设备类型，产品下的设备拥有相同的物模型（功能）、数据格式。 5.3.3 设置物模型设置产品下设备的功能点，统一物模型后可以使设备与物联中台间的数据格式标准化，简化设备和应用的开发。 5.3.4 添加设备物理设备要连接到平台，应先在物联中台创建设备，并获取连接到物联中台的鉴权信息。 5.3.5 协议适配按照不同的接入方式应通过协议适配开发或配置打通感知终端和物联中台的数据通道。 5.3.5.1 设备直连5.3.5.1.1 概述设备应通过有线传输方式或无线传输方式（蜂窝网、wifi 等）直接连接到物联中台。 感知终端功能单一，分布分散，独立使用； 对时延要求不高的业务应用场景； 已建项目相关感知终端已采用直连方式接入业务平台的情况。 图 3 设备直连接入示意图5.3.5.1.2 协议要求在正常通信阶段，采用设备直连接入方式的感知终端应使用下列方式中的至少一种方式，完成感知终端与物联中台的数据交换： 基于长连接的MQTT实时通信； 基于无连接的CoAP实时通信； 基于无连接的LwM2M实时通信。 5.3.5.1.2.1 MQTT 协议接入5.3.5.1.2.1.1 物联中台应支持终端厂商（开发者）使用标准 MQTT 协议接入设备。 5.3.5.1.2.1.2 MQTT 协议通过交换预定义的 MQTT 控制报文来通信，MQTT 控制报文由固定报头、可变报头及有效载荷三部分组成。 5.3.5.1.2.2 CoAP 协议接入5.3.5.1.2.2.1 物联中台应支持终端厂商（开发者）使用标准 CoAP 协议接入设备。 5.3.5.1.2.2.2 CoAP 协议是 IETF 提出的一种面向网络的协议，采用了与 HTTPS 类似的特征，核心内容为资源抽象、REST 式交互以及可扩展的头选项等。 5.3.5.1.2.3 LwM2M 协议接入5.3.5.1.2.3.1 物联中台应支持终端厂商（开发者）使用标准 LwM2M 协议接入设备。 5.3.5.1.2.3.2 LwM2M 是 OMA 组织制定的轻量化的 M2M 协议。LwM2M 定义了三个逻辑实体: LwM2M Server 服务器； LwM2M Client 客户端，负责执行服务器的命令和上报执行结果； LwM2M 引导服务器 Bootstrap Server，负责配置LwM2M客户端。 5.3.5.1.2.3.3 在三个逻辑实体之间有 4 个逻辑接口： Device Discovery and Registration：客户端注册到服务器并通知服务器客户端所支持的能力； Bootstrap：Bootstrap Server配置Client； Device Management and Service Enablement：指令发送和接收； Information Reporting：上报其资源信息。 5.3.5.2 网关接入对于感知终端功能相对复杂，分布较集中，设备自组网的业务应用场景或已建项目相关感知终端已使用物联网感知层网关（智能网关、网络控制器等）接入业务平台的情况，要求相关物联网感知终端在本地接入物联网感知层网关，物联网感知层网关应通过有线传输方式或无线传输方式（无线蜂窝网、LoRa、 wifi 等）接入物联中台，见图4。 图 4 网关接入示意图5.3.5.3 平台接入5.3.5.3.1 对于已建项目中涉及感知终端的已建系统因设备、网关不适于二次改造或有特殊行业要求的物联终端（如应急安全场景等），应采用平台接入方式同步物联数据至物联中台。 5.3.5.3.2 基于物联中台企业融合模块，通过 HTTPS 的方式对第三方平台的数据进行抽取、分析，然后将处理后的数据上报给物联中台，最终实现设备数据的平滑接入，见图 5。 图 5 平台接入示意图5.3.5.3.3 采用平台接入的方式，对接的数据主要为设备的功能点消息。 5.3.5.3.4 第三方平台与协议适配服务通过 HTTPS 协议进行交互。交互的形式为两种： a）第三方平台提供API服务，企业融合模块通过定时器定期调用其API，获取设备数据； b）企业融合模块提供API服务，第三方平台定期将设备数据通过API的形式上报到协议适配服务。c）在实际操作中，只需选用任意一种对接方式即可。 5.3.5.3.5 企业融合模块从第三方平台获取的是原始的 JSON 消息，应转换为物联中台定义的物模型格式。 5.3.5.3.6 企业融合模块根据收到消息的种类，调用提供的不同 API，对消息进行处理。最终调用内部的 MQTT 客户端，将消息通过 MQTT 协议上传到物联中台。 5.3.5.3.7 在平台对平台方案中，企业融合模块与物联中台为单向通信。方向：第三方平台企业融合模块物联中台。 5.3.5.4 边缘物联网平台接入对于网络较为封闭，感知终端专业化程度高或安全要求等级较高，有其它需要在本地使用感知数据的业务应用平台的场景，或在本地有大流量、低时延、本地自治的应用场景，如视频监控、图像识别、即时应急处理等，要求部署边缘物联网平台，在本地进行感知终端接入，提供物联网相关能力服务，同时与物联中台对接进行通讯，见图6。 图 6 边缘物联网平台接入示意图5.3.6 设备调试应通过设备调试功能进行数据交互调试，查看设备实时日志，进行设备功能数据验证。 6 数据转发6.1 转发方式6.1.1 物联中台应支持应用开发者将感知终端数据通过平台数据推送、主动调取公开 API 等功能将数据转发给经过授权且对应的感知终端应用。 6.1.2 平台数据转发应提供以下两种方式： 1） 数据推送（HTTPS）。HTTPS推送用于实现物联中台与第三方平台之间的单向数据通信。物联中台作为客户端，通过HTTPS请求方式，将平台下设备数据推送给第三方平台应用服务器。 2） 主动调取（公开API）。物联中台提供公开API，用户通过对应密钥鉴权后，能调取功能丰富的API，能实现消息推送，消息分发等功能。 6.2 数据推送标准（HTTPS）6.2.1 概述数据推送服务（HTTPS）应包括实例创建、实例验证、规则配置、消息推送4个步骤。业务流程如图7所示: 图 7 数据推送服务使用流程6.2.2 实例创建每个实例对应一个HTTPS的推送配置实例。应用开发者需要在物联中台创建实例，需要配置参数包括：推送地址，Token，消息加密方式。 6.2.3 实例验证6.2.3.1 物联中台服务器应向配置的服务器地址发送 HTTPS GET 请求，进行地址有效性验证，请求形式示例如下： https:/url?msg=xxx&nonce=xxx&signature=xxx 6.2.3.2 第三方平台应用服务器收到请求后，应通过 signature 参数字段对请求进行校验。若确认此次 GET 请求来自物联中台，需在响应中原样返回 msg 参数，实例验证才能通过，否则验证失败，实例配置不生效。 6.2.4 规则配置应用开发者应在平台规则引擎模块自定义规则，对项目下设备数据进行筛选过滤，以实现数据转发至物联中台通信组件。 6.2.5 消息推送6.2.5.1 物联中台应支持设备生命周期、设备物模型等数据推送。当需推送数据通过平台合法性校验入库以后基于数据推送服务以 JSON 形式置于 HTTPS 请求中的 body 部分并推送给第三方平台应用服务器。 图 8 推送数据流转流程6.2.5.2 配置推送实例时，如果选择消息推送方式为安全模式，则平台应对消息 msg 进行加密处理， 应用服务器收到数据时，需通过生成密钥进行解密操作。 6.3 公开 API 接口标准6.3.1 API 调用说明物联中台应提供项目、设备、服务等云端API，配合API接口文档帮助应用开发者快速开发应用，满足场景业务需求。 6.3.2 公共请求说明API接口请求参数应包括公共参数和自定义业务参数两部分。公共请求参数是调用每个API时都需要携带的请求参数, 包括服务命名空间、接口名称、版本信息。自定义业务参数由各接口定义，根据调用方法不同，需要将参数携带至请求路径或者请求体中。API接口公共参数调用如下所示: https:/xxxxxx/namespace?action=xxxx&version=1 6.3.3 API 鉴权物联中台应对API调用方进行资源权限校验，使用API时，需要在请求Header中携带统一的安全鉴权信息。 6.3.4 安全鉴权机制6.3.4.1 安全鉴权 authorization 由多个参数构成，每个参数均应采用 key = value 的形式表示，并用& 作 为 分 隔 符 ： authorization: version=2020-05-29&res=userid%2F38055&et=1623982416&method=sha1&sign=S04GcvafYIjtAMHJthkG PevbNwE%3D 6.3.4.2 sign 的生成算法为: sign = base64(hmac_(base64decode(AccessKey), utf-8(StringForSignature) 6.3.4.3 AccessKey 为物联中台分配的访问密钥（用户访问权限页面查看），如果访问资源以主用户形式访问, 使用主用户的 AccessKey，如果访问资源以项目群组方式访问，使用群组的 AccessKey，且只能对群组内设备进行操作。 6.3.4.4 AccessKey 参与计算前应先进行 base64decode 操作。 6.3.4.5 用于计算签名的字符串 StringForSignature 按照 et、method、resource、version 的顺序， 以n作为分隔符进行排列，如下所示： StringForSignature = et + n + method + n + res + n + version 附 录 A（资料性） 公开 API 使用示例A.1 请求示例请求示例如下： GET /common?action=QueryDeviceDetail&version=1&product_id=lsibd9&device_name=no001 A.2 响应示例A.2.1 响应参数说明请求响应参数说明见表A.1。 表 A.1 响应参数说明序号 参数 类型 描述 1requestIdstring请求 ID，调用API 时由平台生成唯一请求标识2codestring调用失败时，返回的错误码3msgstring调用失败时，返回的错误信息4successboolean接口是否调用成功5 data object 调用成功时，返回的业务数据（接口无业务数据返回，值为 null） A.2.2 成功响应成功响应示例如下： requestId: 8906582E6722409AA6C40E7863B733A5, success: true, data: status: 1 A.2.3 失败响应失败响应示例： requestId: 8906582E6722409AA6C40E7863B733A5, code: iot.application.deviceNotFound, msg: device does not exist, success: false