2022 流域水環(huán)境管理大數(shù)據(jù)業(yè)務系統(tǒng)接口規(guī)范

流域水環(huán)境管理大數(shù)據(jù)業(yè)務系統(tǒng)接口規(guī)范目 次前 言 II范圍 1規(guī)范性引用文件 1術語和定義 1縮略語 2接口分類與描述格式 3物聯(lián)網(wǎng)傳感器數(shù)據(jù)接口 4結構化數(shù)據(jù)接口 8非結構化數(shù)據(jù)類接口 8流域水環(huán)境模型接口 9服務接口 11I1111IIII流域水環(huán)境管理大數(shù)據(jù)業(yè)務系統(tǒng)接口規(guī)范范圍結構化數(shù)據(jù)接口、流域水環(huán)境模型接口、服務接口。本文件適用于流域水環(huán)境管理大數(shù)據(jù)業(yè)務系統(tǒng)接口的設計開發(fā)及數(shù)據(jù)共享等應用構建。規(guī)范性引用文件（包括所有的修改單）適用于本文件。GB/T29811.1信息技術學習、教育和培訓學習系統(tǒng)體系結構與服務接口GB/T35295信息技術大數(shù)據(jù)術語GB/T35319物聯(lián)網(wǎng)系統(tǒng)接口要求GB/T35589信息技術大數(shù)據(jù)技術參考模型HJ/T418環(huán)境信息系統(tǒng)集成技術規(guī)范HJ719環(huán)境信息系統(tǒng)數(shù)據(jù)庫訪問接口規(guī)范HJ727環(huán)境信息交換技術規(guī)范929環(huán)保物聯(lián)網(wǎng)術語術語和定義下列術語和定義適用于本文件。3.1物聯(lián)網(wǎng)internetofthings(IoT)進行處理并作出反應的智能服務系統(tǒng)。[來源：GB/T35319-2017,3.1]3.2接口interface程。PAGEPAGE3PAGEPAGE103.3服務service定義明確、具有自包含特性的功能單元，它的存在不依賴于系統(tǒng)上下文或者其他服務的狀態(tài)。[來源：GB/T29811.1-2013,3.2]3.4傳感器sensor一步處理的信號的設備。注1：信號可以是電子的、化學的或者其他形式的傳感器響應。注2：信號可以表示為1維、2維、3維或更高維度的數(shù)據(jù)。[來源：HJ929-2017,3.25]3.5WebServiceWebWebWeb服務，構建應用程序。3.6非結構化數(shù)據(jù)unstructureddata不具有預定義模型或未以預定義方式組織的數(shù)據(jù)。[來源：GB/T35295-2017,2.1.25]縮略語HTTP超文本傳輸協(xié)議（HyperTextTransferProtocol）API應用程序編程接口（ApplicationProgrammingInterface）SOAP簡單對象訪問協(xié)議（SimpleObjectAccessProtocol）JSON一種輕量級的數(shù)據(jù)交換格式（JavaScriptObjectNotation）RESTful滿足一組架構約束條件和原則的應用程序或設計（RepresentationalStateTransfer）UDF用戶定義函數(shù)（User-DefinedFunction）MR映射化簡（MapReduce），是一種用于大數(shù)據(jù)并行處理的分布式計算模型、框架和平臺。OpenMI開放式模型界面（OpenModelingInterface），是一種模型連接標準，提供了實現(xiàn)水文、水力、水質、水生態(tài)環(huán)境等不同領域模塊構成集成系統(tǒng)的連接機制，用以解決復雜系統(tǒng)中各計算模塊之間的連接和數(shù)據(jù)交互問題。接口分類與描述格式接口分類流域水環(huán)境管理大數(shù)據(jù)業(yè)務系統(tǒng)的接口包括數(shù)據(jù)接口和服務接口兩類。網(wǎng)采集數(shù)據(jù)接口，水環(huán)境管理業(yè)務相關的結構化和非結構化數(shù)據(jù)接口，以及水模型耦合集成的調用接口。數(shù)據(jù)接口提供數(shù)據(jù)類的支持，主要是指對數(shù)據(jù)的增刪改查。服務接口是功能和數(shù)據(jù)的集合體，主要是完成某一特定功能的運算和展示。接口描述格式接口描述基于如下基本格式：WebService::=<METHOD><ENTRY>[<PARAM>][<HEADER>][<STREAM>]各字段的含義如表1所示。HTTP請求的返回結果包含兩部分：一部分為HTTP消息的狀態(tài)碼(StatusCode)，表示響應的狀態(tài)；另一部分為HTTP請求消息體，消息體采用JSON格式進行封裝。[]為接口中可選項。表1接口描述基本格式說明字段含義<METHOD>HTTP請求方法，本接口中使用到的值有GET，POST，各取值含義參考HTTP協(xié)議。<ENTRY>WEB服務接口的入口地址。<PARAM>可選參數(shù)，用以傳遞少量的參數(shù)信息，例如監(jiān)測點位編碼、時間等。<HEADER>HTTP請求的消息頭部。<STREAM>可選的附加流信息，用以傳遞大量的參數(shù)信息，例如視頻流、圖片等。所有接口定義格式說明如下：接口名：接口的名稱；b）Web服務時的語法格式；語義：對調用格式的解釋；調用結果：Web如無特殊說明，所有Web2HTTP請求頭。表2Web服務接口調用請求說明請求頭Header取值ValueContent-Typeapplication/json;charset=utf-8Acceptapplication/json;charset=utf-8注：表頭的英文是相應的中文的對照，避免引起歧義。物聯(lián)網(wǎng)傳感器數(shù)據(jù)接口物聯(lián)網(wǎng)傳感器接口模型常用的HTTP狀態(tài)碼表示及含義見表3，未列舉狀態(tài)碼的名稱及含義參考HTTP協(xié)議的定義。表3 HTTP狀態(tài)碼表狀態(tài)碼狀態(tài)碼名稱含義200OK請求已成功。201Created對象或資源已成功創(chuàng)建。202Accepted操作已被成功接受。302Found重定向跳轉。400BadRequest請求的內容丟失或不合法。401Unauthorized當前請求需要用戶驗證。404NotFound請求的內容不存在。405MethodNotAllowed客戶端請求中的方法被禁止。409Conflict訪問沖突，訪問資源已被上鎖或可能導致服務器內部狀態(tài)出錯。415UnsupportedMediaType服務器無法處理請求附帶的媒體格式。500InternalServerError服務器出現(xiàn)內部錯誤，無法正確響應請求。503ServiceUnavailable服務器服務暫不可用。GB/T35319727的規(guī)定。BsTable4所示。表4傳感器模型接口規(guī)范序號說明調用格式接口語義調用結果1創(chuàng)建傳感器數(shù)據(jù)模型。POST/BsTable<STREAM>附加流<STREAM>指定該傳感器數(shù)據(jù)模型所涉及的相關信息，包括但不限于：模型名稱、模型標識（模型（一個或多個傳感器的元數(shù)據(jù)信息等，支持JSON格式。HTTP201。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。2更新傳感器數(shù)據(jù)模型，主要修改模型基本信息及相關屬性。PUT/BsTable/{模型ID}<STREAM>更新指定模型ID的傳感器數(shù)據(jù)模型的基本信息、屬性信息等。附加流<STREAM>指定需要更新的傳感器數(shù)據(jù)模型，支持JSON格式。HTTP202。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。3按條件查詢指定的傳感器數(shù)據(jù)模型。GET/BsTable/{模型ID}?select={columns}獲取滿足查詢條件的傳感器數(shù)據(jù)模型。指定模型ID，則查詢指定傳感器數(shù)據(jù)模型；未指定模型ID，則查詢所有傳感器數(shù)據(jù)模型。HTTP200，查詢結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。4向指定傳感器數(shù)據(jù)模型添加新的傳感器相關信息。PUT/BsTable/addfield/{模型ID}<STREAM>向指定的傳感器數(shù)據(jù)模型增加傳感器相關信息。附加流<STREAM>指格式。HTTP201。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。5修改指定傳感器數(shù)據(jù)模型中的傳感器的相關信息。PUT/BsTable/{模型ID}/fields/{傳感器ID}<STREAM>修改指定傳感器數(shù)據(jù)模型中指定傳感器ID的相關信息。附加流<STREAM>指定需要修改的傳感器，支持JSON格式。HTTP202。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。6刪除指定傳感器數(shù)據(jù)模型中的某個傳感器的相關信息。DELETE/BsTable/ID}/fields/傳感器ID}當傳感器數(shù)據(jù)模型中某個傳感器失效或者不需要時，可以刪除指定傳感器的相關信息。HTTP200。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。物聯(lián)網(wǎng)傳感器數(shù)據(jù)實時接入接口根據(jù)物聯(lián)網(wǎng)傳感器所處的物理位置和網(wǎng)絡環(huán)境，本文件規(guī)定了3種接口及要求，如表5所示。表5物聯(lián)網(wǎng)數(shù)據(jù)實時接入接口規(guī)范序號接入形式說明調用格式接口語義調用結果1Web服務接口提供RESTful接口實時接入傳感器數(shù)據(jù)。POSTs/data<STREAM>面向傳感器數(shù)據(jù)模型實時接入傳感器數(shù)據(jù)。附加流<STREAM>指定傳感器，支持JSON格式，應在HTTP請求的Content-Type中指定。成功狀態(tài)：返回的HTTP狀態(tài)碼為202。失敗狀態(tài)：返回的HTTP狀態(tài)碼為503。2消息隊列服務接口提供消息隊列服務接口實時接入傳感器數(shù)據(jù)。用戶通過調用消息隊列服務接口將數(shù)據(jù)寫入平臺。寫入數(shù)據(jù)格式支持JSON數(shù)據(jù)和二進制數(shù)據(jù)。POST/time-series-queue<STREAM>將某個時間點的若干傳感器數(shù)據(jù)通過消息隊列服務接口寫入平臺。其中，寫入JSON<STREAM>中應包括傳感器數(shù)據(jù)所屬的傳感器ID)、傳感器數(shù)據(jù)產生的的值等信息。HTTP狀態(tài)碼為。HTTP狀態(tài)碼為。3編程接口將數(shù)據(jù)轉化成平臺能夠識別的傳感器數(shù)據(jù)記錄。--參考返回狀態(tài)碼表。物聯(lián)網(wǎng)傳感器數(shù)據(jù)批量導入接口通過RESTful架構導入文件時，導入文件應符合下列要求：文件編碼為UTF-8；文件為CSV格式（以單豎線作為列分隔符，回車作為行分隔符）；一行一條數(shù)據(jù)記錄；數(shù)據(jù)涉及的傳感器數(shù)據(jù)模型需在平臺中完成注冊；每條數(shù)據(jù)記錄中數(shù)據(jù)列數(shù)應與傳感器數(shù)據(jù)模型定義的傳感器相同且取值一一對應。6所示。表6傳感器數(shù)據(jù)批量導入接口序號接口說明調用格式接口語義調用結果1新建導入任務POST/workflows<STREAM>新建批量導入任務。附加流<STREAM>務相關的信息，包括但不限于要導入的文件標識等，支持JSON格式。成功狀態(tài)：返回的HTTP狀態(tài)碼為201，生成任務ID，結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。表6傳感器數(shù)據(jù)批量導入接口（續(xù)）序號接口說明調用格式接口語義調用結果2上傳傳感器數(shù)據(jù)文件POST/workflows/file-Upload將需要導入的文件上傳到平臺。成功狀態(tài)：返回的HTTP狀態(tài)碼為201，結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。3獲取導入任務列表GET/workflows獲取正在執(zhí)行的和已經(jīng)執(zhí)行完成的批量導入任務列表。成功狀態(tài)：返回的HTTP狀態(tài)碼為200，查詢結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。4獲取任務詳情GET/workflows/{任務ID}根據(jù)任務ID查看導入任務的相關信息，包括任務報告。成功狀態(tài)：返回狀態(tài)碼200，返回結果采用JS0N狀態(tài)碼及采用JSON封裝的響應結果。5獲取單個任務狀態(tài)GET/workflows/status/{任務ID}根據(jù)任務ID查詢某個任務狀態(tài)。成功狀態(tài)：返回HTTP狀態(tài)碼200，返回結果采用JSON封裝，任務狀態(tài)信息。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。物聯(lián)網(wǎng)傳感器數(shù)據(jù)查詢接口7所示。表7傳感器數(shù)據(jù)查詢接口序號查詢類型查詢說明調用格式接口語義調用結果1數(shù)據(jù)流查詢提供數(shù)據(jù)流查詢接口查詢傳感器數(shù)POSTdata-streams<STREAM>GET/data-streams?query=<STREAM>取滿足條件的傳感器指定頁、可排序。成功狀態(tài)：返回的HTTP狀態(tài)碼為200，查詢結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。表7傳感器數(shù)據(jù)查詢接口（續(xù)）序號查詢類型查詢說明調用格式接口語義調用結果2數(shù)據(jù)行查詢提供數(shù)據(jù)行查詢接口查詢傳感器數(shù)POST/data-rows<STREAM>GET/data-rows?query=<STREAM>取滿足條件的傳感器指定頁、可排序。成功狀態(tài)：返回的HTTP狀態(tài)碼為200，查詢結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。3數(shù)據(jù)點查詢提供數(shù)據(jù)點查詢接口查詢傳感器數(shù)也可適用于傳感器流模型。POST/data-points<STREAM>GET/data-points?query=<STREAM>取滿足條件的傳感器定每頁數(shù)量、可指定頁、可排序。成功狀態(tài)：返回的HTTP狀態(tài)碼為200，查詢結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。4數(shù)據(jù)聚合查詢提供數(shù)據(jù)聚合查詢接口查詢傳感器在點查詢返回的結果集基礎上再做聚合。POST/data-aggregation<STREAM>GET/data-aggregation?query=<STREAM>根據(jù)<STREAM>指定滿足條件的傳感器數(shù)<STREAM>包括但不限于數(shù)據(jù)過濾條件、需要聚合的傳感器ID、聚合類型（最大值、最小值、平均值等）；支持對多個傳感器做不同類型的聚合查詢。成功狀態(tài)：返回的HTTP狀態(tài)碼為200；查詢結果采用JSON封裝。失敗狀態(tài)：返回失敗對應的HTTP狀態(tài)碼及采用JSON封裝的響應結果。結構化數(shù)據(jù)接口流域水環(huán)境管理大數(shù)據(jù)業(yè)務系統(tǒng)結構化數(shù)據(jù)接口參照HJ719的規(guī)定執(zhí)行。非結構化數(shù)據(jù)類接口創(chuàng)建非結構化類型的數(shù)據(jù)模型附加流<STREAM>指定該類型數(shù)據(jù)所涉及的相關信息，包括但不限于對象類型名稱、屬性列表。接口服務功能應當包括但不限于創(chuàng)建、修改、刪除、查詢、搜索和導出。接口返回狀態(tài)應參考表3。流域水環(huán)境模型接口接口框架1所示。輸出數(shù)據(jù)輸出數(shù)據(jù)模型輸入數(shù)據(jù)圖1模型與數(shù)據(jù)源數(shù)據(jù)關系集數(shù)據(jù)源信息數(shù)據(jù)源與模型間數(shù)據(jù)關系集2數(shù)據(jù)關系集數(shù)據(jù)源信息數(shù)據(jù)源與模型間數(shù)據(jù)關系集模型輸入輸出數(shù)據(jù)項集模型輸入輸出數(shù)據(jù)項集模型數(shù)據(jù)接口要素集輸出數(shù)據(jù)項集參數(shù)集輸入數(shù)據(jù)項集圖輸出數(shù)據(jù)項集參數(shù)集輸入數(shù)據(jù)項集模型與平臺接口模型輸入輸出數(shù)據(jù)項集描述如表8所示。表8模型數(shù)據(jù)項集序號中文名稱英文名稱縮寫名定義數(shù)據(jù)類型約束/條件1模型數(shù)據(jù)接口要素集合ModelDataInterfaceElementSetMDIElementSet定義流域水環(huán)境模型數(shù)據(jù)接口描述要素的根實體。類M2模型標識符Identifierid據(jù)信息中所給出的標識符一致。字符串M表8模型數(shù)據(jù)項集（續(xù)）序號中文名稱英文名稱縮寫名定義數(shù)據(jù)類型約束/條件3模型輸入數(shù)據(jù)項個數(shù)InputItemCountinputItemCount對模型輸入數(shù)據(jù)項個數(shù)的說明。整型M4模型輸入數(shù)據(jù)項InputIteminputItem對流域水環(huán)境模型需要的每個輸入數(shù)據(jù)項的說明。類M5模型參數(shù)個數(shù)ParameterCountparamCount對模型所需要的每個參數(shù)的說明。整型M6模型參數(shù)Pamameterpamam對流域水環(huán)境模型所需要的每個參數(shù)的說明。類C模型參數(shù)個數(shù)>0時必選。7模型輸出數(shù)據(jù)項個數(shù)OutputItemCountoutputItemCou