DB65-T 4776.3-2024 社区管理基础数据采集系统 第3部分：接口协议要求

ICS35.020CCSL70DB65/T4776.3—2024社区管理基础数据采集系统第3部分：接口协议要求Basicdatacollectionsystemforcommunitymanagement—Part3:Interfaceprotocolrequirements新疆维吾尔自治区市场监督管理局发布IDB65/T4776.3—2024前言 12规范性引用文件 13术语和定义 14缩略语 15接口协议结构 16接口功能 27接口资源描述 38接口消息 59消息交互流程 810消息交互安全性 8附录A(规范性)接口消息对象特征属性 9附录B(规范性)接口消息对象和对象集合JSONSchema描述 DB65/T4776.3—2024本文件按照GB/T1.1—2020《标准化工作导则第1部分：标准化文件的结构和起草规则》的规定起草。本文件是DB65/T4776《社区管理基础数据采集系统》的第3部分。DB65/T4776已经发布了以下内——第1部分：数据元；——第2部分：数据采集规范；——第3部分：接口协议要求。本文件由新疆维吾尔自治区工业和信息化厅提出、归口并组织实施。本文件起草单位：中通服公众信息产业股份有限公司、桂林远望智能通信科技有限公司、新疆维吾尔自治区财政厅信息网络中心、中电信数智科技有限公司新疆分公司。本文件主要起草人：王秀英、蔡晓东、陈郁青、车继江、王权、马新成、魏晟坤、李英、王昱、凌肖、郭莎、王籽懿。本文件实施应用中的疑问，请咨询中通服公众信息产业股份有限公司。对文件的修改意见建议，请反馈至新疆维吾尔自治区工业和信息化厅(乌鲁木齐市友好南路179号)、中通服公众信息产业股份有限公司(乌鲁木齐市黄河路191号)、新疆维吾尔自治区市场监督管理局(乌鲁木齐市新华南路167号)邮编：830000中通服公众信息产业股份有限公司联系电话传真邮编：830000新疆维吾尔自治区市场监督管理局联系电话传真邮编：8300041DB65/T4776.3—2024本文件规定了社区管理基础数据采集系统的接口协议结构、接口功能、接口资源描述、接口消息、消息交互流程、消息交互安全性的要求。本文件适用于对社区管理基础数据的人工或外部系统的采集、交互、处理和存储。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本(包括所有的修改单)适用于本文件。GA/T1400.4—2017公安视频图像信息应用系统第4部分：接口协议要求DB65/T4776.1—2023社区管理基础数据采集系统第1部分：数据元IETFRFC2616超文本传输协议—HTTP/1.1(HypertextTransferProtocol—HTTP/1.1)3术语和定义DB65/T4776.1—2023、GA/T1400.4-2017界定的术语和定义适用于本文件。4缩略语下列缩略语适用于本文件HTTP:超文本传输协议(HyperTextTransferProtocol)JSONSchema:对象标记语言模式(JavaScriptObjectNotationSchema)R:读取(Read)REST:表述性状态传递(RepresentationalStateTransfer)TCP:传输控制协议(TransmissionControlProtocol)UDP:用户数据报协议(UserDatagramProtocol)URI:统一资源标识符(UniformResourceIdentifier)5接口协议结构5.1接口交互关系社区管理基础数据采集系统提供公共功能接口、数据查询接口、数据接收接口三类接口，为外部系统提供公共功能、数据查询、数据接收等服务，接口交互关系见图1。2DB65/T4776.3—2024公共功能接口请求公共功能接口请求公共功能处理结果数据查询接口请求外部系统"数据查询结果数据接收接口请求数据接收结果社区管理基础数据采集系统图1接口交互关系图5.2协议结构5.2.1应采用REST架构定义，接口消息对象数据传输时采用JSON格式序列化。接口协议结构见图2。分析接口图2接口协议结构图5.2.2所有接口交互信息定义为REST架构下的资源，使用URI唯一标识。5.2.3接口交互连接方式应支持HTTP长连接和短连接，实现机制应符合IETFRFC2616的规定。5.2.4外部系统的接口访问形式应符合GA/T1400.4-2017中A.3的规定。6接口功能6.1公共功能接口应符合GA/T1400.4—2017中5.1的规定。6.2数据查询接口3DB65/T4776.3—20246.2.1应支持外部系统从社区管理基础数据采集系统查询门禁设备列表、门禁设备关联的全部准入人员数据，以及一段时间内门禁设备关联准入人员的变更数据。6.2.2应支持外部系统从社区管理基础数据采集系统查询车辆抓拍设备列表、车辆抓拍设备关联的全部准入车辆信息，以及一段时间内车辆抓拍设备关联准入车辆的变更数据。6.2.3数据查询接口和第8章接口消息的对应关系见表1。表1数据查询接口与接口消息对照表123全部准入人员数据R消息4全部准入车辆数据R消息566.3数据接收接口6.3.1应支持从外部系统接收人员进出信息。6.3.2应支持从外部系统接收车辆进出信息。6.3.3数据接收接口和第8章接口消息的对应关系见表2。表2数据接收接口与接口消息对照表127接口资源描述7.1接口资源URI见表3。4DB65/T4776.3—2024表3接口资源URI序号资源URI说明1/DCS顶级资源2DCS/System/Register注册3DCS/System/UnRegister注销4DCS/System/Keepalive保活5/DCS/System/Time校时6/DCS/api/person/device/list查询门禁设备列表7DCS/api/vehicle/device/list查询车辆抓拍设备列表8/DCS/api/device/persons查询全部门禁设备关联的全部准入人员数据9DCS/api/device/vehicles查询全部车辆抓拍设备关联的全部准入车辆数据/DCS/api/device/persons/<DEVICE_NUMBER>根据门禁设备编号，查询门禁设备关联的准入人员变更数据/DCS/api/device/vehicles/<DEVICE_NUMBER>根据车辆抓拍设备编号，查询车辆抓拍设备关联的准入车辆变更数据/DCS/api/person/inout/record人员进出信息接收/DCS/api/vehicle/inout/record车辆进出信息接收7.2.1资源对象类型资源对象(以下简称“对象”)包括设备对象、人员对象、车辆对象、人员进出信息对象、车辆进出信息对象等接口消息对象。7.2.2对象描述方法对象应按以下方法进行描述：a)通过“对象名称”、“对象标签”、“对象集合标签”、“对象特征属性”、“JSONSchema描述”等属性进行描述；b)对象的特征属性应符合本文件附录A的要求；c)对象及对象集合的JSONSchema描述应符合本文件附录B的要求。7.2.3接口消息对象见表4。5DB65/T4776.3—2024表4接口消息对象序号对象名称对象标签对象集合标签对象特征属性JSONSchema描述1应答状态对象ResponseStatus一应符合A.3的规定应符合B.1的规定2设备对象DeviceInfoResponseDeviceList应符合A.4的规定应符合B.2的规定3人员对象PersonInfoResponsePersonList应符合A.5的规定应符合B.3的规定4车辆对象VehicleInfoResponseVehicleList应符合A.6的规定应符合B.4的规定5人员进出信息对象PersonInoutRecord一应符合A.7的规定应符合B.5的规定6车辆进出信息对象VehicleInoutRecord一应符合A.8的规定应符合B.6的规定8接口消息8.1接口消息描述8.1.1接口消息描述格式见表5。表5接口消息描述URI功能方法查询字符串消息体返回结果POSTGETPUTDELETE注释8.1.2表5各项说明如下：—URI项描述资源URI; —方法项列出资源涉及的HTTP方法，包括POST、GET、PUT及DELETE;—-查询字符串项描述资源的“键-值对”; 消息体项说明HTTP请求的消息体； 返回结果项描述HTTP请求的响应；——注释项给出接口消息的特殊说明；——接口消息Content-Type头部域应设为application/*+JSON。6DB65/T4776.3—20248.2公共功能接口消息8.2.1注册消息应符合GA/T1400.4—2017中7.3.1的规定。8.2.2注销消息应符合GA/T1400.4-2017中7.3.2的规定。8.2.3保活消息应符合GA/T1400.4-2017中7.3.3的规定。8.2.4校时消息8.3数据查询接口消息8.3.1门禁设备列表R消息见表6。表6门禁设备列表R消息URI/DCS/api/person/device/list功能查询门禁设备列表方法查询字符串消息体返回结果GET无无<ResponseDeviceList>注释ResponseDeviceList的定义应符合A.4的规定8.3.2车辆抓拍设备列表R消息见表7。表7车辆抓拍设备列表R消息URI/DCS/api/vehicle/device/list功能查询车辆抓拍设备列表方法查询字符串消息体返回结果GET无无<ResponseDeviceList>注释ResponseDeviceList的定义应符合A.4的规定8.3.3全部准入人员数据R消息见表8。7表8全部准入人员数据R消息查询字符串无无ResponsePersonList的定义应符合8.3.4全部准入车辆数据R消息表9全部准入车辆数据R消息查询字符串无无ResponseVehicleList的定义8.3.5准入人员变更数据R消息表10准入人员变更数据R消息/DCS/api/device/persons/<DEV查询字符串无无ResponsePersonList的定义应8.3.6准入车辆变更数据R消息表11准入车辆变更数据R消息URI/DCS/api/device/vehicles/<DEVICE_NUMBER>功能根据车辆抓拍设备编号，获取车辆抓拍设备关联的准入车辆变更数据方法查询字符串消息体返回结果GET无无<ResponseVehicleList>注释ResponseVehicleList的定义应符合A.6的规定8.4数据接收接口消息8DB65/T4776.3—20248.4.1人员进出信息C消息见表12。表12人员进出信息C消息URIDCS/api/person/inout/record功能存储人员进出信息方法查询字符串消息体返回结果POST无<PersonInoutRecord><ResponseStatus>注释ResponseStatus的定义应符合A.3的规定PersonlnoutRecord的定义应符合A.7的规定8.4.2车辆进出信息C消息见表13。表13车辆进出信息C消息DCS/api/vehicle/inout/record存储车辆进出信息查询字符串消息体返回结果无<VehicleInoutRecord><ResponseStatus>ResponseStatus的定义应符合A.3的规定VehicleInoutRecord的定义应符合A.8的规定9消息交互流程应符合GA/T1400.4-2017中第8章的规定。10消息交互安全性应符合GA/T1400.4-2017中第9章的规定。9DB65/T4776.3—2024(规范性)接口消息对象特征属性A.1基础数据类型特征属性见表A.1。表A.1基础数据类型表说明字符串一一一一一一A.2表中选项字符说明应符合以下要求：a)R=requirement表示必选字段；O=Option表示可选字段；R/O表示特定条件下必选，其他可选；b)字段长度应符合DB65/T4776.1—2023中5.4的规定；c)在多值情况时，类型栏只标识单值的类型，长度只标识单值的长度。A.3应答状态对象特征属性见表A.2。表A.2应答状态对象特征属性选说明1R2R为本次操作的响应说明3一RA.4设备对象及列表A.4.1设备列表对象DB65/T4776.3—2024特征属性见表A.3。表A.3设备列表对象特征属性序号名称标识符类型JSON长度必选/可选说明1状态码codestringc..3R0-正常1-参数格式错误2-参数内容无效3-系统忙9-其他未知错误2状态描述messagestringc..255R为本次操作的响应说明3列表内容resultList<DeviceInfo>一一DeviceInfo的定义应符合A.4.2的规定A.4.2设备对象特征属性见表A.4。表A.4设备对象特征属性说明1R定2R定3R定4号R定50定60定7R定8R定A.5人员对象及列表A.5.1人员列表对象特征属性见表A.5。DB65/T4776.3—2024表A.5人员列表对象特征属性说明1R2R为本次操作的响应说明3一一A.5.2人员对象特征属性见表A.6。表A.6人员对象特征属性说明1R2人员姓名R定30定4人员照片0定5R6集时间RA.6车辆对象及列表A.6.1车辆列表对象特征属性见表A.7。表A.7车辆列表对象特征属性序号名称标识符类型JSON长度必选/可选说明1状态码codestringc..3R0-正常1-参数格式错误2-参数内容无效3-系统忙9-其他未知错误2状态描述messagestringc..255R为本次操作的响应说明3列表内容resultList<VehicleInfo>一一VehicleInfo的定义应符合A.6.2的规定A.6.2车辆对象DB65/T4776.3—2024特征属性见表A.8。表A.8车辆对象特征属性说明1R2R3R4R506车辆车身0708090车辆信息采集时间R定A.7人员进出信息对象特征属性见表A.9。表A.9人员进出信息对象特征属性说明1人员进出R2R3进出人员姓名R4照片URI05开门时间R6RA.8车辆进出信息对象特征属性见表A.10。表A.10车辆进出信息对象特征属性序号名称标识符类型JSON长度必选/可选说明DB65/T4776.3—2024说明1号R定2号RDB65/T4776.1—2023中7.63码R定40定50定60定7全景图URI0定8抓拍图URIR定9抓拍图在全景图0定抓拍图在全景图0定00定抓拍时间R应符合DB65/T4776.1—202DB65/T4776.3—2024(规范性)接口消息对象和对象集合JSONSchema描述B.1应答状态对象//应答状态对象"code":"string","message":"string","result":"bool"}B.2设备对象//设备对象{"DEVICE_NUMBER":"string","DEVICE_NAME":"string","DEVICE_TYPE":"int","DEVICE_SN":"string","DEVICE_POSITION_LNG":"double","DEVICE_POSITION_LAT":"double","DEVICE_STATUS":"string","DEVICE_COLLECT_TIME":"dateTime"}//设备列表对象"code":"string","message":"string","result":[{{}}B.3人员对象{DB65/T4776.3—2024"PERSONNUMBER":"string","PERSON_NAME":"string","ID_NUMBER":"string","PERSON_PHONE_URI":"string","PERSON_TYPE":"int","PERSON_COLLECT_TIME":"dateTime"//人员列表对象"code":"string","message":"string","result":[{}]B.4车辆对象"VEHICLE_NUMBER":"string","PLATE_NUMBER":"string","PLATE_COLOR_CODE":"string","PLAT