Tredjepart webservices

Transkript

1 Tredjepart webservices 4. juni 2015 USS Dok. Klik her for at angive tekst. 1/12

2 Indholdsfortegnelse Introduktion... 3 Miljøer... 3 Adgang... 3 API kald... 4 GET: /authorizations... 4 Input 4 Output 4 Output eksempel... 4 GET: /timeseries/... 5 Input 5 Output 5 Output eksempel... 5 GET: /historictimeseries/... 7 Input 7 Output 7 Output eksempel... 7.NET kode eksempel... 9 Ændringslog Dok. 14/ /12

3 1. Introduktion Webservicen består af følgende elementer: ASP.NET Web API, JSON og XML HTTPS/SSL benyttes til transport og sikkerhed. Transportlaget krypterer data og overfører certifikat mellem Tredjepart og Energinet til autentifikation Certifikater (FOCES) benyttes som identifikation af Tredjepart 2. Miljøer TEST miljø Web service Web service dokumentation URL test-energinetcap.miracleas.dk/api/ Afventer PROD miljø Web service Web service dokumentation URL Afventer 3. Adgang Før en Tredjepart kan benytte system til system adgangen skal følgende kriterier være opfyldt: Tredjeparten skal anskaffe et funktionscertifikat (FOCES) Tredjeparten skal registreres som systembruger i tredjepartsystemet Tredjeparten skal i øvrigt kunne leve op til de tekniske specifikationer for brug af servicen som beskrives i de efterfølgende sektioner Certifikat kan rekvireres hos NETS: Installation af certifikatet er beskrevet her: Dok. 14/ /12

4 4. API kald API et er baseret på HTTP. GET: /authorizations Returnerer en liste over fuldmagter for CVR nummeret i Nem ID certifikatet. Input Navn Type Krævet Kommentar Nem ID certifikat Http header Yes Accept Http header No application/xml application/json (default) Output HTTP Status Data Kommentar 200 Liste over fuldmagter i JSON Succes svar 403 Ingen Ikke gyldigt certifikat eller CVR nummer 404 Ingen Ingen fuldmagter fundet Output eksempel XML <meteringpoints> <MeteringPointIdentification> </MeteringPointIdentification> <WebaccessCode></WebaccessCode> <StreetName>Danmarksgade</StreetName> <BuildingNumber></BuildingNumber> <FloorIdentification></FloorIdentification> <Postcode></Postcode> <CityName></CityName> <Alias></Alias> <ParentMP></ParentMP> <SettlementMethod></SettlementMethod> <Product></Product> <MeterCounterUnit></MeterCounterUnit> <MeterReadingOccurence></MeterReadingOccurence> <TypeOfMP>Type 1</TypeOfMP> <NetSettlementGroup></NetSettlementGroup> <DataAccessCvr></DataAccessCvr> <ConsumerCVR></ConsumerCVR> <etc>...</etc> <etc>...</etc> </meteringpoints> JSON "meteringpoints":[ "MeteringPointIdentification":" ", "WebaccessCode":"", "StreetName":"Danmarksgade", "BuildingNumber":"", "FloorIdentification":"", "Postcode":"", "CityName":"", "Alias":"", "ParentMP":"", Dok. 14/ /12

5 ],, "SettlementMethod":"", "Product":"", "MeterCounterUnit":"", "MeterReadingOccurence":"", "TypeOfMP":"Type 1", "NetSettlementGroup":"", "DataAccessCvr":"", "ConsumerCVR":"" "etc":"..." "etc":"..." GET: /timeseries/ Returnerer målerdata for den kaldte måler Input Navn Type Krævet Kommentar Nem ID certifikat Http header Yes Accept Http header No application/xml application/json (default) MeteringPointId Querystring - integer Yes 18 cifret måler id Period Querystring - string Yes Værdier: Month data for seneste måned Quater data for seneste kvartal Year data for op til et år History Querystring - bool No True False (default værdi) Eksempler: /timeseries?authorizationid=2&meteringpointid= &period= month Output HTTP Status Data Kommentar 200 Målerdata Succes svar 400 None Forkert formateret meteringpointid og/eller forkert kombination af fuldmagt og meteringpointid 403 None Ikke gyldigt certifikat eller CVR nummer 404 None Ingen fuldmagter fundet Output eksempel XML <meteringpoints> <from> :00</from> <meteringpointid> </meteringpointid> <to> :00</to> Dok. 14/ /12

6 </meteringpoints> <usage>1234,0 KwH</usage> <from> :00</from> <meteringpointid> </meteringpointid> <to> :00</to> <usage>1234,0 KwH</usage> <from> :00</from> <meteringpointid> </meteringpointid> <to> :00</to> <usage>1234,0 KwH</usage> JSON "meteringpoints":[ "meteringpointid":" ", "from":" :00", "to":" :00", "usage":"1234,0 KwH", "meteringpointid":" ", "from":" :00", "to":" :00", "usage":"1234,0 KwH", "meteringpointid":" ", "from":" :00", "to":" :00", "usage":"1234,0 KwH" ] Dok. 14/ /12

7 GET: /historictimeseries/ Returnerer målerdata for den kaldte måler. Input Navn Type Krævet Kommentar Nem ID certifikat Http header Yes Accept Http header No application/xml application/json (default) MeteringPointId Querystring - integer Yes 18 cifret måler id Eksempler: /historictimeseries?authorizationid=2&meteringpointid= Output HTTP Status Data Kommentar 200 Målerdata Succes svar 400 None Forkert formateret meteringpointid og/eller forkert kombination af fuldmagt og meteringpointid 403 None Ikke gyldigt certifikat eller CVR nummer 404 None Ingen fuldmagter fundet Output eksempel XML <meteringpoints> </meteringpoints> <from> :00</from> <meteringpointid> </meteringpointid> <to> :00</to> <usage>1234,0 KwH</usage> <from> :00</from> <meteringpointid> </meteringpointid> <to> :00</to> <usage>1234,0 KwH</usage> <from> :00</from> <meteringpointid> </meteringpointid> <to> :00</to> <usage>1234,0 KwH</usage> JSON "meteringpoints":[ "meteringpointid":" ", "from":" :00", "to":" :00", "usage":"1234,0 KwH", Dok. 14/ /12

8 ] "meteringpointid":" ", "from":" :00", "to":" :00", "usage":"1234,0 KwH", "meteringpointid":" ", "from":" :00", "to":" :00", "usage":"1234,0 KwH" Dok. 14/ /12

9 5..NET kode eksempel Nedenstående kodeeksempel viser, hvordan man kan lave klientautentificerede SSL forbindelser til webservicen. using System; using System.Collections.Generic; using System.Net; using System.Net.Http; using System.Net.Http.Headers; using System.Security.Cryptography.X509Certificates; using System.Threading.Tasks; namespace TestWebApiClient class Program static void Main(string[] args) RunAsync().Wait(); static async Task RunAsync() // get your Nemid certificate var certificate = new X509Certificate2(@"C:\\Temp\\VOCES_gyldig.p12", "Test1234"); // add certificate to handler var handler = new WebRequestHandler(); handler.clientcertificates.add(certificate); using (var client = new HttpClient(handler)) client.baseaddress = new Uri(" client.defaultrequestheaders.accept.clear(); // request json response client.defaultrequestheaders.accept.add(new MediaTypeWithQualityHeaderValue("application/json")); // get authorizations var listofauthorizations = new List<Authorizations>(); var respauthorizations = await client.getasync("authorizations"); if (respauthorizations.statuscode == HttpStatusCode.OK) listofauthorizations = await respauthorizations.content.readasasync<list<authorizations>>(); else var exception = new Exception StatusCode = respauthorizations.statuscode, Reason = respauthorizations.reasonphrase, Content = respauthorizations.content.readasstringasync().result ; Dok. 14/ /12

10 //TODO: Handle errors // get historic timeseries foreach (var authorization in listofauthorizations) foreach (var meter in authorization.listofmeters) var url = string.format("historictimeseries?authorizationid=0&meteringpointid=1", authorization.id, meter.meteringpointidentification); var resptimeseries = await client.getasync(url); if (resptimeseries.statuscode == HttpStatusCode.OK) var timeseries = await resptimeseries.content.readasasync<list<timeseries>>(); //TODO: Save values to collection or datastore else var exception = new Exception StatusCode = resptimeseries.statuscode, Reason = resptimeseries.reasonphrase, Content = resptimeseries.content.readasstringasync().result ; //TODO: Handle errors public class TimeSeries public string MeteringPointId get; set; public DateTime DateFrom get; set; public DateTime DateTo get; set; public decimal UsageDecimal get; set; public string Unit get; set; public class Authorizations public int Id get; set; public string ThirdPartyKey get; set; public string Name get; set; public DateTime StartDate get; set; public DateTime EndDate get; set; public bool HistoricData get; set; public int CurrentDataResolution get; set; Dok. 14/ /12

11 public IEnumerable<MeteringPoints> ListOfMeters get; set; public class MeteringPoints public string MeteringpointIdentification get; set; public string Streetname get; set; public string BuildingNumber get; set; public string Postcode get; set; public string CityName get; set; public string Alias get; set; public string ParentMP get; set; public string v1 get; set; public string v2 get; set; public string MeterCounterUnit get; set; public string v4 get; set; public string TypeOfMP get; set; public string NetSettlementGroup get; set; public string DataAccessCvr get; set; public string ConsumerCVR get; set; public class Exception public HttpStatusCode StatusCode get; set; public string Reason get; set; public string Content get; set; Dok. 14/ /12

12 6. Ændringslog Version Date Forfatter Kommentarer Flemming Schøsler Flemming Schøsler Flemming Schøsler Opdateret.NET eksempel og tilføjet historic timeseries API beskrivelse. Tilføjet.NET eksempel Første version Dok. 14/ /12