ENS DiademService. Servicebeskrivelse

Transkript

1 ENS DiademService

2 Indholdsfortegnelse 1 SERVICE ENDPOINTS Ping SearchEnergyLabelBBR SearchEnergyLabelUID FetchEnergyLabelDetails FetchEnergyLabelXml FetchEnergyLabelXmlRaw FetchEnergyLabelPdf FetchEnergyLabelPdfRaw FetchEnergyLabelPictureRaw 14 2 TEST AF SERVICE SoapUI Javascript 16 3 BILAG Modifiers argument i metoder ResponseStatus i reponsestrukturer Statuskoder SEEBClassification 20 DiademService - (2).docx Version 1.0 Side 2 af 20

3 1 Service endpoints DIADEMService.svc Service endpoint indeholder følgende metoder Metode Anvendelse Ping (1.1.1) SearchEnergyLabelBBR (1.1.2) SearchEnergyLabelUID (1.1.3) FetchEnergyLabelDetails (1.1.4) FetchEnergyLabelXml (1.1.5) FetchEnergyLabelXmlRaw (1.1.6) FetchEnergyLabelPdf (1.1.7) FetchEnergyLabelPdfRaw (1.1.8) FetchEnergyLabelPictureRaw (1.1.9) Kontrol af adgang til service. Søgning efter energimærkninger ud fra BBR-numre. Søgning efter energimærkninger ud fra UID fra OIS. Hentning af yderligere detaljer og beregninger på energimærke. Hentning af indberettet Xml på energimærke. Dele er fjernet eller ændret i forhold til original indberetning, fx pga. personfølsomme oplysninger. Samme som FetchEnergyLabelXml, men uden reponsestruktur. Hentning af Pdf-rapport på energimærke. Er ikke altid identisk med original rapport, men kan være begrænset version pga. personfølsomme oplysninger. Samme som FetchEnergyLabelPdf, men uden reponsestruktur. Hentning af billede i indberetning. Metoderne kan kaldes via SOAP eller REST. REST kaldene returnerer JSON. Tildelt brugernavn sendes i request-header usertoken. Alternativt kan brugernavn sendes i basic authorization header (se note om BA under 3.1) er i request og response objekter, i efterfølgende metodebeskrivelser, er strenge med mindre andet angivet. DiademService - (2).docx Version 1.0 Side 3 af 20

4 1.1.1 Ping REST uri template : Ping/{*modifiers} Request Object: Kan evt. brugs til versionscheck. Modifiers Tilføjes Version=<version>, kontrolleres angivne version med versionsnummer i interface. Hvis klient version er ældre end service, så returnerer statuskode ARGUMENT_ERROR. Response Object ResponseStatus : Objekt Objekt med status på metodekald. Se bilag 3.1 Version af interface i format YYYYMMDDnn, som angiver dato for implementering af metoder i interface. (nn er altid 01) InterfaceVersion Eksempelvis Versionsnummer ændres hvis metoder i service ændres i væsentlig grad. PingMessage Ping returbesked. Eksempel JSON response { } "InterfaceVersion":" ", "PingMessage":"Service is alive, access to database ok", "ResponseStatus": { "Status":"RESULT_OK", "StatusCode":3, "StatusMessage":"" } DiademService - (2).docx Version 1.0 Side 4 af 20

5 1.1.2 SearchEnergyLabelBBR REST uri template : SearchEnergyLabelBBR/{municipality}/{property}/{building}/{*modifiers} Request Object: Municipality Kommunekode. (fx 101 for Københavnskommune ) Property Building Ejendomsnummer (fx ejendom på Amaliegade) Bygningsnummer (fx 1) Hvis 0 angives som bygningsnummer, så søges efter alle bygningsnumre på ejendom. Modifiers Bruges ikke. (Se evt. bilag 3.1) Response Object ResponseStatus : objekt Se bilag 3.2 SearchResults : array Array med søgeresultater af typen EnergyLabelItem. Se nedenfor. EnergyLabelItem DiademService - (2).docx Version 1.0 Side 5 af 20

6 EntityIdentifier Identitetsstreng på entitet (energimærkning i søgeresultat) Vil være det samme som energimærkningsnummeret, men det kan evt. ændre sig. LabelStatusCode : enum Værdi 1:VALID 2:INCOMPATIBLE 3:EXPIRED Energimærkning er gyldig. Energimærkning er gyldig, men indberetningsformatet er ikke understøttet. Fås normalt ikke, da udløbne energimærker frasorteres. LabelSatus EnergyLabelSerialIdentifier Tekst på enum-værdien af LabelStatusCode Energimærkningsnummer EnergyLabelClassification Energimæke klassifikation (fx D) ValidFrom ValidTo StreetName HouseNumber ZipCode CityName MunicipalityNumber PropertyNumber BuildingNumber BBRUseCode YearOfConstruction HeatSupply EnergyLabelTypeUsage EnergyLabelTypeBasedOn Gyldighedsdato fra (YYYY-MM-DD) Gyldighedsdato til (YYYY-MM-DD) Vejnavn Husnummer Postnummer Bynavn Kommunekode i BBR-nummer Ejendomsnummer i BBR-nummer Bygningsnummer i BBR-nummer. Hvis energimærkning omfatter flere bygninger, så angivers alle bygningsnumre adskilt med komma. Anvendelseskode. (på indberetningstidspunktet) Opførelsesår. Hvis energimærkning omfatter flere bygninger, så angives alle opføreslesår adskilt med komma. Primær energikilde til opvarmning. Anvendelse (fx SingleFamily) Grundlag for energimærkning (fx CalculatedConsumption) DiademService - (2).docx Version 1.0 Side 6 af 20

7 IsMixedUsage SubmitterConsultantName SubmitterCompanyName SubmitterCompanyIdentifier HasPdf : boolean HasXml : boolean SchemaVersion DemoLink True/False Navn på energikonsulent Navn på firma som energikonsulent er tilknyttet. Id på firma. Pdf rapport er tilgængelig. Xml på indberetning er tilgængelig. Indberetningsformat på Xml Hvis anvendelseskoden er 110, 120, eller 130, så angives link til den digitale energimærkningsordning på adressen. I øvrige tilfælde angives link til pdf-dokument på energimærkning. DiademService - (2).docx Version 1.0 Side 7 af 20

8 1.1.3 SearchEnergyLabelUID REST uri template : SearchEnergyLabelUID/{UID}/{*modifiers} Request Object: UID Unique identifier. GUID s fra OIS-database. Kan referere til bygning, eller adgangsadresse på bygning. AdgAdr : UID er adgangsadresse modifiers Bygning : UID er bygning Serial : energimærkningsnummer Se iøvrigt 3.1 Response Object Samme som for metoden SearchEnergyLabelBBR (se 1.1.2) DiademService - (2).docx Version 1.0 Side 8 af 20

9 1.1.4 FetchEnergyLabelDetails REST uri template : FetchEnergyLabelDetails/{EntityIdentifier}/{*modifiers} Request Object: EntityIdentifier Identitetsstreng på entitet (energimærkning i søgeresultat) Vil være det samme som energimærkningsnummeret, men det kan evt. ændre sig. Investment begrænser evt. forbedringsforslag under ProposalOverview (se response object) Investment=All : Alle forbedringsforslag returneres (default). Investment=Profitable : Profitable forbedringsforslag returneres. modifiers Investment=Recommended : Anbefalede forbedringsforslag returneres. Anbefalede forbedringsforslag er ikke altid oplyst i datagrundlaget, specielt for ældre energimærker. Se iøvrigt 3.1 Response Object ResponseStatus : objekt Se bilag 3.2 ProposalCalculation : objekt ProposalOverview : objekt Enkelte beregninger for forbedringsforslag. nedenfor. Oversigt over forbedringsforslag. nedenfor. DiademService - (2).docx Version 1.0 Side 9 af 20

10 ProposalCalculation AdditionalHeat AdditionalHeatCost CalculatedConsumption CalculatedEmission CalculatedEmissionLowering CalculatedEnergyConsumption CalculatedEnergySavings ElectricityPrice ExtraCostPrYear FixedCharge HeatSupply HeatSupplyCost TotalProfitableInvestment Sekundær energikilde til opvarmning Sekundær energikilde udgift Beregnet forbrug Beregnet CO2 udlednning Beregnet CO2 nedsættelse Beregnet energiforbrug Beregnet energibesparelse El pris Ekstra udgift pr år Fast omkostning Primær energikilde til opvarmning Primær energikilde udgift Investering ved valgte investeringer. DiademService - (2).docx Version 1.0 Side 10 af 20

11 ProposalOverview ExtraCostPrYear ExtraCostPrYearForAllProposals ExtraCostPrYearForRecommendedProposals PossibleEnergyLabelForAllProfitableProposals PossibleEnergyLabelForAllProposals TotalProfitableInvestment TotalRecommendedInvestment Proposals : array Ekstra udgift pr år. Ekstra udgift pr år for alle forbedringsforslag. Ekstra udgift pr år for anbefalede forbedringsforslag. Mulig energi klassifikation ved alle profitable forbedringsforslag. Mulig energi klassifikation ved alle forbedringsforslag. Investering ved alle profitable forbedringsforslag. Investering ved alle anbefalede forbedringsforslag. Liste med enkelte forslag af type Proposal (se nedenfor) Proposal Investment Profitable ProposalHeadline ProposalID Recommended Savings Investering. True/False : indikation om forbedringsforslag er profitabel. Kort beskrivelse af forbedringsforslag. Intern reference til forbedringsforslag i indberettet Xml. True/False : indikation om forbedringsforslag er anbefalet af energikonsulent. Besparelse. SeebClassification Klassifikation på forbedring. (se 3.4) DiademService - (2).docx Version 1.0 Side 11 af 20

12 1.1.5 FetchEnergyLabelXml REST uri template : FetchEnergyLabelXml/{EntityIdentifier}/{*modifiers} Request Object: EntityIdentifier Identitetsstreng på entitet (energimærkning i søgeresultat) Vil være det samme som energimærkningsnummeret, men det kan evt. ændre sig. modifiers Se iøvrigt 3.1 Response Object ResponseStatus : objekt Se bilag 3.2 Xml på energimærkning, som er indberettet af energikonsulent. XmlDocument Dele er fjernet eller ændret i forhold til original indberetning, fx pga. personfølsomme oplysninger FetchEnergyLabelXmlRaw Rest uri template : FetchEnergyLabelXmlRaw/{EntityIdentifier}/{*modifiers} Input er det samme som for FetchEnergyLabelXml, men i stedet returneres det rå xml. (For SOAP kald vil response dog stadig være pakket ind i SOAP envelope) I stedet for ResponseStatus kan header X-OperationStatus kontrolleres for status på kaldet. HTTP/ OK Content-Length: Content-Type: text/xml Server: Microsoft-IIS/7.5 Access-Control-Allow-Origin: * X-OperationTime: 00:00: X-OperationStatus: RESULT_OK Content-Disposition: inline; filename= _public.xml X-Powered-By: ASP.NET Date: Fri, 13 Jun :02:44 GMT <EnergyLabel... HTTP/ No Content Content-Length: 0 Content-Type: application/octet-stream Server: Microsoft-IIS/7.5 Access-Control-Allow-Origin: * X-OperationTime: 00:00: X-OperationStatus: RESULT_EMPTY X-ErrorMessage: Energylabel not found for number: X-Powered-By: ASP.NET Date: Fri, 13 Jun :01:45 GMT DiademService - (2).docx Version 1.0 Side 12 af 20

13 1.1.7 FetchEnergyLabelPdf REST uri template : FetchEnergyLabelPdf/{EntityIdentifier}/{*modifiers} Request Object: EntityIdentifier : string Identitetsstreng på entitet (energimærkning i søgeresultat) Vil være det samme som energimærkningsnummeret, men det kan evt. ændre sig. modifiers Se iøvrigt 3.1 Response Object ResponseStatus : objekt Se bilag 3.2 PdfDocument Pdf-rapport på energimærkning. Binær data er Base64 encodet FetchEnergyLabelPdfRaw REST uri template : FetchEnergyLabelPdfRaw/{EntityIdentifier}/{*modifiers} Input er det samme som for FetchEnergyLabelPdf, men i stedet returnes de rå data. (For SOAP kald vil response dog stadig være pakket ind i SOAP envelope) I stedet for ResponseStatus kan header X-OperationStatus kontrolleres for status på kaldet. HTTP/ OK Content-Length: Content-Type: application/x-pdf Server: Microsoft-IIS/7.5 Access-Control-Allow-Origin: * X-OperationTime: 00:00: X-OperationStatus: RESULT_OK Content-Disposition: inline; filename= pdf X-Powered-By: ASP.NET Date: Fri, 13 Jun :47:13 GMT %PDF HTTP/ No Content Content-Length: 0 Content-Type: application/octet-stream Server: Microsoft-IIS/7.5 Access-Control-Allow-Origin: * X-OperationTime: 00:00: X-OperationStatus: RESULT_EMPTY X-ErrorMessage: Energylabel not found for number: X-Powered-By: ASP.NET Date: Fri, 13 Jun :52:17 GMT DiademService - (2).docx Version 1.0 Side 13 af 20

14 1.1.9 FetchEnergyLabelPictureRaw REST uri template : FetchEnergyLabelPdfRaw/{EntityIdentifier}/{*modifiers} Returnerer binær data på billede. (For SOAP kald vil response dog stadig være pakket ind i SOAP envelope) Header X-OperationStatus kontrolleres for status på kaldet. HTTP/ OK Content-Length: Content-Type: image/jpeg Server: Microsoft-IIS/7.5 Access-Control-Allow-Origin: * Content-Disposition: inline; filename= jpeg X-OperationTime: 00:00: X-OperationStatus: RESULT_OK X-Powered-By: ASP.NET Date: Fri, 13 Jun :05:54 GMT _JFIF... DiademService - (2).docx Version 1.0 Side 14 af 20

15 2 Test af service 2.1 SoapUI For test gennem SoapUI. Opret nyt projekt. I Initial WSDL, til test-miljø angiv Headers (eg. usertoken) kan tilføjes til hvert enkelt request. Åben et request under metode, klik på Headers i bunden af request vinduet, klik på tilføj-knappen i toppen af headers-vinduet. DiademService - (2).docx Version 1.0 Side 15 af 20

16 2.2 Javascript Ping eksempel var username = 'xsomeuser'; var url = ' + '/Ping/Version= ' ; $.ajax({ url: url + "?" + Math.random(), datatype: 'json', async: true, crossdomain: true, headers: { usertoken: username } }).done(function(data, textstatus, jqxhr) { if (data.responsestatus.statuscode=='3') alert(data.pingmessage); else alert(data.responsestatus.status + ' : ' + data.responsestatus.statusmessage); }).fail(function(jqxhr, textstatus, errorthrown) { alert("ping failed: "+ errorthrown); }); DiademService - (2).docx Version 1.0 Side 16 af 20

17 3 Bilag 3.1 Modifiers argument i metoder Alle metoder har en parameter modifiers, som er til switches som kan modificere adfærden af den enkelte metode. Enkelte switches adskilles af komma. Typisk brug er angivet under beskrivelsen af de enkelte metoder. Øvrige switches angivet herunder, skal normalt ikke bruges. BA: Basic Authentication. Hvis brugernavn ikke kan sendes som request header. (fx hvis der er fra et direkte link i browser), så sendes http status 401 (unauthorized) tilbage, i stedet for den normale responsestruktur. Det bevirker at man i en browser vil få en login boks: Kan bruges til test af REST-interface. Basic authorization-header kan også sendes med i første kald, sammen med BA modifier. TL : progress/timing logning. I koden er der punkter hvor der kan blive taget en tidstagning. LDB: logger ovenstående timings i databasen (ud over selve kaldet). Manglende switch eller minus (-) foran, logges der ikke i database. Må kun bruges efter aftale. DiademService - (2).docx Version 1.0 Side 17 af 20

18 3.2 ResponseStatus i reponsestrukturer StatusCode : enum Int-værdi for status. (se bilag 0) Status StatusMessage Tekst for StatusCode. Evt. uddybende tekst for status. Er typisk udfyldt i tilfælde af fejl. DiademService - (2).docx Version 1.0 Side 18 af 20

19 3.3 Statuskoder Mulige statuskoder, som kan returneres fra metoder. Ikke alle statuskoder er relevant for alle metoder i service. StatusKode UNSPECIFIED_ERROR = 0 Uventet fejl. Kontakt ENS. ACCESS_DENIED = 1 POLICY_ERROR = 2 Brugernavn ikke angivet i kald, eller brugernavn ikke registreret i systemet. Restriktioner tilknyttet bruger er ikke overholdt. Metodekald kan evt. foretages på senere tidspunkt. RESULT_OK = 3 Resultat fundet på forespørgsel, og returneret i response struktur. RESULT_EMPTY = 4 Fandt intet resultat på forespørgsel. RESULT_COUNT_EXCEEDED = 5 MAINTENANCE_MODE = 6 ARGUMENT_ERROR = 7 Søgning gav for mange resultater. Antal af resultater i responsestruktur vil være begrænset. Til evt. fremtidig brug. Ikke implementeret. Service er midlertidigt ude af drift. Samme metodekald kan foretages på senere tidspunkt. Til evt. fremtidig brug. Ikke implementeret. Fejl i argumenter til metode. Samme søgning børe ikke foretages igen. SERVICE_ERROR = 8 Fejl i service. Kontakt ENS hvis fejl er vedholdende. BACKEND_UNAVAILABLE = 9 NOT_SUPPORTED = 10 Forespørgsel var afhængig af andet system, som ikke var tilgængeligt. Samme metodekald kan foretages på senere tidspunkt. Forespørgsel kunne ikke returnere resultat, pga. manglende tilgængelige data. DiademService - (2).docx Version 1.0 Side 19 af 20

20 3.4 SEEBClassification , Bygningen , Tag og loft , Loft , Fladt tag , Loft til kip , Ydervægge , Hule ydervægge , Massive ydervægge , Lette ydervægge , Hule vægge mod uopvarmet rum , Massive vægge mod uopvarmet rum , Lette vægge mod uopvarmet rum , Kælder ydervægge , Vinduer, ovenlys og døre , Vinduer , Ovenlys , Yderdøre , Gulve , Terrændæk , Etageadskillelse , Krybekælder , Kældergulv , Terrændæk med gulvvarme , Etageadskillelse med gulvvarme , Krybekælder med gulvvarme , Kældergulv med gulvvarme , Linjetab , Ventilation , Ventilation , Ventilationskanaler , Køling , Internt varmetilskud , Internt varmetilskud , Varmeanlæg , Varmeanlæg , Varmeanlæg , Kedler , Fjernvarme , Ovne , Varmepumper , Solvarme , Varmefordeling , Varmefordeling , Varmerør , Varmefordelingspumper , Automatik , Varmt og koldt vand , Varmt brugsvand , Varmt brugsvand , Armaturer , Varmtvandsrør , Varmtvandspumper , Varmtvandsbeholder , Koldt vand , Koldt vand , El , El , Belysning , Apparater , Solceller , Vindmøller DiademService - (2).docx Version 1.0 Side 20 af 20