DB35∕T 1893-2020 生态环境大数据管理平台接口规范(福建省).pdf

ICS 35.240 L 67 DB35 福建省地方标准 DB35/T 18932020 生态环境大数据管理平台接口规范 Interface specification for eco-environment big data management platform 2020 - 02 - 20 发布 2020 - 05 - 20 实施福建省市场监督管理局 发 布 DB35/T 18932020 I 目 次 前言 . II 1 范围 . 1 2 规范性引用文件 . 1 3 术语和定义 . 1 4 缩略语 . 1 5 数据接口格式要求 . 2 6 传感器数据接口 . 4 7 文本/图像/视频类数据接口 . 11 8 关系型数据接口 . 14 9 数据分析接口 . 15 附录 A（规范性附录） 消息队列服务接口二进制包说明. 18 附录 B（规范性附录） 聚合类型与数据类型的适用关系表. 19 参考文献 . 21 DB35/T 18932020 II 前 言 本标准按照GB/T 1.12009给出的规则起草。 本标准由福建省生态环境厅提出。 本标准由福建省信息化标准化技术委员会（SAFJ/TC 11）归口。 本标准起草单位：福建省环境信息中心、清华大学、数字中国研究院（福建）、福州市环境科学研究院、宁德市环境信息中心、莆田市环境宣教中心。 本标准主要起草人：蔡旺华、王建民、王晨、缪飞、肖桂荣、孙为静、卢云霞、阙华、蒋建、杨锐、田扬。 DB35/T 18932020 1 生态环境大数据管理平台接口规范 1 范围 本标准规定了生态环境大数据管理平台（以下简称“平台”）的数据接口格式要求、传感器数据接口、文本/图像/视频类数据接口、关系型数据接口和数据分析接口等技术规范。 本标准适用于基于生态环境大数据管理平台接口的设计、编程和应用开发。 2 规范性引用文件 下列文件对于本文件的应用是必不可少的。 凡是注日期的引用文件， 仅注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 HJ 7192014 环境信息系统数据库访问接口规范 ISO 8601-1:2019 日期和时间 信息交换的表示法 第1部分：基本规则（Date and timeRepresentations for information interchangePart 1: Basic rules） 3 术语和定义 下列术语和定义适用于本文件。 3.1 生态环境大数据管理平台 eco-environment big data management platform 对不同类型生态环境数据进行存储、管理和分析的大数据管理平台。 3.2 接口 interface 预先定义的为应用程序提供实现一定数据访问、数据处理和数据服务等功能的程序、函数或过程。 3.3 传感器数据模型 sensor data model 识别、存储传感器数据的数据模型。 3.4 传感器流模型 sensor stream model 以传感器数据中每个传感器的每次采集行为作为数据操作对象。 3.5 传感器行模型 sensor row model 以传感器数据中每个传感器的每条行记录作为数据操作对象。 4 缩略语 下列缩略语适应于本文件。 API：应用程序编程接口（Application Programming Interface） DB35/T 18932020 2 HTTP：超文本传输协议（Hyper Text Transfer Protocol） IP：英特网协议地址（Internet Protocol） JSON：一种轻量级的数据交换格式（Java Script Object Notation） RESTful：满足一组架构约束条件和原则的应用程序或设计（Representational State Transfer） Web：全球广域网（World Wide Web） 5 数据接口格式要求 5.1 数据接口分类 平台接口遵循RESTful API规范，数据接口分类架构如图1所示： 图1 5.2 接口描述格式 接口描述基于如下基本格式： WebService:= 各字段的含义如表1所示。HTTP请求的返回结果包含两部分：一部分为HTTP消息的状态码（StatusCode） ， 表示响应的状态； 另一部分为HTTP请求的消息体， 消息体默认采用JSON格式进行封装。 传感器数据 建模接口 传感器数据 实时接入接口 传感器数据 批量导入 传感器数据 查询接口 传感器数据接口 对象类型接口 上传文件 对象数据操作接口 文档/图片/视频类数据接口 配置同步任务 业务关系型 数据接口 分析脚本接口 分析模型接口 分析作业接口 数据分析接口 生态环境大数据管理平台接口规范 外部时序数据 （包括数据接入系统及需要查询时序数据的业务） 外部对象数据 （包括数据接入系统及需要查询对象数据的业务） 外部关系数据 外部分析业务 DB35/T 18932020 3 表1 字段 含义 HTTP请求的方法，本接口中使用到的值有GET，POST，PUT和DELETE，各取值的含义参考HTTP协议。 Web服务接口的入口地址。 可选参数，用以传递少量的参数信息。 HTTP请求的消息头部。 可选的附加流信息，用以传递大量的参数信息。 所有接口定义格式说明如下： a) 接口名：接口的名称； b) 说明：对接口内容的描述； c) 调用格式：调用 Web 服务时的语法格式； d) 语义：对调用格式的解释； e) 调用结果：Web 服务调用结果，包括成功状态和失败状态的下的响应信息。 如无特殊说明，所有Web服务接口调用时都应加上表2中的HTTP请求头。 表2 请求头 Header 取值 Value Content-Type application/json;charset=utf-8 Accept application/json;charset=utf-8 注：表头的英文是相应中文的对照，避免引起歧义。 5.3 HTTP 状态码 常用的HTTP状态码表示及含义见表3，未列举状态码的名称及含义参考HTTP协议的定义。 表3 状态码编号 状态码名称 含义 200 OK 请求已成功。 201 Created 对象或资源已成功创建。 202 Accepted 操作已被成功接受。 302 Found 重定向跳转。 400 Bad Request 请求的内容丢失或不合法。 401 Unauthorized 当前请求需要用户验证。 404 Not Found 请求的内容不存在。 405 Method Not Allowed 客户端请求中的方法被禁止。 409 Conflict 访问冲突，访问资源已被上锁或可能导致服务器内部状态出错。 415 Unsupported Media Type 服务器无法处理请求附带的媒体格式。 500 Internal Server Error 服务器出现内部错误，无法正确响应请求。 503 Service Unavailable 服务器服务暂不可用。 DB35/T 18932020 4 6 传感器数据接口 6.1 传感器数据模型接口 6.1.1 创建传感器数据模型 接口名：tsTable 说明：创建传感器数据模型。 调用格式：POST /tsTable 语义： 创建传感器数据模型。 附加流指定该传感器数据模型所涉及的相关信息， 包括但不限于：模型名称、模型标识（模型ID）、传感器标识（传感器ID）、一个或多个传感器的元数据信息等，支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 201。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.1.2 修改传感器数据模型 接口名：tsTable 说明：更新传感器数据模型，主要修改模型基本信息及相关属性。 调用格式：PUT /tsTable/模型ID 语义： 更新指定模型ID的传感器数据模型的基本信息、 属性信息等。 附加流指定需要更新的传感器数据模型，支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 201。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.1.3 查询传感器数据模型 接口名：tsTable 说明：按条件查询指定的传感器数据模型。 调用格式：GET /tsTable/模型ID?select=columns 语义： 获取满足查询条件的传感器数据模型。指定模型ID，则查询指定传感器数据模型；未指定模型ID，则查询所有传感器数据模型。查询所有记录时，支持输入需要返回的列名，查询结果可指定每页数量、可指定页、可排序。 调用结果： 成功状态： DB35/T 18932020 5 返回的 HTTP 状态码为 201，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.1.4 添加传感器 接口名：tsTable 说明：向指定传感器数据模型添加新的传感器相关信息。 调用格式：PUT /tsTable/addfield/模型ID 语义： 向指定的传感器数据模型增加传感器相关信息。 附加流指定需要添加新的传感器， 支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 201。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.1.5 修改传感器 接口名：tsTable 说明：修改指定传感器数据模型中的传感器的相关信息。 调用格式：PUT /tsTable/模型ID/fields/传感器ID 语义： 修改指定传感器数据模型中指定传感器ID的相关信息。附加流指定需要修改的传感器，支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 200。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.1.6 删除传感器 接口名：tsTable 说明：删除指定传感器数据模型中的某个传感器的相关信息。 调用格式：DELETE /tsTable/模型ID/fields/传感器ID 语义： 当传感器数据模型中某个传感器失效或者不需要时，可以删除指定传感器的相关信息。 调用结果： 成功状态： 返回的 HTTP 状态码为 200。 失败状态： DB35/T 18932020 6 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.2 传感器数据实时接入接口 6.2.1 Web 服务接口 接口名：channels 说明：提供RESTful接口实时接入传感器数据。 调用格式：POST /channels/devices/data 语义： 面向传感器数据模型实时接入传感器数据。附加流指定传感器，支持JSON格式，应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的 HTTP 状态码为 202。 失败状态： 返回的 HTTP 状态码为 503。 6.2.2 消息队列服务接口 接口名：time-series-queue 说明： 提供消息队列服务接口实时接入传感器数据。 用户通过调用消息队列服务接口将数据写入平台。写入数据格式支持JSON数据和二进制数据。两种类型的数据应分别写到对应的主题（topic）中，写入的数据应保证各个分区（partition）的均匀分布，通行的做法是设置主键（key）为null。写入二进制数据时，二进制包主要由三部分构成：包头、包体和包尾，见附录A。 调用格式：POST / time-series-queue 语义： 将某个时间点的若干传感器数据通过消息队列服务接口写入平台。其中，写入JSON数据时，写入的中应包括传感器数据所属的传感器数据模型、传感器标识（传感器ID）、传感器数据产生的时间、各个传感器在这个时间的值等信息。 调用结果： 成功状态： 返回的 HTTP 状态码为 202。 失败状态： 返回的 HTTP 状态码为 503。 6.2.3 Java 编程接口 6.2.3.1 生成数据记录接口 接口名：GenRecord 说明：将数据转化成平台能够识别的传感器数据记录。 提供方法见表4： DB35/T 18932020 7 表4 方法名及参数列表 说明 setFieldGroupId(String tsd) 设置传感器数据模型，取值应与 6.1.1 模型 ID 匹配。 setTimestamp(long timestamp) 设置传感器数据记录时间，取值类型为长实型。 setIso(String iso) 设置传感器数据记录时间，取值类型为 ISO 型。 setField(String FieldID， Object value) 设置传感器的监测值。参数中 FieldID 表示传感器 ID，value 表示传感器的监测值。 getRecord() 获得传感器生成的数据记录。 setTimestamp(long timestamp)设置数据记录时间的优先级高于setIso(String iso)。 6.2.3.2 SDK 配置接口 接口名：Config 说明：设置SDK客户端的配置参数信息。 方法:void put(String key,Object value) 参数如表5所示： 表5 参数 key 取值 对应 value 取值 ParamNames.PLATFORM_SERVER value 的数据类型为 String，必填。取值为平台的服务地址，应同时包含 IP和 Port。 ParamNames.SEND_TIMEOUT_MILLISECS value 的数据类型为 Long，非必填。取值为发送记录的超时时间，单位毫秒，默认为 30000。 ParamNames.DATA_TYPE value 的数据类型为枚举类型，非必填。用来设置发送数据格式，默认值为DataType.JSON_STRING （JSON 数据） ， 可设置为 DataType.BINARY （二进制） 。 6.3 传感器数据批量导入接口 6.3.1 总则 通过RESTful架构导入文件时，单个文件大小不超过2G，导入文件应符合下列要求： 文件编码为 UTF-8； 文件为 csv 格式（以逗号或分号或单竖线作为列分隔符，回车作为行分隔符）； 一行一条数据记录； 数据涉及的传感器数据模型已注册； 数据已按照传感器数据模型定义进行相关的预处理； 每条数据记录中数据列数应与传感器数据模型定义的传感器相同且取值一一对应； 时间格式按照 ISO 8601-1:2019 的规定。 DB35/T 18932020 8 6.3.2 新建导入任务 接口名：workflows 说明：创建新导入任务。 调用格式：POST /workflows 语义： 新建批量导入任务。 附加流指定导入任务相关的信息， 包括但不限于要导入的文件标识等，支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 201，生成任务 ID，结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.3.3 上传传感器数据文件 接口名：workflows 说明：将需要导入的文件上传到平台。 调用格式：POST /workflows/file-upload 请求头（Header）：ContentType: multipart/form-data 语义： 将需要导入的文件上传到平台。 调用结果： 成功状态： 返回的 HTTP 状态码为 201，结果采用 JSON 封装。返回的结果中包含文件的唯一标识。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.3.4 获取导入任务列表 接口名：workflows 说明：获取正在执行的和已经执行完成的批量导入任务列表，支持分页。 调用格式：GET /workflows 语义： 获取正在执行的和已经执行完成的批量导入任务列表。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 DB35/T 18932020 9 6.3.5 获取任务详情 接口名：workflows 说明：查看批量导入任务相关的详情。 调用格式：GET /workflows/任务ID 语义： 根据任务ID查看导入任务的相关信息，包括任务报告。 调用结果： 成功状态： 返回 HTTP 状态码 200，返回结果采用 JSON 封装，包含导入任务相关信息。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.3.6 获取单个任务状态 接口名：workflows 说明：获取批量导入任务的执行状态和进度。 调用格式：GET /workflows/status/任务ID 语义： 根据任务 ID 查询某个任务状态。 调用结果： 成功状态： 返回 HTTP 状态码 201，返回结果采用 JSON 封装，任务状态信息。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.4 传感器数据查询接口 6.4.1 数据流查询 接口名：data-streams 说明：提供数据流查询接口查询传感器数据，适用于传感器流模型。 调用格式： POST /data-streams GET /data-streams?query= 语义： 根据指定查询语句，获取满足条件的传感器流模型数据集。查询结果可指定每页数量、可指定页、可排序。附加流指定查询语句，支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 DB35/T 18932020 10 6.4.2 数据行查询 接口名：data-rows 说明：提供数据行查询接口查询传感器数据，适用于传感器行模型。 调用格式： POST /data-rows GET /data-rows?query= 语义： 根据指定查询语句，获取满足条件的传感器行模型数据集。查询结果可指定每页数量、可指定页、 可排序。 附加流指定查询语句， 支持JSON格式， 应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.4.3 数据点查询 接口名：data-points 说明：提供数据点查询接口查询传感器数据，适用于传感器行模型，也可适用于传感器流模型。 调用格式： POST /data-points GET /data-points?query= 语义： 根据指定查询语句，获取满足条件的传感器数据集。查询结果可指定每页数量、可指定页、可排序。附加流指定查询语句，支持JSON格式，应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 6.4.4 数据聚合查询 接口名：data-aggregation 说明：提供数据聚合查询接口查询传感器的聚合数据，在点查询返回的结果集基础上再做聚合。 调用格式： POST /data-aggregation GET /data-aggregation?query= 语义： 根据指定的聚合查询条件， 获取满足条件的传感器数据并做聚合； 查询参数包括但不限于数据过滤条件、需要聚合的传感器ID、聚合类型（最大值、最小值、平均值等）；支持对多个DB35/T 18932020 11 传感器做不同类型的聚合查询；用做聚合查询的传感器数据类型应满足附录B中表B.1或表B.2的规定。附加流指定查询语句，支持JSON格式，应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的HTTP状态码为200；查询结果采用JSON封装。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 7 文本/图像/视频类数据接口 7.1 对象类型接口 7.1.1 创建对象类型 接口名：object-classes 说明： 提供文本/图像/视频类数据类型建模接口。 调用格式：POST /object-classes 语义： 创建文本/图像/视频类数据类型的数据模型， 附加流指定该类型数据所涉及的相关信息， 包括但不限于对象类型名称、 属性列表， 支持JSON格式， 应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的 HTTP 状态码为 201，结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.1.2 修改对象类型 接口名：object-classes 说明：提供文本/图像/视频类数据类型更新接口。 调用格式：PUT /object-classes/对象类型ID 语义： 更新对象类型ID指定的文本/图像/视频类数据类型的数据模型。 附加流指定需要更新的类型数据信息，支持JSON格式，应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的HTTP状态码为200，结果采用JSON封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.1.3 删除对象类型 接口名：object-classes DB35/T 18932020 12 说明：提供文本/图像/视频类数据类型删除接口。 调用格式：DELETE /object-classes/对象类型ID 语义： 删除对象类型ID指定的文本/图像/视频类数据类型的数据模型。 调用结果： 成功状态： 返回的 HTTP 状态码为 200。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.1.4 查询对象类型 接口名：object-classes 说明：按条件查询指定的数据类型。 调用格式：GET /object-classes/对象类型ID?query=过滤条件 语义： 获取满足查询条件的数据。指定对象类型ID，则查询指定数据类型；未指定对象类型ID，则查询所有数据类型。输入过滤条件，则查询满足条件的对象类型；未输入过滤条件，则查询对象类型的所有信息。查询结果可指定每页数量、可指定页、可排序，支持模糊查询。 调用结果： 成功状态： 返回的 HTTP 状态码为 201，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.2 上传文本/图像/视频类数据文件 接口名：file-uploads 说明：将对象关联的文件上传到平台。 调用格式：POST / file-uploads/对象类型ID/upload 语义：将对象关联的文件上传到平台。 请求头（Header）：ContentType: multipart/form-data 调用结果： 成功状态： 返回的 HTTP 状态码为 201，结果采用 JSON 封装。返回结果中包含文件的唯一标识。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.3 对象数据接口 7.3.1 创建对象数据 接口名：object-metadata DB35/T 18932020 13 说明：提供文本/图像/视频类数据建模接口。 调用格式：POST /object-metadata 语义： 创建文本/图像/视频类数据模型， 附加流指定该数据所涉及的相关信息， 包括但不限于元数据、资源路径等，支持JSON格式，应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的 HTTP 状态码为 201。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.3.2 修改对象数据 接口名：object-metadata 说明：提供文本/图像/视频类数据更新接口。 调用格式：PUT /object-metadata 语义： 更新指定的文本/图像/视频类数据的元数据。 附加流指定对象元数据， 支持JSON格式，应在HTTP请求的Content-Type中指定。 调用结果： 成功状态： 返回的 HTTP 状态码为 200。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.3.3 删除对象数据 接口名：object-metadata 说明：提供文本/图像/视频类数据删除接口。 调用格式：DELETE /object-metadata 语义： 删除指定的文本/图像/视频类数据的元数据。 附加流指定对象元数据， 支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 200。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.3.4 查询对象数据 接口名：object-metadata 说明：按条件查询指定的文本/图像/视频类数据。 调用格式：GET /object-metadata?fields= DB35/T 18932020 14 语义： 根据指定元数据，获取满足查询条件的对象数据。查询结果可指定每页数量、可指定页、可排序。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，查询结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.3.5 搜索对象数据 接口名：object-metadata 说明：按条件搜索指定的文本/图像/视频类数据。 调用格式：GET /search/object-metadata?query= 语义： 根据指定描述属性，获取满足查询条件的对象数据，支持“=”、“IN”、“LIKE”、时间区间等匹配条件。搜索结果可指定每页数量、可指定页、可排序。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 7.3.6 导出对象数据 接口名：object-metadata 说明：按条件查询/搜索指定的文本/图像/视频类数据，并进行批量导出。 调用格式：GET /export/search/object-metadata?export=过滤条件 语义： 根据指定描述属性，获取并导出满足查询/搜索条件的对象数据，支持“=”、 “IN” 、 “LIKE”、时间区间等匹配条件。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，结果采用 JSON 封装。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。 响应结果包含失败原因， 具体状态码参见 5.3。 8 关系型数据接口 平台支持主流关系型数据库作为数据源，包括但不限于：SQLServer，MySQL和Oracle等主流关系型数据库。 平台关系型数据接口规范按照HJ 7192014的规定。 DB35/T 18932020 15 9 数据分析接口 9.1 分析模型接口 9.1.1 新建分析模型 接口名：model 说明：创建新的分析模型。 调用格式：POST /model 语义： 创建新的分析模型， 附加流指定该分析模型使用的数据源节点、 计算节点及分析流程图等信息， 支持JSON格式。 数据源节点的信息包括但不限于数据源节点的唯一标识、 数据源的类型、过滤条件和获取数据的方式。 计算节点的信息包括但不限于计算节点的唯一标识脚本类型、 脚本参数、脚本信息和脚本程序入口。 调用结果： 成功状态： 返回的HTTP状态码为201，生成分析模型ID，结果采用JSON封装。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 9.1.2 修改分析模型 接口名：model 说明：修改已存在的分析模型。 调用格式：PUT /model 语义： 修改已存在的分析模型。附加流指定该分析模型ID、使用的数据源节点、计算节点及分析流程图等信息，支持JSON格式。数据源节点的信息包括但不限于数据源节点的唯一标识、数据源的类型、过滤条件和获取数据的方式。计算节点的信息包括但不限于计算节点的唯一标识脚本类型、脚本参数、脚本信息和脚本程序入口。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，结果采用 JSON 封装。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 9.1.3 查看分析模型 接口名：model 说明：查看已存在的分析模型的信息。 调用格式：GET /model/$分析模型ID 语义： 查看已存在的分析模型的信息。 调用结果： DB35/T 18932020 16 成功状态： 返回的 HTTP 状态码为 200。返回结果采用 JSON 封装，结果包含分析模型 ID、使用的数据源节点、计算节点及分析流程图等相关信息。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。响应结果包含失败原因，具体状态码参见5.3。 9.2 上传分析脚本接口 接口名：file-uploads 说明：上传计算节点需要的脚本文件。 调用格式：POST /file-upload 请求头（Header）：ContentType:multipart/form-data 语义： 上传计算节点所需要的可执行脚本文件到平台。 调用结果： 成功状态： 返回 HTTP 状态码为 201，生成平台识别脚本时的脚本信息，结果采用 JSON 封装。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 9.3 分析作业接口 9.3.1 提交分析作业 接口名：jobs 说明：提交分析作业到平台。 调用格式：POST /jobs 语义： 提交运行一个分析模型实例，将分析任务提交到平台执行。附加流指定需要运行的分析模型信息，包括但不限于分析模型ID、分析作业名称以及其他分析需要的相关参数，支持JSON格式。 调用结果： 成功状态： 返回的HTTP状态码为201，生成分析作业ID，结果采用JSON封装。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 9.3.2 查看分析作业 接口名：jobs 说明：查看分析作业。 调用格式：GET /jobs/$分析作业ID 语义： DB35/T 18932020 17 查看指定的分析作业信息。 调用结果： 成功状态： 返回的 HTTP 状态码为 200，返回结果采用 JSON 封装，结果包含分析作业 ID、作业执行相关信息、作业运行进度和状态等相关信息。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 9.4 查看分析结果 接口名：jobs-result 说明：查看分析作业的分析输出结果。 调用格式：GET /jobs-result/$分析作业ID 语义： 查看分析作业的输出结果。 调用结果： 成功状态： 返回的HTTP状态码为200，返回结果采用JSON封装，结果包含分析作业ID、分析输出结果等相关信息。 失败状态： 返回失败对应的HTTP状态码及采用JSON封装的响应结果。 响应结果包含失败原因， 具体状态码参见5.3。 DB35/T 18932020 18 附 录 A （规范性附录） 消息队列服务接口二进制包说明 消息队列服务接口二进制包说明见表A.1。 表A.1 构成部分 结构及含义 包头 第 12 字节：对齐标记位，内容是字符K、2的 UTF-8 码，即 01001011 00110010。 第 36 字节：标记整个消息的长度。 第 7 字节： 0000 0000：最高位为 0，表示单个记录发送； 1000 0000：最高位为 1，表示批量记录发送。 第 8 字节：对于批量发送的情况，该字节标记包含的记录个数；对于单个记录发送的情形，不包含该字节。 0000 0000 1111 1111：表示批量发送时包含的记录个数，范围 0255。 包体 包含若干记录，对于每个记录的结构如下： 1. 4 字节用于存储整个 Record 的字节数。 2. 传感器数据模型： 第一个字节表示传感器数据模型 ID 字符串长度 N； 后续 N 个字节表示传感器数据模型 ID 实际内容（UTF-8 编码）。 3. 时间戳：8 字节，表示对应记录的时间，格式为时间戳（Long 类型的时间）。 4. 传感器集：存放所有传感器数据模型 ID 和对应时间的传感器取值。 包尾 两个字节，留作以后使用，比如作为 CRC 校验码等。 DB35/T 18932020 19 附 录 B （规范性附录） 聚合类型与数据类型的适用关系表 B.1 适用于历史数据统计型分析查询 适用历史数据统计型分析查询的传感器数据类型见表B.1。 表B.1 适用 Apply(Y/N) 总数 Count 最小 Min 最大 Max double, float Y (exclude null) Y Y integer, long Y (exclude null) Y Y boolean Y (exclude null) N N string Y (exclude null) N N 注：表头的英文是相应中文的对照，避免引起歧义。 DB35/T 18932020 20 B.2 适用于历史数据探索型分析查询 适用历史数据探索型分析查询的传感器数据类型见表B.2。 表 B.2 适用 Apply(Y/N) 总数 Count 最小 Min 最大 Max 求和 Sum 均值 Avg 极差 range 标准差 Stddev 方差 variance 描述 description Double, Float Y (exclude null) Y Y Y Y Y Y Y Integer, Long Y (exclude null) Y Y Y Y Y Y Y Boolean Y (exclude null)