ICS 35.240 L 67 福 DB35 建 省 地 方 标 准 DB35/T 1893—2020 生态环境大数据管理平台接口规范 Interface specification for eco-environment big data management platform 2020 - 02 - 20 发布 福建省市场监督管理局 2020 - 05 - 20 实施 发 布 DB35/T 1893—2020 目 次 前言 ................................................................................ II 1 范围 .............................................................................. 1 2 规范性引用文件 .................................................................... 1 3 术语和定义 ........................................................................ 1 4 缩略语 ............................................................................ 1 5 数据接口格式要求 .................................................................. 2 6 传感器数据接口 .................................................................... 4 7 文本/图像/视频类数据接口 ......................................................... 11 8 关系型数据接口 ................................................................... 14 9 数据分析接口 ..................................................................... 15 附录 A（规范性附录） 消息队列服务接口二进制包说明 ................................... 18 附录 B（规范性附录） 聚合类型与数据类型的适用关系表 ................................. 19 参考文献 ............................................................................ 21 I DB35/T 1893—2020 前 言 本标准按照GB/T 1.1—2009给出的规则起草。 本标准由福建省生态环境厅提出。 本标准由福建省信息化标准化技术委员会（SAFJ/TC 11）归口。 本标准起草单位：福建省环境信息中心、清华大学、数字中国研究院（福建）、福州市环境科学研 究院、宁德市环境信息中心、莆田市环境宣教中心。 本标准主要起草人：蔡旺华、王建民、王晨、缪飞、肖桂荣、孙为静、卢云霞、阙华、蒋建、杨锐、 田扬。 II DB35/T 1893—2020 生态环境大数据管理平台接口规范 1 范围 本标准规定了生态环境大数据管理平台（以下简称“平台”）的数据接口格式要求、传感器数据接 口、文本/图像/视频类数据接口、关系型数据接口和数据分析接口等技术规范。 本标准适用于基于生态环境大数据管理平台接口的设计、编程和应用开发。 2 规范性引用文件 下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文件。 凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 HJ 719—2014 环境信息系统数据库访问接口规范 ISO 8601-1:2019 日期和时间 信息交换的表示法 第1部分：基本规则（Date and time— Representations for information interchange—Part 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） 1 DB35/T 1893—2020 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::=<METHOD><ENTRY>[<PARAM>][<HEADER>][<STREAM>] 各 字 段 的 含 义 如 表 1 所 示 。 HTTP 请 求 的 返 回 结 果 包 含 两 部 分 ： 一 部 分 为 HTTP 消 息 的 状 态 码 （StatusCode），表示响应的状态；另一部分为HTTP请求的消息体，消息体默认采用JSON格式进行封装。 2 DB35/T 1893—2020 表1 字段 含义 <METHOD> HTTP请求的方法，本接口中使用到的值有GET，POST，PUT和DELETE，各取值的含义参考HTTP协议。 <ENTRY> Web服务接口的入口地址。 <PARAM> 可选参数，用以传递少量的参数信息。 <HEADER> HTTP请求的消息头部。 <STREAM> 可选的附加流信息，用以传递大量的参数信息。 所有接口定义格式说明如下： 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 服务器服务暂不可用。 3 DB35/T 1893—2020 6 传感器数据接口 6.1 传感器数据模型接口 6.1.1 创建传感器数据模型 接口名：tsTable 说明：创建传感器数据模型。 调用格式：POST /tsTable <STREAM> 语义： 创建传感器数据模型。附加流<STREAM>指定该传感器数据模型所涉及的相关信息，包括但不限 于：模型名称、模型标识（模型ID）、传感器标识（传感器ID）、一个或多个传感器的元数据信息 等，支持JSON格式。 调用结果： 成功状态： 返回的 HTTP 状态码为 201。 失败状态： 返回失败对应的 HTTP 状态码及采用 JSON 封装的响应结果。响应结果包含失败原因，具体 状态码参见 5.3。 6.1.2 修改传感器数据模型 接口名：tsTable 说明：更新传感器数据模型，主要修改模型基本信息及相关属性。 调用格式：PUT /tsTable/{模型ID} <STREAM>