电梯应急救援平台数据接口规范

ICS 点击此处添加ICS号 点击此处添加中国标准文献分类号 DB34 安徽省地方标准 DB 34/ XXXXX—XXXX 电梯应急救援平台数据接口规范 Data Interface Specification for Elevator Emergency Rescue Plat 点击此处添加与国际标准一致性程度的标识 XXXX - XX - XX发布 XXXX - XX - XX实施 安徽省市场监督管理局 发布 DB/ XXXXX—XXXX 前 言 本标准依据GB/T 1.1-2020给出的规则起草。 本标准由安徽省特种设备检测院提出。 本标准由安徽省市场监督管理局归口。 本标准起草单位：安徽省特种设备检测院、科大国创云网科技有限公司。 本标准主要起草人：莫诚生、赵龙、许迪、许佳伟、徐建国、苏文涛。 电梯应急救援平台数据接口规范 1 范围 本标准规定了电梯应急救援平台的数据交换架构、数据交换环境、数据交换模式、接口总则、接口响应状态编码、接口协议约定及协议清单、接口协议的内容。 本标准适用于电梯应急救援平台的建设单位、研发单位的系统开发、平台对接、接口测试、系统验收工作。 2 规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅所注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 GB/T 7408数据元和交换格式 信息交换 日期和时间表示法 TSG 08—2017 特种设备使用管理规则 T/CPASE M001-2019 电梯应急处置平台技术规范 3 术语和定义 下列术语和定义适用于本文件。（关于网格、电梯唯一标识、电梯使用单位等名词的定义） 3.1 电梯 lifts，escalators and moving walks 动力驱动，利用沿刚性导轨运行的箱体或者沿固定线路运行的梯级（踏步），进行升降或者平行运送人、货物的机电设备，包括载人（货）电梯、自动扶梯、自动人行道等。 3.2 使用单位 the elevator unit 对电梯使用履行安全管理义务、承担安全首负责任的单位或者个人。 4 数据交换架构 省、市、及区县的电梯应急救援平台通过三级数据交换架构形式进行，省级平台为省级部门提供数据服务支撑，与市级各平台互联互通；市级平台为市级部门提供数据服务支撑，与各区县/地方平台互联互通。 数据交换架构如图1所示： 图1 数据交换架构体系图 省级平台建立数据交换节点或通过前置机部署数据库，开通市级平台接口访问权限，完成与市级平台的数据交换； 市级平台建立数据交换节点或通过前置机部署数据库，开通区县/地方平台接口访问权限，完成与各区县/地方平台的数据交换。 5 数据交换模式 5.1 数据接口调用 5.1.1 通过基于HTTP协议的接口调用实现数据交换 注：适用于获取实时性、小数据包、结构化、非结构化、半结构化的数据，以及具备接口调用存储能力的系统。 5.1.2 接口调用流程应符合图2的要求，详细的接口清单及约定内容见《附件A 电梯应急救援HTTP接口协议要求》 图2 接口调用流程图 注：适用于获取实时性、小数据包服务方：即提供接口服务的一方；调用方：即需要进行接口调用的一方； 调用方在首次调用接口前需预先提供调用方的相关信息，以获取服务方提供的用户识别码，根据用户识别码鉴权获取接口服务的授权码，从而进行接口的访问调用，返回的接口响应状态编码详情见第6章。 5.2 数据抽取服务 5.2.1 通过数据抽取服务实现数据交换。 注：一般用于数据量大、实时性要求不高、不具备HTTP接口调用能力或局域网部署的周期性、结构化的数据场景。 5.2.2 数据库抽取的流程宜符合图3的要求，对接的数据内容见《附件B 电梯应急救援平台数据交换内容》 图3 数据抽取示意图 数据提供方按照预先制定的标准数据结构写入数据，与数据接收方约定数据抽取规则并提供数据库访问权限，数据接收方按照约定内容进行数据抽取并回执数据获取状态。 6 接口基本要求 6.1 同步异步接口使用原则 采用同步方式进行接口交互。 6.2 接口异常响应提示信息原则 6.2.1 接口异常响应提示信息应符合以下原则： a) 接口异常响应中，能够明确的错误信息一定要表述清楚，并记录把详细报错信息记录到日志。 b) 接口异常响应中的错误提示信息，应通俗易懂。 c) 错误日志中需要记录路由信息（包括请求唯一标识等），供运维人员排查问题使用。 6.3 前置库对接协同说明 源数据提供方和目标数据接收方明确好表的结构、名称以及传输时间后，接收方应及时建表，并提供具有该表读写权限的账号信息，以及相对应的地址、端口、实例/库名称；源数据提供方按照给定的连接信息建立ETL脚本清洗、转换、抽取、同步程序。 7 接口响应状态编码 接口响应状态编码要求如表1所示。 表1 接口响应状态码 状态码 说明 200 成功 101 路由字段不存在 201 服务器已经接受请求，但尚未处理 202 服务不可用 203 单次调用包大小超过指定阀值 204 流量超过阀值 205 调用频次过快 206 并发超过阀值 207 IP鉴权异常 208 授权码无效 209 授权码超时 210 报文转换异常 301 服务端连接异常 302 服务端连接超时 303 服务端内部异常 304 服务端请求超时 400 服务器拒绝请求，不能理解请求语法 401 测试接口未实现 404 服务器拒绝请求，该服务不存在 600 服务器遇到错误，无法完成请求 999 未知异常 附录A （规范性附录） 电梯应急救援平台HTTP接口协议要求 7.1 接口申报要求 7.1.1 接口申报应符合如下要求： a) 接口服务方需提供接口服务器地址及端口； b) 协议格式：接口服务器地址:端口号/平台英文名称/分类英文名称/接口英文名称? authorization=授权码，其中分类名称和接口名称详情见1.5节，授权码在访问获取授权码时获得； 例：http://接口服务器地址:端口号/平台英文名称/comm/getDict ?authorization=090988778899809（获取数据字典） c) 用户识别码由安平台名称统一提供，接口对接期间长期有效； d) 接口授权码是针对每个接口服务的，具有时效性限制，系统内限制为30分钟； e) 接口数据模型定义的必填项必须提供； f) 上传数据前应建立校验数据重复性的机制，避免数据重复插入； g) 无特殊说明，接口默认采用HTTP POST接口方法。 7.2 接口日志记录要求 接口调用方、接口提供方均应该对每次调用