接口出现内部错误

ICSXX.
XXXZXX团体标准T/CSESXXXX—202X流域水环境管理大数据业务系统接口规范Thespecificationforbigdataplatformbusinessinterfaceofwaterenvironmentalmanagementofwatershed(征求意见稿)XXXX-XX-XX发布XXXX-XX-XX实施中国环境科学学会发布T/CSESXXX—202XII目次目次.
II前言.
IV1范围.
12规范性引用文件.
13术语和定义.
13.
1物联网Internetofthings(IoT)13.
2接口interface13.
3服务service13.
4传感器sensor23.
5WebService.
23.
6非结构化数据unstructureddata.
24缩略语.
24.
1HTTP24.
2API24.
3SOAP.
24.
4JSON.
24.
5RESTful.
24.
6UDF.
24.
7MR24.
8OpenMI.
25接口分类与描述格式.
35.
1接口分类.
35.
2接口描述格式.
36物联网传感器数据接口.
46.
1物联网传感器接口模型.
46.
2物联网传感器数据实时接入接口.
56.
3物联网传感器数据批量导入接口.
56.
4物联网传感器数据查询接口.
6T/CSESXXX—202XIII7非结构化数据类接口.
78关系型数据接口.
79服务接口.
710流域水环境模型接口.
810.
1接口框架.
810.
2模型与平台接口.
910.
3模型间接口.
9T/CSESXXX—202XIV前言本标准按照GB/T1.
1—2020《标准化工作导则第1部分:标准化文件的结构和起草规则》的规定起草.
本标准的发布机构不承担识别专利的责任.
本标准由中国环境科学学会归口.
本标准起草单位:北京师范大学、生态环境部信息中心、中科宇图科技股份有限公司.
本标准主要起草人:王国强,张璇,殷国栋,谢刚,谢涛.
T/CSESXXX—202X1流域水环境管理大数据业务系统接口规范1范围本标准规定了流域水环境管理大数据业务系统的数据接口格式要求、物联网传感器数据接口、非结构化数据接口、服务接口、关系型数据接口和流域水环境模型接口等技术规范.
本标准适用于基于流域水环境管理大数据业务系统接口的设计和开发.
2规范性引用文件下列标准中的内容通过文中的规范性引用而构成本标准必不可少的条款.
引用标准的最新版本(包括所有的修改单)适用于本标准.
GB/T35295信息技术大数据术语GB/T35319物联网系统接口GB/T35589信息技术大数据技术参考模型HJ418环境信息系统集成技术规范HJ/T419环境数据库设计与运行管理规范HJ718环境信息共享互联互通平台总体框架技术规范HJ719环境信息系统数据库访问接口规范HJ727环境信息交换技术规范HJ929环保物联网术语3术语和定义下列术语和定义适用于本标准.
3.
1物联网Internetofthings(IoT)通过感知设备,按照约定协议,连接物、人、系统和信息资源,实现对物理和虚拟世界的信息进行处理并作出反应的智能服务系统.
3.
2接口interface预先定义的为应用程序提供实现一定数据访问、数据处理和数据服务等功能的程序、函数或过程.
3.
3服务serviceT/CSESXXX—202X2定义明确、具有自包含特性的功能单元,它的存在不依赖于系统的上下文或者其他服务的状态.
3.
4传感器sensor依照一定的规则,对物理世界中的客观现象、物理属性进行监测,并将监测结果转化为可以进一一步处理的信号的设备.
3.
5WebServiceWebService是一种基于标准的Web协议的可编程组件,是Web服务提供者开放的一系列API,开发人员通过调用这些API来集成Web服务,构建自己的应用程序.
3.
6非结构化数据unstructureddata不具有预定义模型或未以预定义方式组织的数据.
4缩略语4.
1HTTP超文本传输协议(HypertextTransferProtocol).
4.
2API应用程序编程接口(ApplicationProgrammingInterface).
4.
3SOAP简单对象访问协议(SimpleObjectAccessProtocol).
4.
4JSON一种轻量级的数据交换格式(JavaScriptobjectNotation).
4.
5RESTful满足一组架构约束条件和原则的应用程序或设计(RepresentationalStateTransfer).
4.
6UDF用户定义函数(User-DefinedFunction).
4.
7MR映射化简(MapReduce),是一种用于大数据并行处理的分布式计算模型、框架和平台.
4.
8OpenMIT/CSESXXX—202X3开放式模型界面(OpenModelingInterface),是一种模型连接标准,提供了实现水文、水力、水质、水生态环境等不同领域模块构成集成系统的连接机制,用以解决复杂系统中各计算模块之间的连接和数据交互问题.
5接口分类与描述格式5.
1接口分类流域水环境管理大数据业务系统的接口包括数据接口和服务接口两类.
根据数据采集方式和数据特征,数据接口主要包括水环境监测监控物联网采集数据接口,水环境管理业务相关的结构化和非结构化数据接口,以及水模型耦合集成的调用接口.
5.
2接口描述格式接口描述基于如下基本格式:WebService::=[][][]各字段的含义如表1所示.
HTTP请求的返回结果包含两部分:一部分为HTTP消息的状态码(StatusCode),表示响应的状态;另一部分为HTTP请求的消息体,消息体采用JSON格式进行封装.
表1接口描述基本格式说明字段含义HTTP请求的方法,本接口中使用到的值有GET,POST,PUT和DELETE,各取值的含义参考HTTP协议.
WEB服务接口的入口地址.
可选参数,用以传递少量的参数信息.
HTTP请求的消息头部.
可选的附加流信息,用以传递大量的参数信息.
所有接口定义格式说明如下:a)接口名:接口的名称;b)说明:对接口内容的描述;c)调用格式::调用Web服务时的语法格式;d)语义:对调用格式的解释;e)调用结果:Web服务调用结果,包括成功状态和失败状态的下的响应信息.
如无特殊说明,所有Web服务接口调用时都应加上表2中的HTTP请求头.
表2Web服务接口调用请求说明请求头Header取值ValueContent-Typeapplication/json;charset=utf-8Acceptapplication/json;charset=utf-8注:表头的应为是相应的中文的对照,避免引起歧义.
T/CSESXXX—202X46物联网传感器数据接口6.
1物联网传感器接口模型常用的HTTP状态码表示及含义见表3,未列举状态码的名称及含义参考HTTP协议的定义.
表3HTTP状态码表状态码状态码名称含义200OK请求已成功.
201Created对象或资源已成功创建.
202Accepted操作已被成功接受.
302Found重定向跳转.
400BadRequest请求的内容丢失或不合法.
401Unauthorized当前请求需要用户验证.
404NotFound请求的内容不存在.
405MethodNotAllowed客户端请求中的方法被禁止.
409Conflict访问冲突,访问资源已被上锁或可能导致服务器内部状态出错.
415UnsupportedMediaType服务器无法处理请求附带的媒体格式.
500InternalServerError服务器出现内部错误,无法正确响应请求.
503ServiceUnavailable服务器服务暂不可用.
传感器接口模型规定了平台管理传感器及数据接入的相关要求,接口名为:BsTable,如表4所示.
表4传感器模型接口说明序号说明调用格式接口语义调用结果1创建传感器数据模型.
POST/BsTable附加流指定该传感器数据模型所涉及的相关信息,包括但不限于:模型名称、模型标识(模型ID)、传感器标识(传感器ID)、一个或多个传感器的元数据信息等,支持JSON格式.
成功状态:返回的HTTP状态码为201.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
2更新传感器数据模型,主要修改模型基本信息及相关属性.
PUT/BsTable/{模型ID}更新指定模型ID的传感器数据模型的基本信息、属性信息等.
附加流指定需要更新的传感器数据模型,支持JSON格式.
成功状态:返回的HTTP状态码为201.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
3按条件查询指定的传感器数据模型.
GET/BsTable/{模型ID}select={columns}获取满足查询条件的传感器数据模型.
指定模型ID,则查询指定传感器数据模型;未指定模型ID,则查询所有传感器数据模型.
成功状态:返回的HTTP状态码为201,查询结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
4向指定传感器PUT/向指定的传感器数据模型增加传感器相成功状态:返回的HTTP状态码T/CSESXXX—202X5序号说明调用格式接口语义调用结果数据模型添加新的传感器相关信息.
BsTable/addfield/{模型ID}关信息.
附加流指定需要添加新的传感器,支持JSON格式.
为201.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
5修改指定传感器数据模型中的传感器的相关信息.
PUT/BsTable/{模型ID}/fields/{传感器ID}修改指定传感器数据模型中指定传感器ID的相关信息.
附加流指定需要修改的传感器,支持JSON格式.
成功状态:返回的HTTP状态码为200.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
6删除指定传感器数据模型中的某个传感器的相关信息.
DELETE/BsTable/{模型ID}/fields/{传感器ID}当传感器数据模型中某个传感器失效或者不需要时,可以删除指定传感器的相关信息.
成功状态:返回的HTTP状态码为200.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
6.
2物联网传感器数据实时接入接口根据物联网传感器所处的物理位置和网络环境,本标准规定了三种接口及要求,如表5所示.
表5物联网数据实时接入接口说明序号接入形式说明调用格式接口语义调用结果1Web服务接口提供RESTful接口实时接入传感器数据.
POST/channels/devices/data面向传感器数据模型实时接入传感器数据.
附加流指定传感器,支持JSON格式,应在HTTP请求的Content-Type中指定.
成功状态:返回的HTTP状态码为202.
失败状态:返回的HTTP状态码为503.
2消息队列服务接口提供消息队列服务接口实时接入传感器数据.
用户通过调用消息队列服务接口将数据写入平台.
写入数据格式支持JSON数据和二进制数据.
POST/time-series-queue将某个时间点的若干传感器数据通过消息队列服务接口写入平台.
其中,写入JSON数据时,写入的中应包括传感器数据所属的传感器数据模型、传感器标识(传感器ID)、传感器数据:产生的时间、各个传感器在这个时间的值等信息.
成功状态:返回的HTTP状态码为202.
失败状态:返回的HTTP状态码为503.
3Java编程接口将数据转化成平台能够识别的传感器数据记录.
--参考返回状态码表.
6.
3物联网传感器数据批量导入接口通过RESTful架构导入文件时,导入文件应符合下列要求:T/CSESXXX—202X6a)文件编码为UTF-8;b)文件为CSV格式(以逗号或分号或单竖线作为列分隔符,回车作为行分隔符);c)一行一条数据记录;d)数据涉及的传感器数据模型需在平台中完成注册;e)每条数据记录中数据列数应与传感器数据模型定义的传感器相同且取值一一对应.
传感器数据批量导入接口规定了新建导入任务、上传传感器数据文件、获取导入任务列表、获取任务详情、获取单个任务状态的要求,具体如表6所示.
表6传感器数据批量导入接口序号接口说明调用格式接口语义调用结果1新建导入任务POST/workflows新建批量导入任务.
附加流指定导入任务相关的信息,包括但不限于要导入的文件标识等,支持JSON格式.
成功状态:返回的HTTP状态码为201,生成任务ID,结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
2上传传感器数据文件POST/workflows/file-Upload将需要导入的文件上传到平台.
成功状态:返回的HTTP状态码为201,结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
3获取导入任务列表GET/workflows获取正在执行的和已经执行完成的批量导入任务列表.
成功状态:返回的HTTP状态码为200,查询结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
4获取任务详情GET/workflows/{任务ID}根据任务ID查看导入任务的相关信息,包括任务报告.
成功状态:返回HTTP状态码200,返回结果采用JS0N封装,包含导入任务相关信息.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
5获取单个任务状态GET/workflows/status/{任务ID}根据任务ID查询某个任务状态.
成功状态:返回HTTP状态码201,返回结果采用JSON封装,任务状态信息.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
6.
4物联网传感器数据查询接口物联网传感器数据查询接口,规定了流数据、行数据、点数据、聚合数据的查询要求,具体如表7所示.
表7传感器数据查询接口序号查询类型查询说明调用格式接口语义调用结果1数据流查询提供数据流查询接口查询传感器POSTdata-streamsGET根据指定查询语句,获取满足条件的传感器成功状态:返回的HTTP状态码为200,查询结果采用T/CSESXXX—202X7序号查询类型查询说明调用格式接口语义调用结果数据,适用于传感器流模型.
/data-streamsquery=流模型数据集.
查询结果可指定每页数量、可指定页、可排序.
JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
2数据行查询提供数据行查询接口查询传感器数据,适用于传感器行模型.
POST/data-rowsGET/data-rowsquery=根据指定查询语句,获取满足条件的传感器行模型数据集.
查询结果可指定每页数量、可指定页、可排序.
成功状态:返回的HTTP状态码为200,查询结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
3数据点查询提供数据点查询接口查询传感器数据,适用于传感器行模型,也可适用于传感器流模型.
POST/data-pointsGET/data-pointsquery=根据指定查询语句,获取满足条件的传感器数据集.
查询结果可指定每页数量、可指定页、可排序.
成功状态:返回的HTTP状态码为200,查询结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
4数据聚合查询提供数据聚合查询接口查询传感器的聚合数据,在点查询返回的结果集基础上再做聚合.
POST/data-aggregationGET/data-aggregationquery=根据指定的聚合查询条件,获取满足条件的传感器数据并做聚合;查询参数包括但不限于数据过滤条件、需要聚合的传感器ID、聚合类型(最大值、最小值、平均值等);支持对多个传感器做不同类型的聚合查询.
成功状态:返回的HTTP状态码为200;查询结果采用JSON封装.
失败状态:返回失败对应的HTTP状态码及采用JSON封装的响应结果.
7非结构化数据类接口创建非结构化类型的数据模型附加流指定该类型数据所涉及的相关信息,包括但不限于对象类型名称、属性列表.
接口服务功能应当包括但不限于创建、修改、删除、查询、搜索和导出.
接口返回状态应参考表3.
8关系型数据接口流域水环境管理大数据业务系统关系型数据接口参照HJ719-2014的规定执行.
9服务接口T/CSESXXX—202X8业务系统大数据分析组件包括但不限于以下四种:UDFAPI、MRAPI、数据导入导出API和数据质量检查API.
流域水环境管理大数据业务系统开发宜集成上述组件.
流域水环境管理大数据业务系统服务接口开发应遵循GB/T35295-2017和GB/T35589-2017的规定.
10流域水环境模型接口10.
1接口框架流域水环境管理大数据业务系统耦合集成水文、水动力、水环境等模型过程中,通常模型与可为之提供输入数据的数据源之间并不具备相同的数据定义,两者之间进行数据交换需要转换数据源数据至满足模型输入数据要求的形式,模型与数据源之间的一般关系如图1所示.
图1模型与数据源一个完整的模型数据接口描述要素集包含两大部分内容:模型输入输出数据项集和数据源与模型之间的数据映射关系集,如图2所示.
图2模型数据接口描述元素集结构模型数据接口要素集模型输入输出数据项集数据源与模型间数据关系集输入数据项集参数集输出数据项集数据源信息数据关系集数据源数据转换输入数据输出数据模型T/CSESXXX—202X910.
2模型与平台接口模型输入输出数据项集描述如表8所示.
表8模型输入输出数据项集序号中文名称英文名称缩写名定义数据类型约束/条件1模型数据接口要素集合ModelDataInterfaceElementSetMDIElementSet定义流域水环境模型数据接口描述要素的根实体.
类M2模型标识符Identifierid模型的唯一标识符.
同模型元数据信息中所给出的标识符一致.
字符串M3模型输入数据项个数InputItemCountinputItemCount对模型输入数据项个数的说明.
整型M4模型输入数据项InputIteminputItem对流域水环境模型需要的每个输入数据项的说明.
类M5模型参数个数ParameterCountparamCount对模型所需要的每个参数的说明.
整型M6模型参数Pamameterpamam对流域水环境模型所需要的每个参数的说明.
类C/模型参数个数>0时必选.
7模型输出数据项个数OutputItemCountoutputItemCount对模型输出数据项个数的说明.
整型M8模型输出数据项OutputItemoutputItem对流域水环境模型每个输出数据项的说明.
类M9角色名称:模型与数据源数据关系信息Rolename:DataRelationshipInformationdataRelationshipInfo可为流域水环境模型提供部分或全部输入数据的数据源与模型输入数据项之间关系的有关信息.
关联O10.
3模型间接口流域水环境模型的接口调用,主要体现在模型间的接口调用和模型与系统间的接口调用.
模型间的数据接口宜采用OpenMIStandard2SpecificationfortheOpenMI要求.
其模型原理如图3所示:T/CSESXXX—202X10图3OpenMI标准接口原理图中A和B表示按OpenMI技术要求标准化的模型组件.
OpenMI采用"请求-响应"机制,运行时根据预定义的交互模式实现模型组件间的数据请求与返回.
1、单向数据请求:组件A单向地从组件B中请求数据,如果B已完成对A所需数据的计算,它将直接返回所需数据;如果计算尚未完成,提出需求的模型将等待所需数据的返回.
2、双向数据交互:组件A需要从组件B中获得数据,而组件B完成计算需从组件A中获取某种物理量数据.
若组件A请求的数据在时间与空间上与B模型的计算值不匹配,要求模型做相应处理后返回请求值,对返回的数据在数据格式与科学语意上必须相匹配.