DB3502T 049.1—2019 公共安全管理平台信息资源交换规范 第1部分：接口服务(厦门市).pdf

DB3502/T 福建省厦门市地方标准 DB3502/T 049.12019 公共安全管理平台信息资源交换规范 第 1 部分：接口服务 Specification of information resource exchange for public security management platformPart 1 : Interface services 2019 - 09 -10 发布 2019 - 10 - 01 实施 厦门市市场监督管理局 发 布 DB3502/T 049.12019 I 目 次 前言 . II 1 范围 . 1 2 规范性引用文件 . 1 3 术语和定义 . 1 4 缩略语 . 1 5 基本框架 . 2 6 接口定义 . 2 7 交换数据项值域 . 13 DB3502/T 049.12019 II 前 言 DB3502/T 0492019公共安全管理平台信息资源交换规范分为3个部分： 第 1 部分：接口服务； 第 2 部分：数据文件交换； 第 3 部分：业务协同对接。 本部分为DB3502/T 0492019的第1部分。 本部分按照GB/T 1.12009给出的规则起草。 本部分由厦门市城市公共安全管理领导小组办公室提出并归口。 本部分起草单位：厦门市城市公共安全管理领导小组办公室、厦门市信息中心、厦门市公安局、厦门市美亚柏科信息股份有限公司、厦门畅博思信息技术有限公司、厦门市标准化研究院。 本部分主要起草人：张若峰、柯国鸿、陈志飞、刘一鸣、龚浩杰、陈锦荣、连志阳、洪亚杰、林大滨、李童、陈成威、林立南、黄智强。 DB3502/T 049.12019 1 公共安全管理平台信息资源交换规范 第 1 部分：接口服务 1 范围 DB3502/T 0492019的本部分规定了公共安全管理平台信息汇聚和共享中数据交换及访问服务接口的基本框架和接口定义。 DB3502/T 0492019的本部分适用于采用接口方式、日均交换数据量10万条以下、响应实时性要求较高的公共安全管理信息数据报送、 备案和数据访问业务， 以及和公共安全管理平台与部门应用系统间的业务协同对接。部门应用系统向公共安全管理平台开放数据访问接口服务也可以参照本规范开发。 2 规范性引用文件 下列文件对于本文件的应用是必不可少的。 凡是注日期的引用文件， 仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 25647 电子政务术语 DB3502/Z 033.32016 政务信息共享协同平台技术规范 第3部分：平台接入规范 DB3502/T 048.12019 公共安全管理平台数据规范 第1部分：信息资源分类 DB3502/T 048.22019 公共安全管理平台数据规范 第2部分：数据元 3 术语和定义 GB/T 25647和DB3502/T 048.22019界定的以及下列术语和定义适用于本文件。 3.1 接口 interface 体现一个实体行为特征的具有名称的操作集。 3.2 请求 request 接口服务请求方向服务提供方发出一次调用。 3.3 响应 response 接口服务提供方返回给服务请求方的操作结果。 4 缩略语 下列缩略语适用于本文件。 GET：一种从指定的资源请求数据的HTTP方法 HTTP：超文本传输协议（Hyper Text Transfer Protocol） HTTPS：超文本传输安全协议（Hyper Text Transfer Protocol over Secure Socket Layer） DB3502/T 049.12019 2 JSON：基于JavaScript语言形式的数据对象表达方式（JavaScript Object Notation） POST：一种向指定的资源提交数据处理请求的HTTP方法 5 基本框架 5.1 接口服务许可、授权和使用 公共安全管理信息数据交换及访问服务接口许可、授权、使用的基本流程如下： a) 接口服务请求方向接口服务提供方提出使用接口服务申请，提交以下信息： 部门名称； 部门编码； 应用场景描述； 交换/访问服务的信息类别； 每天最大访问量； 使用期限，接口授权起止时间； 最多 8 个许可调用服务的请求方 IP 地址； b) 接口服务审批通过后，接口服务提供方生成访问许可信息，发放给接口服务请求方； c) 接口服务请求方在调用接口服务时，应提供有效的许可信息； d) 接口服务提供方接收到请求后应校验许可信息有效性和合法性，校验通过后，执行服务请求，向服务请求方返回服务响应内容。 注： 通过政务信息共享协同平台使用公共安全管理信息进行数据交换及访问服务， 应遵循 DB3502/Z 033.32016 第6 章的请求接入标准流程规定。 5.2 接口服务模型 公共安全管理信息数据访问服务接口遵循DB3502/Z 033.32016 第7章相关规范，以HTTP/HTTPS的方式提供， 服务请求方通过POST/GET方式进行数据请求， 服务提供方通过同步响应的方式返回响应数据。接口逻辑架构主要由接口请求参数、接口服务、接口响应数据三部分组成，接口逻辑架构见图1。 图1 接口逻辑架构图 6 接口定义 6.1 接口说明 公共安全管理信息数据访问服务接口地址， 应对服务发布路径和服务名称进行约定。 如示例1所示。 DB3502/T 049.12019 3 示例1： http:/XXX.XXX.XXX/SERVICE_PATH/SERVICE_NAME 其中： XXX.XXX.XXX：表示服务接口的服务器地址，其取值应为有效的服务器域名或 IP 地址； SERVICE_PATH：表示开放接口服务的发布路径，路径层次不做具体要求； SERVICE_NAME：表示开放接口服务的名称，由服务提供方命名。 6.2 基本约定 6.2.1 传输协议和消息封装格式 传输协议和消息封装格式为： a)采用HTTP/HTTPS作为传输协议； b)采用JSON作为消息的封装格式。 6.2.2 安全性 在公共安全管理信息数据交换及访问服务接口开发中，采用HTTP SERVICE进行数据传输，服务端进行用户和许可信息验证。 申请服务的用户应首先向服务提供方提出申请，经审批通过后，获取相应服务的访问许可证。 6.2.3 数据格式 服务接口请求参数和返回结果采用JSON标准格式， 请求参数由许可信息参数信息、 报送数据参数信息/数据访问服务条件参数信息组成，返回结果由结果描述信息和结果数据信息组成。 请求参数格式见图2。 许可信息参数信息 报送数据参数信息/数据访问服务条件参数信息 图2 请求参数格式 返回结果内容格式见图3。 结果描述信息 结果数据信息 图3 返回结果格式 数据格式的主要说明如下： a） 许可信息参数的内容符合 6.3 的规定； b） 报送数据参数的内容符合 6.4 的规定； c） 数据访问服务条件参数的内容符合 6.5 的规定； d） 报送结果的内容符合 6.6 的规定； e） 数据返回结果的内容符合 6.7 的规定。 6.3 许可信息参数 6.3.1 许可信息格式 许可信息参数由接口标识符、接口许可证、服务请求业务流水号、服务请求时间四部分组成。如图4所示。 DB3502/T 049.12019 4 接口标识符 接口许可证 服务请求业务流水号 服务请求时间 图4 许可信息参数格式 6.3.2 许可信息格式说明 许可信息标记及含义见表1。 表1 许可信息标记及含义 序号 标记 含义 说明 1 SERVICEID 接口标识符 必填项，由服务提供方提供的 4 位字符的接口标识符 2 TOKEN 接口许可证 必填项，由算法生成的二进制长度为 128 位的数字标识符 3 REQUESTID 服务请求业务流水号 必填项，采用 DB3502/T 048.32019 公共安全管理平台数据规范 第 3 部分： 信息代码 的 3.1 条“业务流水号编码规则” 4 REQUESTTIME 服务请求时间 必填项，格式：yyyy-MM-ddHH:mm:ss 许可信息在键值对 HEADERS 中，如示例 2 所示。 示例2： HEADERS: SERVICEID: X001, TOKEN: b59cb246111347858a7215ff4111729c, REQUESTID: 51100000MJ0000632D01_1_20181010120000_00001, REQUESTTIME: 2018-10-10 12:00:00 , 6.4 报送数据参数 6.4.1 报送数据参数信息格式 报送数据参数由许可信息、数据包描述信息（报送数据信息资源分类代码、报送数据单位编码、报送数据记录数）和报送数据集三部分组成，其中报送数据集部分由n条数据记录组成，每条数据记录由n个数据项组成。报送数据参数见图5。 DB3502/T 049.12019 5 图5 报送数据参数格式 6.4.2 报送数据参数信息格式说明 报送数据参数信息标记及含义见表2。 表2 报送数据参数信息标记及含义 序号 标记 含义 说明 1 DATATYPE 报送数据信息资源分类代码 必填项，符合 DB3502/T 048.12019公共安全管理平台数据规范 第 1 部分：信息资源分类 的规定 2 DEPTCODE 报送数据单位编码 必填项，采用 20 位编码，符合 DB3502/T 048.22019公共安全管理平台数据规范 第 2 部分：数据元规定的“010031”公共安全管理平台应用单位编码 3 RECORDCOUNT 报送数据记录数 最大记录数不超过 1000 条 4 DATA 报送数据集 必填项，由 n 条数据组成的数据内容集合(n 的取值范围为 1-1000)， 每条数据由由 ITEM1 到 ITEMn 数据项描述。 其中的数据项 ITEM1 到 ITEMn， 按 DB3502/T 048.42019公共安全管理平台数据规范 第 4 部分： 交换数据项 规定的数据标识符或约定的标识符填写 DB3502/T 049.12019 6 报送数据信息格式如示例 3 所示。 示例3： HEADERS: SERVICEID: B005, TOKEN: b59cb246111347858a7215ff4111729c REQUESTID: 51100000MJ0000632D01_1_20181010120000_00001, REQUESTTIME: 2018-10-10 12:00:00, , DATATYPE: X12345, DEPTCODE: 51100000MJ0000632D01, RECORDCOUNT: 1, DATA: CCCO: 4627, LAT: 24.61098, LBPL: 地址, LON: 118.23553, MOBI: 联系电话, ROWID: 51100000MJ0000632D01_1_20181010120000_00001_000001 6.5 数据访问请求参数 6.5.1 数据访问请求参数信息格式 数据访问请求参数信息部分由许可信息、业务调用方信息、描述信息（起始记录位置、返回记录条数）、排序信息、条件信息五部分组成，数据访问请求参数信息部分组成见图6。 DB3502/T 049.12019 7 图6 数据访问请求参数信息格式 A町PARAS1:1 业务凋阿亢倍主墅里壁n. 旦出量隽滴采血隽话时号旦旦旦旦噩隽滴求陪阴!Y!ITEM川一应同系统洛称剧SINESS川调陈业._J!o!MACADDRESS 砸醉阵是纠正绝执放到难度德摊主活重诲每件戴蜜顷但台关系匹矗值DB3502/T 049.12019 8 6.5.2 数据访问服务条件参数信息格式说明 业务调用方信息放置在AUDITPARAS的键值对中，其标记及含义见表3。 表3 业务调用方信息标记及含义 序号 标记 含义 说明 1 SYSTEMNAME 应用系统名称 调用方应用系统名称 2 BUSINESSNAME 请求业务事项 调用方办理业务名称 3 MACADDRESS 硬件地址 调用方 MAC 地址 4 IP IP 地址 调用方 IP 地址 5 LOC 地址经纬度 调用方如果是移动设备，则按照移动设备当前位置经纬度上报 数据访问请求参数信息中的描述信息标记及含义见表4。 表4 描述信息标记及含义 序号 标记 含义 说明 1 START 起始记录位置 必填项，返回结果数据起始记录位置 2 ROWS 返回记录条数 必填项，返回结果数据记录条数，不超过 1000 条 数据访问请求参数信息中的排序信息放置在ORDER的键值对中，排序信息包括排序数据项、排序方式两个元素组成，其标记及含义见表5。 表5 排序信息标记及含义 序号 标记 含义 说明 1 COLUMN 排序数据项标识 该元素为必填项 2 TYPE 排序方式 1：升序，-1：降序，默认为降序 数据访问请求参数中的条件信息包含的所有查询条件逻辑表达式放置在QUERYS的键值对中。 QUERYS值中的EXP键值对描述查询条件数据项间的逻辑关系，其中逻辑“与”用“*”号表示、逻辑“或”用“+”号表示，括号标识优先等级，条件数据项按照顺序用1、2、3n的连续数字表示。本键值对省略或取值为空时，默认条件关系为逻辑“与”。 QUERYS值中的QUERY键值对逐项描述查询条件数据项集合，条件项的数量不少于一项，最多不超过100个条件项， 每个条件项由数据项标识、 关系运算符和关系匹配值三个元素构成， 其标记及含义见表6。 表6 条件信息标记及含义 序号 标记 含义 说明 1 KEY 数据项标识 必填项，符合 DB3502/T 048.42019 公共安全管理平台数据规范 第 4 部分： 交换数据项 的规定 2 TYPE 关系运算符 必填项，关系运算符具体的值参考表 7 3 VALUE 关系匹配值 必填项，数据项关系匹配的具体数据值 数据访问请求参数的条件信息中的关系运算符标记及含义见表7。 DB3502/T 049.12019 9 表7 关系运算符标记及含义 序号 标记 含义 说明 1 eq 等于 按照对应数据项类型进行比较： 1) 字符型：按字符编码顺序进行比较 2) 数值型：转换成数值进行比较 3) 日期型：转换成日期进行比较 4） 日期时间型：转换成日期时间进行比较 2 gt 大于 3 gte 大于或等于 4 lt 小于 5 lte 小于或等于 6 ne 不等于 7 like 模糊匹配 1) 仅可应用于字符类型的数据项 2) 从字符串任意位置进行匹配 8 region 空间区域匹配 1) 仅可应用于空间位置类型的数据项 2) 关系匹配值为至少三个的空间位置点位集合，格式：经度,纬度,经度,纬度（如：118.07572,24.87644,118.04562,24.89767,118.12345,24.63234） 9 circle 圆型区域匹配 1) 仅可应用于空间位置类型的数据项 2) 关系匹配值为圆心空间位置及半径（单位：米）信 息 ， 格 式 ： 经 度 , 纬 度 , 半 径 （ 如 ：118.07572,24.87644,1000） 数据访问请求参数信息格式如示例4所示。 示例4： HEADERS: SERVICEID: B005, TOKEN: b59cb246111347858a7215ff4111729c REQUESTID: 51100000MJ0000632D01_1_20181010120000_00001, REQUESTTIME: 2018-10-10 12:00:00, , AUDITPARAS: BUSINESSNAME: 请求业务事项, IP: 192.168.2.1, LOC: 118.11177492,24.53695372, MACADDRESS: 9C-5C-8E-98-85-19, SYSTEMNAME: 应用系统名称 , ORDER: COLUMN: CPTM, TYPE: 1 , QUERYS: EXP: (1+2)*(3+4)*5*6, QUERY: DB3502/T 049.12019 10 KEY: DTCO, TYPE: eq, VALUE: 21D01 , KEY: DTCO, TYPE: eq, VALUE: 21D02 , KEY: LOC, TYPE: region, VALUE: 118.07572,24.87644,118.04562,24.89767,118.12345,24.63234 , KEY: LOC, TYPE: circle, VALUE: 118.07572,24.87644,1000 , KEY: CPTM, TYPE: gt, VALUE: 2016-11-21 02:41:51 , KEY: CPTM, TYPE: lt, VALUE: 2017-11-21 02:41:51 , ROWS: 3, START: 10 6.6 报送返回结果 6.6.1 报送返回结果信息格式 报送返回结果信息由数据描述和n条报送结果记录组成。报送失败或全部数据报送成功时只返回数据包描述；当报送数据部分发生异常时，返回每条异常数据的报送结果。报送返回结果信息组成见图7。 DB3502/T 049.12019 11 图7 报送返回结果数据包体格式 6.6.2 报送返回结果信息格式说明 报送返回结果信息标记及含义见表8。 表8 报送返回结果信息标记及含义 序号 标记 含义 说明 1 REQUESTID 报送数据的服务请求业务流水号 填写报送数据时的服务请求业务流水号，采用DB3502/T 048.32019 公共安全管理平台数据规范 第 3 部分： 信息代码 的 3.1 条“业务流水号编码规则” 2 MSG 状态消息 3 STATUS 状态编码 必填项，符合 DB3502/T 048.32019 公共安全管理平台数据规范 第 3 部分： 信息代码 的 3.18 条 “请求响应状态代码” 4 DATA 异常数据集合 如果部分数据报送失败， 则返回结果中包含报送失败的数据。 报送异常的数据集合放在DATA键值对中，包括：交换数据记录号编码RECORDCODE、异常原因描述ERRORMSG，其中RECORDCODE应符合DB3502/T 048.32019 公共安全管理平台数据规范 第3部分： 信息代码 的3.2条 “交换数据记录号编码规则” 。 报送返回结果信息格式如示例5所示。 示例5： REQUESTID: 51100000MJ0000632D01_1_20181010120000_00001, MSG: 失败, STATUS: 02, DATA: DB3502/T 049.12019 12 RECORDCODE: 51100000MJ0000632D01_1_20181010120000_00001_000001, ERRORMSG: 缺少关键项, , 6.7 数据访问结果 6.7.1 数据访问结果信息格式 数据访问结果信息由结果描述和查询结果集组成， 查询结果集由多个结果数据记录组成， 每个结果数据记录又由多个数据项组成。返回结果数据信息格式见图8。 图8 数据访问结果信息格式 6.7.2 数据访问结果信息格式说明 数据访问结果信息格式的标记及含义见表9。 DB3502/T 049.12019 13 表9 数据访问结果说明 序号 标记 含义 说明 1 REQUESTID 数据访问的服务请求业务流水号 填写数据访问发起的服务请求业务流水号，采用DB3502/T 048.32019公共安全管理平台数据规范 第 3 部分： 信息代码 的 3.1 条“业务流水号编码规则” 2 MSG 数据访问结果状态消息 3 STATUS 数据访问结果状态编码 必填项，符合 DB3502/T 048.32019 公共安全管理平台数据规范 第 3 部分： 信息代码 的 3.18 条 “请求响应状态代码” 4 TOTAL 查询结果集记录数 5 DATA 查询结果集 查询结果集包含由 n 条数据组成的数据内容集合(n 的取值范围为 1-1000)， 每条数据由 RECORDCODE 和 KEY1到 KEYn 数据项描述。 RECORDCODE 为交换数据记录号编码，符合 DB3502/T 048.32019 公共安全管理平台数据规范 第 3 部分： 信息代码 的 3.2 条“交换数据记录号编码规则” ； 数据项KEY1到KEYn， 按DB3502/T 048.42019 公共安全管理平台数据规范 第 4 部分： 交换数据项规定的数据标识符填写 查询结果集放置在DATA键值对中， 包含由n条数据组成的数据内容集合(n的取值范围为1-1000)。 每条数据由RECORDCODE和KEY1到KEYn数据项标识及数据值组成。 RECORDCODE为交换数据记录号编码， 应符合DB3502/T 048.32019公共安全管理平台数据规范 第3部分：信息代码 的3.2条“交换数据记录号编码规则”；数据项KEY1到KEYn，按DB3502/T 048.42019公共安全管理平台数据规范 第4部分： 交换数据项 规定的数据标识符和值域填写。 数据访问结果格式如示例6所示。 示例6： MSG: , REQUESTID: 51100000MJ0000632D01_1_20181010120000_00001, STATUS: 0, TOTAL: 1, DATA: KEY1: 2018-06-08 20:52:57, KEY2: 内容, KEY3: 02, KEY4: 主题, KEY5: 124.12578,24.56718, DB3502/T 049.12019 14 KEY6: 分类, RECORDCODE: 51100000MJ0000632D01_1_20181010120000_00001_00001 7 交换数据项值域 交换数据项取值符合DB3502/T 048.22019公共安全管理平台数据规范 第2部分：数据元中对应数据元的值域。其实际长度取决于其内容包含的字符在UTF-8字符编码中的表示长度。二进制类型的数据项，应通过Base64编码规则转换为字符串后放置在数据项标记之间。