（正式版）DB23∕T 2637-2020 《位置服务平台多模式协同定位服务接口技术规范》

ICS07.040A75DB230LocationServicePlatformMulti-ModeCooperativePositServiceInterfacetechni2020–06–08发布黑龙江省测绘地理信息局联合发布IDB23/T2637—2020前言 I 12规范性引用文件 13术语和定义 14总则 25符号、缩略语和UML标记 36基本服务元素 47定位服务操作 68指令服务操作 69扩展服务操作 6附录A(规范性附录)服务接口部分返回字段说明 错误！未定义书签。附录B(资料性附录)服务接口返回数据结构 参考文献 23DB23/T2637—2020I本标准按照GB/T1.1-2009编写的规则起草。本标准由黑龙江省测绘地理信息局提出。本标准由黑龙江省测绘地理信息局标准化技术委员会归口。本标准起草单位：自然资源部黑龙江基础地理信息中心。本标准主要起草人：周振发、林富明、张庆全、刘禹鑫、周源、王洪昌、刘恒飞、李冰、古一鸣、王芳、李梅、朱晓东。DB23/T2637—20201位置服务平台多模式协同定位服务接口技术规范本标准规定了位置服务平台多模式协同定位服务接口的适用范围、一致性要求、规范性引用文件、术语和定义、符号、缩略语和UML标记、建设原则、基本服务要素和定位指令服务操作。本标准适用于行业领域位置服务多模式协同定位的管理、研究、开发及应用。2规范性引用文件下列文件对本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本使用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单元）适用于本文件。GB/T16831-2013基于坐标的地理点位置标准表示法GB/T30288-2013卫星导航定位坐标系统GB/T7408-2005数据元和交换格式信息交换日期和时间表示法JT/T808-2019道路运输车辆卫星定位系统终端通讯协议及数据格式JT/T794-2019道路运输车辆卫星定位系统车载终端技术要求JT/T796-2011道路运输车辆卫星定位系统平台技术要求W3CXML可扩展标记语言1.0（第五版），W3C推荐（2008）3术语和定义下列术语和定义适用于本文件。3.1位置服务根据特定需求，采用卫星定位技术获取的用户终端的位置信息，通过移动通信网络，在电子地图服务的可视化支持下提供给用户本人或他人以及通信系统，实现定位、导航、查询、识别和事件检查等与空间位置相关的增值服务。3.2定位模式采用一定的定位设备和定位技术组合进行定位的方式。3.3协同定位采用不同定位模式实现室内外空间的定位服务。注：多种定位技术与方法相互协调完成的定位服务。DB23/T2637—20203.4定位区域能提供稳定的定位服务与流畅的信息交互的空间区域。3.5接口用户应用位置服务多模式协同定位服务接口的开发人员。3.6定位终端定位终端是位置服务平台的定位数据来源设备，包括GPS/北斗车载终端、手持定位终端，具备定位功能的手机、无线对讲机等。注：本处车载终端一般要求符合交通部JT/T794-2019，终端与平台间的数据格式符合JT/T808-2019道路运输车辆卫星定位系统终端通讯协议及数据格式(兼容JT/T808-2013）[JT/T796-20113.5车载终端]3.7网络通讯协议连接不同操作系统和不同硬件体系结构的互联网络提供通信支持，是一种网络通用语言。4总则4.1一致性任何声称与本标准相一致的定位服务的实现或产品都应满足本标准规定的接口服务操作和相应数据结构的全部要求。4.2实用性接口功能跨平台使用，具备实用、简洁的特点。4.3扩展性平台具备对架构、容量、通信和处理能力等方面进行接口扩充和升级的特点。4.4开放性与相关技术标准相统一，传输协议具备通用性与一致性的要求。4.5先进性接口具备功能、采用技术、实现方法、可延续性等方面技术的先进性。DB23/T2637—20205符号、缩略语和UML标记5.1缩略语下列缩略语适用于本文件。OGC开放地理空间信息联盟（OpenGeospatialConsortium）CGCS20002000国家大地坐标系（ChinaGeodeticCoordinateSystem2000）CRS坐标参照系（CoordinateReferenceSystem)GNSS全球导航卫星系统（GlobalNavigationSatelliteSystem）GSM全球移动通信系统（GlobalSystemforMobileCommunications）XML可扩展标记语言（ExtensibleMarkupLanguage）[W3CXML可扩展标记语言1.0]5.2UML标记在本标准中，采用统一建模语言（UML）描述室内外多模式协同定位的概念模型和服务接口。基本的数据类型和图表在ISO/TS19103:2005中以及ISO/IEC19501中说明。在本标准中，采用下列UML类的构造型：a)<<DataType>>(<<数据类型>>)一组没有标识（独立存在且可能存在边缘效应）值的描述符。数据类型包括基本的预定类型。DataType是一个具有少量操作或没有操作的类，其主要目的是保持其他类的抽象状态。b)<<CodeList>>(<<代码表>>)一个灵活的枚举，用于描述一个开放列表。如果完全知道该表的元素的值，则应使用枚举；如果只知道该表元素的可能值，则应使用代码表。c)<<Abstract>>(<<抽象类>>)不能直接实例化的类（或其他类元）。该类的UML标记用斜体表示其名称。d)<<Interface>>(<<接口>>)命名的操作集，描述元素的行为。e)<<Package>>(<<包>>)逻辑上相关组分的群集，包括子包。f)<<Type>>(<<类型>>)一组抽象的属性和关联。抽象意味着其规范不一定应作为实例变量体实现。在本标准中，UML标记的主要元素如图1所示。4组件类#1父类本条规定了服务接口中独立于特定服务必选操作的通用部分，操作流程如下图2所示。用户验证服务响应用户验证注销服务服务接口调用注销服务设备验证服务异常图2操作流程图6.2用户验证先校验用户名，获取加密参数，将密码执行rsa加密后，再进行登录验证参数名是用户名，例如：testuserl是RSA加密后的密码密文，很长一串字符串。是固定为trueDB23/T2637—202056.3设备验证通过提供专用接口执行设备传回数据接收入口校验，用来验证隶属于该平台的设备，校验成功后放行否则为无效数据。如图表1。表2设备验证详细参数表是是6.4位置坐标位置坐标数据是多模式协同定位服务接口提供的核心服务内容，各种终端结构数据最后基于该标准坐标数据结构（终端实时位置数据基于该标准数据结构，用户能根据不同的应用场景开发各种位置服务延伸应用，如图表2。表3定位数据结构度度米度YYYYMMDDThhmmss坐标数据中的lat、lon和alt应符合《基于坐标的地理点位置标准表示法》（GB/T16831-2013）对地理点位置的规定。其中，高程单位为米，速度单位是米每秒，方位角是以真北方向TN为参考基准，范围在0-360。定位时间以采用UTC作为参照基准，其格式表示为符合GB/T7408-2005《数据元和交换格式信息交换日期和时间表示法》的字符串，为YYYYMMDDThhmmss。6.5服务注销当结束服务调用时，执行服务注销操作。6.6服务响应当服务调用时，通用返回结果为JSON数据格式，具体格式见附录A，详细记录了服务调用返回状态与执行结果。6.7服务异常当接收到不符合本标准的无效请求时，或定位服务计算出现问题时，定位服务器应发布服务异常报DB23/T2637—20206告，用于向客户应用程序和使用者声明请求无效的原因。6.8消息通道主要包括后台下行命令请求消息队列接口和信息网关上行信息推送消息队列接口两部分，作为命令执行获取消息反馈的通道。7定位服务操作7.1概述本标准规定位置服务平台采用以下服务操作实现获取基本位置与定位相关服务，并在名称与含义上保持一致，接口统一访问http://<主机>:<端口>/webAppInterface/命令名称。终端管理（myDevices）操作：获取用户所管辖内所有终端基本信息。终端参数（params）操作：获取特定终端参数列表。终端定位服务（realTimeInfo）操作：实时请求终端最新位置。历史回放（historyBLInfo）操作：用于查询某时段的终端轨迹点集合的历史位置信息。表4定位服务操作realTimeInfoparamshsitoryBLPointHandl7.2终端管理7.2.1描述终端管理类（myDevices）操作用于查询及变更终端基本信息相关参数。7.2.2请求终端管理类（myDevices）的请求参数如表5所示。表5请求URL的参数否7终端管理类(myDevices)操作的请求有效时，服务器应根据请求的参数返回一个响应，根据请求类型返回终端详细信息，请求响应的服务接口如图3所示，其JSON数据结构的示例见附录B.2。<<接口>><<接口>>图3myDevices接口7.3终端参数终端参数类(params)操作的目的是查询及变更用户管理的车载、手持、北斗等定位终端或者权限等信息，返回用户对应终端及权限。终端参数类(params)的请求参数如表6所示。7.3.3响应终端参数类(params)操作的请求有效时，服务器应根据请求的参数返回一个响应，根据请求类型返回终端详细信息，请求响应的服务接口如图4所示，其JSON数据结构的示例见附录B.2。<<接口>>87.4终端定位终端定位类(realTimelnfo)操作实现实时请求终端最新位置，获取多种终端设备明码经纬度地理坐标位置信息、时间、速度、方向等实时信息。终端定位类(realTimeInfo)操作的请求参数如表7所示。表7realTimelnfo请求URL的参数终端标识指定终端的识别码，多个时以英文逗号隔开。形如15812345678,不的终端实时数据。7.4.3响应终端定位类(realTimeInfo)操作的请求有效时，服务器应根据请求的参数返回一个响应，否则就返回一个服务异常。请求响应的服务接口如图5所示，逻辑结构如图6,返回该用户所属所有终端的实时位置信息。其JSON数据结构的示例见附录B.3。<<接口>>9用户参数实时位置集实时位置集实时位置集实时位置集图6逻辑结构7.5历史回放历史回放(historyBLInfo)的请求参数如表8所示。开始时间查询起始时间结束时间不填则默认以当前时间为结束时间7.5.3响应历史回放(historyBLInfo)操作的请求有效时，服务器应根据请求的参数返回一个响应，返回请求查询时间内终端所有的运动轨迹点集合。请求响应的服务接口如图7所示，逻辑结构如图8,返回该用户所属所有终端的实时位置信息。其JSON数据结构的示例见附录B.4。<<接口>><<接口>>终端位置坐标等信息位置坐标等位置坐标等信息…...…...8指令服务操作本标准规定位置服务平台采用以下服务操作实现与终端交互相应指令(指令符合国家部标标准协报警命令(超速报警setOverSpeed,区域报警setAreaCircular,报警操作用于超速和区域等报警命拍照命令(takePhoto)操作用于对表9指令服务操作见8.2见8.3DB23/T2637—20208.2报警命令8.2.1描述报警命令中超速报警setOverSpeed，区域报警setAreaCircular，涵盖设置区域报警(圆形、矩形和多边形)，查询区域报警，删除区域报警等，此处以超速报警和圆形区域报警为例。8.2.2请求报警命令的请求参数如表10、11、12所示。表10setOverSpeed请求URL的参数表11setAreaCircular请求URL的参数usetime是否根据时超速持续多长时间认定警警0否，1:是，默认1圆心纬度圆心经度是表12deleteAreaCircular请求URL的区域ID则删除所有区域。不超过125个，多于125个建议用多条消息报警命令操作的请求有效时，服务器应根据请求的参数返回请求成功响应，终端将记录超速、区域报警约束，报警信息随终端定位基本信息返回。请求响应的服务接口如图9所示，其JSON数据结构的示例见附录B.5。<<接口>>8.3定时监控指令定时监控指令(setLocationTimeSpan)操作用于设置终端上报位置时间间隔。定时监控指令(setLocationTimeSpan)的请求参数如表13所示。是是时间间隔定时监控指令(setLocationTimeSpan)操作的请求有效时，服务器应根据请求的参数返回请求成功响应。请求响应的服务接口如图10所示。<<接口>>图10定时监控指令服务接口8.4拍照命令终端拍照命令(takePhoto)用于对车载设备下发摄像头工作命令，车载设备接收命令后自动拍照上终端拍照命令(takePhoto)的请求参数如表14所示。照片质量1:低质量；2:中质量；3:高质量；终端拍照命令(takePhoto)操作请求有效时，服务器应根据请求的参数返回请求成功响应，请求响应的服务接口如图11所示。<<接口>>图11拍照命令下发上传服务接口指令服务反馈信息采用activeMQ作为消息中间件来推送实时信息，使用方式为用户登录系统后访问http://<主机>:<端口>/webPu待实时数据推送过来，同时，需要设置定时程序维持activeMQ主题。http://***。***.***.**用户名Mq推送主题的用户名8.5.3响应表16指令服务反馈操作结果DB23/T2637—2020命令执行状态：error-失败,susuccess成功时，关联的数据信息，里程时为单字符，参数查询时指令流水号：仅808协议才有，当流水号为0时，此指令一定不是8.6指令反馈维持8.6.1描述指令服务反馈信息采用activeMQ作为消息中间件来推送实时信息，为保证等待实时数据推送获取，>/webPush/keepTopicHeart接口，访问间隔时间不超过20分钟，此消息为维持通道不被自动清理。8.6.2请求表17指令反馈维持请求URL的参数空8.6.3响应指令反馈维持操作请求有效时，服务器应根据请求的参数返回请求成功响应，响应返回结果JSON数据结构示例见附录B.7。9扩展服务操作平台可根据用户需求，扩展该标准服务接口，包括平台功能接口、综合统计接口和其他终端扩展协议接口。DB23/T2637—2020（规范性附录）服务接口部分返回字段说明A.1服务接口部分返回字段说明见表A.1。表A.1规定了所有服务接口返回数据的属性结构，返回数据限于包含表中所有属性项，并具备不同字段类型。表A.1服务接口响应返回数据属性结构DB23/T2637—2020（资料性附录）定位服务接口返回数据结构B.1—B.5规定了定位服务接口和指令服务反馈返回数据JSON格式结构，根据返回数据进行解析处理表达。B.1终端管理类（myDevices）操作返回数据结构如下。{"name":"位置服务运营",//部门名称"uuid":"8a40c0353fa828a6013fa898d4ac0026",//部门唯一ID"devices":[//这个部门下的设备列表{"DeviceID":"***********",//设备识别号"infogateName":"**分中心",//设备所属信息网关名"protocolType":jtt808,//设备所使用的协议类型"iscors":0,//是否高精度定位"devType":"lbs_dev_vehicle",//设备类型"ext":{//设备的扩展属性"simcardid":,"platenumber":"*BKK123","brand":null,"color":null,"cartype":"jiaoche","carbase":"gongche"}}"childs":[//子部门{"name":"**测绘院","uuid":"1a7b8e2037774e04ac8877c3fbd34ec1","devices":[{DB23/T2637—2020"DeviceID":"***********","infogateName":"**分中心","protocolType":null,"iscors":null,"devType":"lbs_dev_mobile","ext":{"telnumber":,"brand":null,"name":"zhang"}}]}]}B.2终端参数（params）操作返回数据结构如下{"DataType":"Params",//描述此消息的数据类型，此处固定"deviceId":"************",//终端唯一ID"detectionTime":"2018-11-2710:06:30",//终端事件侦测触发时间"receiveTime":"2018-11-2710:06:29"，//数据接收时间"peakList":[{//终端参数列表"peakId":1,//id"peakValue":"30",//参数值"peakDesc":"终端心跳发送间隔"//参数说明}DB23/T2637—2020B.3终端定位（realTimeInfo）操作返回数据结构如下[{"uuid":"361b2079ad7649e78dd7c36dbb1574d2",//本条数据的标识码"deviceid":"***********",//终端识别码"lon":115.926277,//经度"lat":22.981482,//纬度"heading":181,//航向"speed":15.400001,//速度"time":"2018-12-2110:13:04",//定位时间"altitude":476,//高程"miles":62,//里程"warnmsgs":"超速报警,GNSS模块发生故障",//报警信息"status":"ACC关,未定位",//状态信息"onlinestate":"在线"//在线状态}]B.4历史回放（historyBLInfo）操作返回数据结构如下[{"uuid":"fc01375445fd11e9a5464ccc6aa7f1b8","deviceid":"***********",//设备识别号"lon":126.620685,//经度"lat":45.70345,//纬度"heading":117,//航向"speed":0,//速度"time":"2013-07-1611:17:26",//时间"altitude":0,//高程"miles":1086.8,//里程"status":"0"//状态}]DB23/T2637—2020B.5历史报警（historyWarn）操作返回数据结构如下[{"uuid":"53063d6bc93a40acbf3dae8dfbeada0c","gpsinfouuid":"c17fa2bbf9f3428cb3d1023760da9256","deviceid":"************","time":"2018-12-0209:16:27","warnmsgs":"进出区域,需要人工确认报警事件的ID,进出区域/路线报警","lon":126.621563,"lat":45.705135}]DB23/T2637—2020（资料性附录）指令服务接口返回数据结构C.1—C.2规定了部分指令服务反馈返回数据JSON格式结构，根据返回数据进行解析处理表达。C.1指令服务反馈操作返回数据结构如下所有指令服务执行反馈JSON示例如下：{"DataType":"ExecutionStatus",//描述此消息的数据类型"DeviceId":"015046686410",//终端唯一ID"Status":"success",//命令执行状态：error-失败,success-成功"Data":null,//success成功时，关联的数据信息"Description":null,//error失败时，描述具体失败原因或者关联信息。"CmdTypeDescription":"拍照（摄像头立即拍摄）",//下行命令类型描述"packId":9,//指令流水号"CmdType":"TAKE_PHOTO",//下行命令类型"DetectionTime":"2019-06-0615:18:21"//终端事件侦测触发时间}查询参数指令服务