用戶(hù)端能源管理系統(tǒng) 第5部分：應(yīng)用側(cè)接口規(guī)范 征求意見(jiàn)稿

GB/TXXXXX—XXXX1用戶(hù)端能源管理系統(tǒng)第5部分：應(yīng)用側(cè)接口規(guī)范本文件適用于用戶(hù)端能源管理系統(tǒng)應(yīng)用側(cè)應(yīng)用程序接GB/T35031.1—2018用GB/T35031.2—2018用戶(hù)端能源管理系統(tǒng)第2部分：主站功GB/T35031.302-2022用戶(hù)端能源管理系統(tǒng)第3-2部分：子系統(tǒng)接口網(wǎng)關(guān)數(shù)據(jù)配置GB/T35031.4-2022用戶(hù)端能源管理系統(tǒng)第4部分：主站與網(wǎng)關(guān)信息交互規(guī)范GB/T35031.6-2019用戶(hù)端能源管理系統(tǒng)第6部分：管理指標(biāo)GB/Z32500-2016智能電網(wǎng)用戶(hù)端系統(tǒng)數(shù)據(jù)接口一般要求RFC6749TheOAuth2.0AuthorizationFramework（OAuth2.GB/Z32500—2016、GB/T35031.1—2018、GB/T35031.2—2018、GB/T35031.302-2022、GB/T注1：Cems用于表示CEMS系統(tǒng)中的一個(gè)核心對(duì)象，即CEMS的一個(gè)具體實(shí)例。在APGB/TXXXXX—XXXX2根據(jù)功能、用途、技術(shù)特性或應(yīng)用場(chǎng)景等共同特征，將多個(gè)設(shè)備進(jìn)行歸類(lèi)和分組的一種API：應(yīng)用程序編程接口（applicationprogramminginterface）CEMS：用戶(hù)端能源管理系統(tǒng)（customerenergymanagementsystem）DR：需求響應(yīng)（demandresponse）EMS：能源管理系統(tǒng)（energymanagementsystem）HTTP：超文本傳輸協(xié)議（hypertexttransferprotocol）HTTPS：基于安全套接字層的超文本傳輸協(xié)議（hypertexttransferprotocoloversecuresocketlayer）OAuth2.0：開(kāi)放授權(quán)2.0（openauthorization2.0）URL：統(tǒng)一資源定位符（uniformresourcelocator）35031.1—2018中定義的能源供應(yīng)商EMS、能源服務(wù)商EMS，這里統(tǒng)稱(chēng)為能源服務(wù)平臺(tái)。本文件定義的應(yīng)用程序接口（API），適用于能源服務(wù)平臺(tái)向CEMS主站查詢(xún)和調(diào)用數(shù)據(jù)。CEMS主站儲(chǔ)和管理用戶(hù)端的能源數(shù)據(jù)，并提供數(shù)據(jù)查GB/TXXXXX—XXXX3a）靜態(tài)基本信息接口的GB/TXXXXX—XXXX44.2數(shù)據(jù)交互流程b)CEMS主站驗(yàn)證請(qǐng)求的合法性（如身份驗(yàn)證、權(quán)限檢4.3數(shù)據(jù)提供范圍a)靜態(tài)基本信息：包括用戶(hù)端（Cems）、接入點(diǎn)（Point）和設(shè)備類(lèi)（Category）的基礎(chǔ)信息，b)動(dòng)態(tài)實(shí)時(shí)信息：包括用戶(hù)端、接入點(diǎn)和設(shè)備類(lèi)的實(shí)時(shí)狀態(tài)數(shù)據(jù)，如當(dāng)前c)過(guò)往歷史信息：過(guò)往歷史信息：包括用戶(hù)端、接入點(diǎn)和設(shè)備類(lèi)在過(guò)去不同時(shí)間節(jié)點(diǎn)及時(shí)間段d)匯總統(tǒng)計(jì)信息：包括用戶(hù)端、接入點(diǎn)和設(shè)備類(lèi)的統(tǒng)計(jì)信息b)請(qǐng)求和響應(yīng)的數(shù)據(jù)傳輸格式均為JSON。5.2請(qǐng)求頭AuthorizationContent-Type:appliAuthorization:BearereyJhbGciOiJIUzI1NiIAccept:applicationGB/TXXXXX—XXXX5POST/api/cems/v1/getpointstaticdata對(duì)于成功響應(yīng)（200響應(yīng)體中應(yīng)包含code和data字段，其中data字段為具體的業(yè)務(wù)數(shù)據(jù)。），b)訪(fǎng)問(wèn)令牌（Token）：客戶(hù)端每次請(qǐng)求應(yīng)攜帶有c)防火墻安全配置：服務(wù)端應(yīng)配置防火d)訪(fǎng)問(wèn)日志：服務(wù)端應(yīng)記錄所有接口訪(fǎng)問(wèn)日志，便于審計(jì)和問(wèn)題排查。GB/TXXXXX—XXXX65.6可擴(kuò)展性說(shuō)明版本升級(jí)時(shí)，舊版本接口應(yīng)至少保留6個(gè)月的兼容期。b)模塊化設(shè)計(jì)：接口按功能模塊劃分（如靜態(tài)數(shù)據(jù)類(lèi)接口、動(dòng)態(tài)實(shí)時(shí)類(lèi)接口等便于未來(lái)功基本信息模型（Basic）定義了CEMS中核心數(shù)據(jù)對(duì)象的結(jié)構(gòu)和關(guān)系，涵蓋了用戶(hù)端（Cems）、接入點(diǎn)（Point）、設(shè)備類(lèi)（Category）等關(guān)鍵實(shí)體。該模型為系統(tǒng)提供了標(biāo)準(zhǔn)化的數(shù)據(jù)表示方式，確保GB/TXXXXX—XXXX7備進(jìn)行統(tǒng)一管理和監(jiān)控，便于能源消耗的分析和優(yōu)化。Category參數(shù)定義12 345maxPowerTotal6789運(yùn)行狀態(tài)：generation（發(fā)電）、consumpCems（用戶(hù)端）是用戶(hù)端能源管理系統(tǒng)的核心對(duì)象，用于描述和管理用戶(hù)端的基本信息。Cems對(duì)的所有接入點(diǎn)（Point）。Cems對(duì)象為用戶(hù)端系統(tǒng)的數(shù)據(jù)采集和統(tǒng)計(jì)分析提供了基礎(chǔ)數(shù)據(jù)支持。Cems參1234567GB/TXXXXX—XXXX812DynamicData是用于描述用戶(hù)端能源管理系統(tǒng)中動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)的對(duì)象，包含實(shí)時(shí)采集的參數(shù)列表及其相關(guān)讀數(shù)。DynamicData參數(shù)定義16.5HistoricData（歷史數(shù)據(jù)）關(guān)讀數(shù)。HistoricData參數(shù)定義同HistoricD6.6Page（分頁(yè)信息）Page是用于支持分頁(yè)查詢(xún)的輔助對(duì)象，主要用于指定查詢(xún)結(jié)果的頁(yè)碼和每頁(yè)顯象在接口請(qǐng)求和響應(yīng)中使用，支持調(diào)用方實(shí)現(xiàn)分頁(yè)查詢(xún)功能。Pa12讀數(shù)列表等信息，為系統(tǒng)提供統(tǒng)一的計(jì)量參數(shù)表示方式。Parameter參數(shù)定義12GB/TXXXXX—XXXX9345Point是用于描述用戶(hù)端電氣設(shè)備與配電網(wǎng)絡(luò)相連12345678Reading是用于描述參數(shù)讀數(shù)的對(duì)象，記錄參數(shù)在特定時(shí)間點(diǎn)的值。該對(duì)象通常與Parameter對(duì)象結(jié)合使用，用于記錄和展示能源管理系統(tǒng)中的實(shí)時(shí)數(shù)據(jù)或歷史數(shù)據(jù)。ReadingGB/TXXXXX—XXXX1格式為“yyyy-mm-ddThh:mm）；2SimpleCategory是用于簡(jiǎn)約描述設(shè)備類(lèi)別的動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)的對(duì)象，包含設(shè)備類(lèi)ID、名稱(chēng)以及相關(guān)1231236.12SimpleStatisticPoint（簡(jiǎn)約統(tǒng)計(jì)接入點(diǎn)）SimpleStatisticPoint是用于簡(jiǎn)約描述接入點(diǎn)的統(tǒng)計(jì)數(shù)據(jù)的對(duì)象，包含接入點(diǎn)I12GB/TXXXXX—XXXX3信息，如用戶(hù)端的基本信息、接入點(diǎn)的配置信息、設(shè)備類(lèi)別的定義等。StaticData參數(shù)定123StatisticData是用于描述統(tǒng)計(jì)數(shù)據(jù)的對(duì)象，包含統(tǒng)計(jì)ID、統(tǒng)計(jì)范圍、統(tǒng)計(jì)指標(biāo)類(lèi)、統(tǒng)計(jì)指標(biāo)項(xiàng)、123456789monthGB/TXXXXX—XXXX7.1GetCemsStaticData（獲取用戶(hù)端靜態(tài)數(shù)獲取用戶(hù)端能源管理系統(tǒng)（Cems）的靜態(tài)基本數(shù)據(jù)，包括CemsID、名稱(chēng)、地址、聯(lián)系電話(huà)GetCemsStaticData響應(yīng)參數(shù)定義123457.2GetCemsFullStaticData（獲取用戶(hù)端完整的靜態(tài)數(shù)據(jù)）獲取用戶(hù)端完整數(shù)據(jù)，包括系統(tǒng)基本信息、所關(guān)聯(lián)的所有接入點(diǎn)（Point）信息以及每個(gè)接入點(diǎn)所連接設(shè)備類(lèi)（Category）的詳細(xì)信息。GetCemsFullStaticData請(qǐng)求參數(shù)定1GetCemsFullStaticData響應(yīng)參數(shù)定127.3GetCemsSpecCategoryStaticData（獲取用戶(hù)端特定設(shè)備類(lèi)的靜態(tài)數(shù)據(jù)）獲取用戶(hù)端能源管理系統(tǒng)中特定設(shè)備類(lèi)別（由categoryIDGetCemsSpecCategoryStaticData請(qǐng)求參1GetCemsSpecCategoryStaticData響應(yīng)參17.4GetPointStaticData（獲取接入點(diǎn)靜態(tài)數(shù)據(jù)）GetPointStaticData請(qǐng)求參數(shù)定義見(jiàn)表21GetPointStaticData響應(yīng)參數(shù)定義見(jiàn)表212345677.5GetPointFullStaticData（獲取接入點(diǎn)完整的靜態(tài)數(shù)據(jù)）GB/TXXXXX—XXXX獲取指定接入點(diǎn)（由pointID指定）的完整靜態(tài)數(shù)據(jù)，包括接入點(diǎn)自身的基本信息以及其所關(guān)聯(lián)GetPointFullStaticData請(qǐng)求參數(shù)定義見(jiàn)表212GetPointFullStaticData響應(yīng)參數(shù)定義見(jiàn)表2127.6GetPointSpecCategoryStaticData（獲取接入點(diǎn)特定設(shè)備類(lèi)的靜態(tài)數(shù)據(jù)）GB/TXXXXX—XXXX獲取用戶(hù)端能源管理系統(tǒng)中特定接入點(diǎn)（由pointID指定）下特定設(shè)備類(lèi)（由categoryIGetPointSpecCategoryStaticData請(qǐng)求參數(shù)表25GetPointSpecCa123GetPointSpecCategoryStaticData響應(yīng)參數(shù)同GetCemsSpecCategoryStaticData響應(yīng)參數(shù)，詳見(jiàn)表12GB/TXXXXX—XXXX8.1.1功能GetCemsDynamicData請(qǐng)求參數(shù)同GetCemsFullStaticData請(qǐng)求參數(shù)，詳見(jiàn)表GetCemsDynamicData響應(yīng)參數(shù)定義見(jiàn)表2128.2GetCemsFullDynamicData（獲取用戶(hù)端完整的動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)）8.2.1功能GB/TXXXXX—XXXXGetCemsFullDynamicData請(qǐng)求參數(shù)同GetCemsFullStaticData請(qǐng)求參數(shù)，詳見(jiàn)表GetCemsFullDynamicData響應(yīng)參數(shù)定義見(jiàn)表2128.3GetCemsSpecCategoryDynamicData（獲取用戶(hù)端特定設(shè)備類(lèi)的動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)）8.3.1功能GB/TXXXXX—XXXXGetCemsSpecCategoryDynamicData請(qǐng)求參數(shù)表29GetCemsSpecCat12GetCemsSpecCategoryDynamicData響應(yīng)參數(shù)1238.4GetPointDynamicData（獲取接入點(diǎn)動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)）8.4.1功能獲取接入點(diǎn)動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)，包括接入點(diǎn)ID、參數(shù)列表及其相關(guān)數(shù)據(jù)。支GetPointDynamicData請(qǐng)求參數(shù)同GetPointFullStaticData請(qǐng)求參數(shù)GetPointDynamicData響應(yīng)參數(shù)定義見(jiàn)1238.5GetPointFullDynamicData（獲取接入點(diǎn)完整的動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)）8.5.1功能GetPointFullDynamicData請(qǐng)求參數(shù)同GetPointFullStaticData請(qǐng)求參數(shù)，GetPointFullDynamicData響應(yīng)參數(shù)定義見(jiàn)123GB/TXXXXX—XXXX8.6GetPointSpecCategoryDynamicData（獲取接入點(diǎn)特定設(shè)備類(lèi)的動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)）8.6.1功能GetPointSpecCategoryDynamicData請(qǐng)求參數(shù)同GetPointSpecCategoryStaticData請(qǐng)求參數(shù)，詳見(jiàn)GetPointSpecCategoryDynamicData響應(yīng)參數(shù)定義見(jiàn)12349歷史數(shù)據(jù)信息接口9.1GetCemsHistoricData（獲取用戶(hù)端歷史數(shù)據(jù)）9.1.1功能GB/TXXXXX—XXXX9.1.3請(qǐng)求參數(shù)GetCemsHistoricData請(qǐng)求參數(shù)定義見(jiàn)1239.2GetCemGetCemsFullHistoricData（獲取用戶(hù)端完整的歷史數(shù)據(jù)）9.2.1功能GB/TXXXXX—XXXX9.2.3請(qǐng)求參數(shù)GetCemsFullHistoricData請(qǐng)求參數(shù)同GetCemsHistoricData請(qǐng)求參GetCemsFullHistoricData響應(yīng)參數(shù)同GetCemsFullDynamicData響應(yīng)參數(shù)，9.3GetCemsSpecCategoryHistoricData（獲取用戶(hù)端特定設(shè)備類(lèi)的歷史數(shù)據(jù)）9.3.1功能9.3.3請(qǐng)求參數(shù)GetCemsSpecCategoryHistoricData請(qǐng)求參數(shù)定義見(jiàn)表35GetCemsSpecCategor1234GetCemsSpecCategoryHistoricData響應(yīng)參數(shù)同GetCemsSpecCategoryDynamicData響應(yīng)參數(shù)，詳見(jiàn)9.4GetPointHistoricData（獲取接入點(diǎn)歷史數(shù)據(jù)）GB/TXXXXX—XXXX9.4.1功能9.4.3請(qǐng)求參數(shù)GetPointHistoricData請(qǐng)求參數(shù)定義見(jiàn)1234GetPointHistoricData響應(yīng)參數(shù)同GetPointDynamicData響應(yīng)參數(shù)，詳見(jiàn)表9.5GetPointFullHistoricData（獲取接入點(diǎn)完整的歷史數(shù)據(jù)）9.5.1功能GB/TXXXXX—XXXX9.5.3請(qǐng)求參數(shù)GetPointFullHistoricData請(qǐng)求參數(shù)同GetPointHistoricData請(qǐng)求參數(shù)，詳GetPointFullHistoricData響應(yīng)9.6GetPointSpecCategoryHistoricData（獲取接入點(diǎn)特定設(shè)備類(lèi)的歷史數(shù)據(jù)）9.6.1功能圖20GetPointSpecCa9.6.3請(qǐng)求參數(shù)GetPointSpecCategoryHistoricData請(qǐng)求參數(shù)定GB/TXXXXX—XXXX表37GetPointSpecCategory12345GetPointSpecCategoryHistoricData響應(yīng)參數(shù)同GetPointSpecCategoryDynamicD10.1GetCemsStatisticData（獲取用戶(hù)端統(tǒng)計(jì)數(shù)據(jù)）GetCemsStatisticData請(qǐng)求參數(shù)定義見(jiàn)1234GetCemsStatisticData響應(yīng)參數(shù)定義見(jiàn)1210.2GetCemsFullStatisticData（獲取用戶(hù)端完GetCemsFullStatisticData請(qǐng)求參數(shù)同GetCemsStatisticData請(qǐng)求參數(shù)，詳GetCemsFullStatisticData響應(yīng)參數(shù)定GB/TXXXXX—XXXX1List<SimpleStatisticPo210.3GetCemsSpecCategoryStatisticData（獲取用戶(hù)端特定設(shè)備類(lèi)的統(tǒng)計(jì)GetCemsSpecCategoryStatisticData請(qǐng)求參數(shù)定表41GetCemsSpecCategoryS1234GB/TXXXXX—XXXX567GetCemsSpecCategoryStatisticData響應(yīng)參數(shù)定123410.4GetPointStatisticData（獲取接入點(diǎn)統(tǒng)計(jì)數(shù)據(jù)）GetPointStatisticData請(qǐng)求參數(shù)定義GB/TXXXXX—XXXX12345GetPointStatisticData響應(yīng)參數(shù)定義12310.5GetPointFullStatisticData（獲取接入點(diǎn)完整的統(tǒng)計(jì)數(shù)據(jù)）GB/TXXXXX—XXXXGetPointFullStatisticData請(qǐng)求參數(shù)同GetPointStatisticData請(qǐng)求參數(shù)，詳見(jiàn)GetPointFullStatisticData響應(yīng)參數(shù)同GetPointStatisticData響應(yīng)參數(shù)，詳見(jiàn)10.6GetPointSpecCategoryStatisticcData（獲取接入點(diǎn)特定設(shè)備類(lèi)的統(tǒng)計(jì)數(shù)據(jù)）GetPointSpecCategoryStatisticcData請(qǐng)求參數(shù)定義表45GetPointSpecCatego12345GB/TXXXXX—XXXXGetPointSpecCategoryStatisticcDataGB/TXXXXX—XXXXA.1概述DrDeclaration參數(shù)定義見(jiàn)表A1234123456DrDynamicData參數(shù)定義見(jiàn)表A123maxLoad45margin67DrHistoricData參數(shù)定義見(jiàn)表A1234567GB/TXXXXX—XXXX89DR事件記錄時(shí)間。格式同Reading的12345modificationTimeA.3.1GetCemsDrResourceStaticData（獲取用A.3.1.1功能獲取用戶(hù)端能源管理系統(tǒng)中與需求響應(yīng)相關(guān)的靜態(tài)數(shù)據(jù)，包括DR資源的類(lèi)型、可減少負(fù)荷、可上GB/TXXXXX—XXXXGetCemsDrStaticData響應(yīng)參數(shù)定義12A.3.2GetCemsDrDynamicData（獲取用戶(hù)端A.3.2.1功能獲取用戶(hù)端能源管理系統(tǒng)中與需求響應(yīng)執(zhí)行相關(guān)的動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)，包括DR事件的實(shí)時(shí)狀態(tài)、負(fù)荷GB/TXXXXX—XXXXGetCemsDrDynamicData響應(yīng)參數(shù)定義見(jiàn)表A1A.3.3GetCemsDrHistoricData（獲取用戶(hù)端DR執(zhí)行歷史數(shù)A.3.3.1功能GetCemsDrHistoricData請(qǐng)求參數(shù)定義見(jiàn)123GetCemsDrHistoricData響應(yīng)參數(shù)定義見(jiàn)121234month5DemandDynamicData參數(shù)定義見(jiàn)表B123456B.2.4DemandHistoric（需DemandHistoric參數(shù)定義見(jiàn)表B1monthMaxDemand23monthDemandLoadRate6789monthB.3.1GetCemsDemandStatGB/TXXXXX—XXXXGetCemsDemandStaticData響應(yīng)參數(shù)定義1B.3.2GetCemsDemandDynamiGetCemsDemandDynamicData響應(yīng)參數(shù)定義見(jiàn)1Object<DemandDynamicB.3.3GetCemsDemandHisGB/TXXXXX—XXXXGetCemsDemandHistoricData請(qǐng)求參數(shù)同GetCemsDrHistoricData請(qǐng)求參數(shù)，詳見(jiàn)GetCemsDemandHistoricData響應(yīng)參數(shù)定義見(jiàn)12GB/TXXXXX—XXXX本附錄提供了CEMS應(yīng)用側(cè)接口的規(guī)范性示例，展示如何通過(guò)API接口些示例涵蓋CEMS靜態(tài)數(shù)據(jù)、動(dòng)態(tài)實(shí)時(shí)數(shù)據(jù)、統(tǒng)計(jì)數(shù)據(jù)和需求響應(yīng)數(shù)據(jù)等主要數(shù)POST/api/cems/v1/getcemsfullstaticdata{"Content-Type":"app"Authorization":"BearereyJhbGciOiJIUzI1NiIsInR5cCI6}{}{"cemsID":"CEMS001",//"cemsName":"用戶(hù)端能源管理系統(tǒng)1","address":"北京市朝陽(yáng)區(qū)XX路XX{"location":"北京市朝陽(yáng)區(qū)XX路"powerFactorStandard":0.9"contractCapacity":800,//合{"categoryName":"生產(chǎn)]}}}POST/api/cems/v1/getcemsspeccategorydynamicdata{"Content-Type":"app"Authorization":"BearereyJhbGciOiJIUzI1NiIsInR5cCI6Ik}{"categoryID":"CAT00}{{"parameterName":"當(dāng)前{"time":"2024-03-15T14:30:0]{"parameterName":"當(dāng)天最大{"time":"2024-03-15T10:30:0]}}}POST/api/cems/v1/getcemsspeccategorystatisticdata{"Content-Type":"app"Authorization":"BearereyJhbGciOiJIUzI1NiIsInR5cCI6Ik}{"startTime":"2024-01-01T00:00:00Z","endTime":"2024-12-31T23:59:59Z","statisticCategory":"能效統(tǒng)計(jì)}{{"statisticCategory":"能效統(tǒng)計(jì)管理指"statisticItem":"單位產(chǎn)值"statisticValue":0.5,//單位產(chǎn)值能耗值"statisticTime":"2024-12-31T23:59:59Z""remarks":"2024年單位產(chǎn)值能]}}POST/api/cems/v1/getcemsspeccategorystatisticdata{"Content-Type":"app"Authorization":"BearereyJhbGciOiJIUzI1NiIsInR5cCI6Ik}{"startTime":"2024-04-01T00:00:00Z","endTime":"2024-05-31T23:59:59Z","granularity":"month","statisticCategory":"峰平谷尖用電量管理指"statisticItem":"峰時(shí)段用電量比}{{"statisticCategory":"峰平谷尖用電量管理指標(biāo)""statisticItem":"峰時(shí)段用電"statisticValue":35,"statisticTime":"2024-04-30T23:59:59Z","remarks":"2024年4月空調(diào)與通風(fēng)峰峰時(shí)段能耗統(tǒng)計(jì)"{"statisticCategory":"峰平谷尖用電量管理指標(biāo)""statisticItem":"峰時(shí)段用電GB/TXXXXX—XXXX"statisticTime":"2024-05-31T23:59:59Z","remarks":"2024年5月空調(diào)與通風(fēng)峰時(shí)段能耗統(tǒng)}}}POST/api/cems/v1/getdrhistoricdata{"Content-Type":"app"Authorization":"BearereyJhbGciOiJIUzI1NiIsInR5cCI6Ik}{"startTime":"2024-01-01T00:00:00Z","endTime":"2024-12-31T23:59:59Z",}{{"drStart