CMe3100 REST API Plugin

Inledning

Detta dokument beskriver Elvaco Rest API och interaktioner inom resurser som tillhandahålls av CMe3100-produkten. Elvaco Rest API ger åtkomst till resurser (dataenheter) via URL-vägar. Alla åtgärder via API görs med hjälp av vanliga HTTP-metoder GET, POST, PUT och DELETE. Standard HTTP-svarskoder som används för att indikera framgång och feltillstånd.

Begärd data hittas som JSON, och svarsdata returneras som JSON.

Statusobjekt som JSON returnerar när en operation utförs utan att returnera resultatentitet.

{

status: Statustext

}

Statustext: Record(s) not found / Parameter(s) not found / Success/ Error

HTTP-statuskoder: 404 Not found / 404 Not found / 201 Created / 400 Bad request

Tips

Elvacos webbgränssnitt har ett testområde för REST API-konfigurationer. Gå till Konfiguration och klicka på Tjänster>REST>HJÄLP>Testa för att komma in i testområdet.

Tjänster

Lista över tjänster

Använd följande tabell för att ta reda på resurserna för Elvaco Rest API.

Tabell 127. Lista över Rest API-resurser

Tjänster

Beskrivning

/config

Konfigureringstjänster CMe3100, det vill säga byte av TCP-konsolport, inställning av e-postserver etc.

/console

Tjänst för att utföra konsolkommandon. d.v.s. exekvera ett konsolkommando för att begära tillfälliga rapporter via e-post.

/datatable

Tjänst för att nå permanent datatabell inom systemet.

/dbtranslations

Tjänst för att fastställa databasöversättningar, d.v.s. lägga till/uppdatera nya översättningar till databasen.

/device

Service för hantering av enheter, det vill säga M-Busslavar.

/deviceType

Tjänst för bestämning av enhetstyper, det vill säga el, gas, detektor, rökdetektor mm.

/encryptionkey

Tjänst för bestämning av krypteringsnycklar för M-Busslavar.

/log

Tjänst för att övervaka logginformation för olika allvarlighetsgrad, det vill säga -2 (Debug), -1 (Okänd), 0 (Info), 1 (Varning), 2 (Fel), 3 (Kritisk), 4 (Farlig), 5 (Undantag), 6 (Händelse).

/mdmdata

Tjänst för att läsa historiska eller momentana data från olika källor.

/mdmserie

Tjänst för normaliserade värden/mätardata från enheter.

/mdmseriestemplates

/mdmsource

Tjänst för hantering av datakälla för mdmseries, det vill säga M-Bus, funktioner etc.

/mdmtag

Tjänst för att bestämma taggar med tillhörande mätserier.

/operations for unit types

/system

/unit

Tjänst för att bestämma enheter för mätaråtgärder, det vill säga kW, GJ/h, minut(er), dag(ar) mm.

/user

Tjänst för att fastställa användare och deras autentiseringsrättigheter.

/userlink

Tjänst för att fastställa användarlänkar som har lagts till av användaren.

/viewmdmdata

Tjänst för enklare enhet som kombinerar mdmdata främmande nyckel med läsbar data.

/viewmdmserie

Tjänst för enklare enhet som kombinerar mdmseries främmande nyckel till läsbar data.

Användning av tjänster

Elvaco Rest API är baserat på öppna standarder, vilket webbspråk som helst kan användas för att komma åt API. För att använda Elvaco Rest API bör applikationen göra HTTP-begäran och analysera svaret. Grundläggande autentisering krävs.

Bas-URL: http://yourserver:port /Elvaco-Rest/rest

REST-tjänster

Få åtkomst till mätardata

Data som läses från enheter normaliseras i mätserier. Huvuddelarna i mätserierna är källa, data och serier.

Källa

Källan för en mätserie definierar källan till data, vilket kan vara ett specifikt värde som läses från en M-Busslav. Källan kan också användas för att definiera matematiska funktioner för att beräkna data från en eller flera mätserier. En mätserie kan endast ha en aktiv källa

Serie

Serien definierar hur data från källan publiceras till användaren eller annat gränssnitt.

Data

Mätseriens data innehåller information om mätseriens data. Genom användning av modulen; om data är numeriska tillhör data den mätserie och datakälla etc. som kan övervakas.

Exempel

I det här avsnittet demonstrerar vi ett användningsfall för att visa hur man använder Elvaco Rest API. Nedan är stegen i scenariot och exempel på svar och förfrågningar.

Användaren vill lista alla mätserier i systemet.

Begäran

HTTP GET /Elvaco-Rest/rest/mdmserie/all

Svar

[

{

"storageIntervalCron":"",

"updateIntervalCron":"",

"unitTypeID": 134,

"updateOnNewData": false,

"description": "Signal strenght in dBm",

"expireTimeout": 0,

"name": "Signal strenght",

"measurementSerieId": 241,

"unitId": 58,

"apiIdentifier": "61000002-mbus.dib.rf-level.0.0.0.0"

"deviceTypeId": "2",

"calculationOrder": "0",

"createdFromTemplateId": "9",

"unitTypeId": 0,

"priority": "1",

}

{

"storageIntervalCron": "",

"updateIntervalCron": "",

"unitTypeId": 167,

"updateOnNewData": false,

"description": "Indoor temperature",

"expireTimeout": 0,

"name": "Temperature",

"measurementSerieId": 242,

"unitId": 13,

"apiIdentifier": "61000002-mbus.dib.ext-temp.0.0.0.0"

"deviceTypeId": "2",

"calculationOrder": "0",

"createdFromTemplateId": "5",

"unitTypeId": 5,

"priority": "1",

},

{

...

}

]

Efter att mätserieinformationen har listats kan användaren använda mätserie-id för att bestämma mätseriekällan.

Användaren vill få källan till mätserien.

För att kunna få källinformationen till en mätserie måste förfrågan med mätserie-id som parameter begäras.

Begäran

HTTP GET /Elvaco-Rest/rest/mdmsource/measurementSerieId/{measurementSerieId}

HTTP GET /Elvaco-Rest/rest/mdmsource/measurementSerieId/241

Svar

{

"sourceType": "mbus",

"formatString": null,

"constant": 1,

"sourceData": "0.mbus.dib.rf-level.0.0.0.0.value",

"created": 1418921380184,

"measurementSeriesId": 241,

"deactivated": -1,

"sourceIdentifier": 61000002,

"sourceId": 1147

}

Som framgår av svarstexten nedan är källtypen M-Bus (M-Busslav) för mätserier med id 241.

Två förfrågningsexempel ovan låter oss få information om mdmserie – mätserieinformation och mdmsource – mätseriens källinformation. Nu kommer information om mdmdata – mätseriedata att listas.

Användaren vill få mätseriedata.

Att få mätseriedata kan bestämmas på fem olika sätt med olika parametrar.

Listar alla mätseriedata med limit och offset.

Begäran

HTTP GET /Elvaco-Rest/rest/mdmdata/all/limit/{limit}/offset/{offset}

HTTP GET /Elvaco-Rest/rest/mdmdata/all/limit/100/offset/0

Notera

Att begära för många mdmdata (mätseriedata)-entiteter kan skapa stor belastning på applikationen. I detta fall föreslås en användning av limit och offset med pagineringsimplementering.

Svar

{

"total_records": 38728,

"limit": 100,

"offset": 0,

"values": [

{

"numeric": true,

"status": 0,

"created": 1418921232000,

"value": 62000501,

"sourceDate": 1418921230641,

"measurementSerieId": 188,

"effectiveDate": 1418921220000,

"measurementSerieDataId": 204,

"valueAsString": "62000501,000",

"sourceId": 1094

},

{

"numeric": false,

"status": 0,

"created": 1418921235000,

"value": 0,

"sourceDate": 1418921230641,

"measurementSerieId": 189,

"effectiveDate": 1418921220000,

"measurementSerieDataId": 205,

"valueAsString": "1.6.3",

"sourceId": 1095

},

{

...

},

{

"numeric": true,

"status": 0,

"created": 1418921237000,

"value": 4,

"sourceDate": 1418921230641,

"measurementSerieId": 191,

"effectiveDate": 1418921220000,

"measurementSerieDataId": 207,

"valueAsString": "4,000",

"sourceId": 1097

}

]

}

Listar mätseriedata från specifika mätserier med limit och offset.

Begäran

HTTP GET /ElvacoRest/rest/mdmdata/measurementserieId/{measurementserieId}/limit/{limit}/offset/{offset}

HTTP GET /Elvaco-Rest/rest/mdmdata/measurementserieId/241/limit/100/offset/0

Svar

{

"total_records": 296,

"limit": 100,

"offset": 0,

"values": [

{

"numeric": true,

"status": 0,

"created": 1418921380000,

"value": -66,

"sourceDate": 1418921374435,

"measurementSerieId": 241,

"effectiveDate": 1418921340000,

"measurementSerieDataId": 257,

"valueAsString": "-66,000",

"sourceId": 1147

},

{

...

},

{

"numeric": true,

"status": 0,

"created": 1418925604000,

"value": -66,

"sourceDate": 1418925601121,

"measurementSerieId": 241,

"effectiveDate": 1418925600000,

"measurementSerieDataId": 523,

"valueAsString": "-66,000",

"sourceId": 1147

}

]

}

Lista över mätseriedata med senaste antal avläsningar.

Begäran

HTTP GET /ElvacoRest/rest/mdmdata/measurementSerieId/{measurementSerieId}/latest/ {numberofread}

HTTP GET /Elvaco-Rest/rest/mdmdata/measurementSerieId/693/latest/5

Svar

{

"total_records": 337,

"limit": 5,

"offset": 0,

"values": [

{

"numeric": false,

"status": -1,

"created": 1426169671000,

"value": 0,

"sourceDate": 1426169671682,

"measurementSerieId": 693,

"effectiveDate": 1426169640000,

"measurementSerieDataId": 71619,

"valueAsString": "N/A",

"sourceId": 1599

},

{

"numeric": true,

"status": 0,

"created": 1426172404000,

"value": 0,

"sourceDate": 1426169667730,

"measurementSerieId": 693,

"effectiveDate": 1426172400000,

"measurementSerieDataId": 71686,

"valueAsString": "0,000",

"sourceId": 1599

},

{

"numeric": true,

"status": 0,

"created": 1426176005000,

"value": 0,

"sourceDate": 1426172401560,

"measurementSerieId": 693,

"effectiveDate": 1426176000000,

"measurementSerieDataId": 71753,

"valueAsString": "0,000",

"sourceId": 1599

},

{

"numeric": true,

"status": 0,

"created": 1426179605000,

"value": 0,

"sourceDate": 1426176001513,

"measurementSerieId": 693,

"effectiveDate": 1426179600000,

"measurementSerieDataId": 71820,

"valueAsString": "0,000",

"sourceId": 1599

},

{

"numeric": true,

"status": 0,

"created": 1426183205000,

"value": 0,

"sourceDate": 1426179601471,

"measurementSerieId": 693,

"effectiveDate": 1426183200000,

"measurementSerieDataId": 71887,

"valueAsString": "0,000",

"sourceId": 1599

}

]

}

Listar mätseriedata från när den skapades med limit och offset.

Begäran

HTTP GET /ElvacoRest/rest/mdmdata/created/{created}/limit/{limit}/offset/{offset}

HTTP GET /Elvaco-Rest/rest/mdmdata/created/1420448349000/limit/100/offset/0

Svar

{

"total_records": 8,

"limit": 100,

"offset": 0,

"values": [

{

"numeric": true,

"status": 0,

"created": 1420448349000,

"value": 16.44,

"sourceDate": 1420448349043,

"measurementSerieId": 188,

"effectiveDate": 1420448340000,

"measurementSerieDataId": 204,

"valueAsString": "16,440",

"sourceId": 1094

},

{

"numeric": true,

"status": 0,

"created": 1420448349000,

"value": 24.03,

"sourceDate": 1420448349043,

"measurementSerieId": 189,

"effectiveDate": 1420448340000,

"measurementSerieDataId": 205,

"valueAsString": "24,030",

"sourceId": 1095

},

{

"numeric": true,

"status": 0

"created": 1420448356000,

"value": 16.51,

"sourceDate": 1420448356214,

"measurementSerieId": 190,

"effectiveDate": 1420448340000,

"measurementSerieDataId": 206,

"valueAsString": "16,510",

"sourceId": 1096

},

{

"numeric": true,

"status": 0,

"created": 1420448356000,

"value": 23.990000000000002,

"sourceDate": 1420448356214,

"measurementSerieId": 191,

"effectiveDate": 1420448340000,

"measurementSerieDataId": 207,

"valueAsString": "23,990",

"sourceId": 1097

},

{

"numeric": true,

"status": 0,

"created": 1420448426000,

"value": 16.44,

"sourceDate": 1420448349043,

"measurementSerieId": 188,

"effectiveDate": 1420448400000,

"measurementSerieDataId": 208,

"valueAsString": "16,440",

"sourceId": 1094

},

{

"sourceId": 1094

"status": 0,

"created": 1420448426000,

"value": 24.02,

"sourceDate": 1420448425374,

"measurementSerieId": 189,

"effectiveDate": 1420448400000,

"measurementSerieDataId": 209,

"valueAsString": "24,020",

"sourceId": 1095

},

{

"numeric": true,

"status": 0,

"created": 1420448426000,

"value": 16.48,

"sourceDate": 1420448425374,

"measurementSerieId": 190,

"effectiveDate": 1420448400000,

"measurementSerieDataId": 210,

"valueAsString": "16,480",

"sourceId": 1096

},

{

"numeric": true,

"status": 0,

"created": 1420448426000,

"value": 23.990000000000002,

"sourceDate": 1420448425374,

"measurementSerieId": 191,

"effectiveDate": 1420448400000,

"measurementSerieDataId": 211,

"valueAsString": "23,990",

"sourceId": 1097

}

]

}

Denna begäran returnerar mätseriedata från begärd skapad med limit och offset. Skapad parameter ska vara i millisekunder.

Listar mätseriedata med ikraftträdandedatum från/till med limit och offset.

Begäran

HTTP GET /ElvacoRest/rest/mdmdata/effectiveDate/from/{from}/to/{to}/limit/{limit}/offset/{off set}

HTTP GET /ElvacoRest/rest/mdmdata/effectiveDate/from/1420448340000/to/1420548400000/limit/100 /offset/0

Svar

{

"total_records": 204,

"limit": 100,

"offset": 0,

"values": [

{

"numeric": true,

"status": 0,

"created": 1420448349000,

"value": 16.44,

"sourceDate": 1420448349043,

"measurementSerieId": 188,

"effectiveDate": 1420448340000,

"measurementSerieDataId": 204,

"valueAsString": "16,440",

"sourceId": 1094

},

{

...

},

{

"numeric": true,

"status": 0,

"created": 1420448426000,

"value": 23.990000000000002,

"sourceDate": 1420448425374,

"measurementSerieId": 191,

"effectiveDate": 1420448400000,

"measurementSerieDataId": 211,

"valueAsString": "23,990",

"sourceId": 1097

}

]

}

Begäran returnerar mätseriedata från begärt datumintervall med limit och offset. Effektiv datumparameter ska vara i millisekunder

Var denna artikel till hjälp?

0 av 0 tyckte detta var till hjälp
Har du fler frågor? Skicka en förfrågan

Artiklar i detta avsnitt

Kommentarer (0 kommentarer)

Artikeln är stängd för kommentarer.