OISservice 2.0
Generelt
OISservice er en Web-service der giver adgang til alle OIS-data. Adgangen sker på databaseniveau således brugeren eller applikationsudvikleren selv får mulighed for at sammensætte data, lave join mellem tabeller og tolke data.
Målet med OISservice er at give brugeren adgang til data og databasens funktionalitet på en sådan måde, at data kan indgå i brugerens egne applikationer.
Kommunikationen mellem bruger (Klient) og OISservice (Server) sker via SOAP.
OISservice har fire grundlæggende funktioner.
- Query. Afviklere en SQL-select forespørgsel
- GetDatapakke. Henter indholdet af en prædefineret pakke (samling af data fra forskellige kilder).
- CheckLogin. Tjekker om brugernavn og password er valid.
- ExecProc. Afvikler en procedure på databasen.
Data returneres som en XML-streng. Dataindholdet () er i bulkformat, hvor de enkelte felter er separeret med ';' og records er separeret med CRLF. Dette er gjort for at forbedre performance.
Den enkelte bruger har forskellige rettigheder. Der kan være begrænsninger i form af en maksimum antal records der kan returneres ved en SQL select-sætning, hvilke procedure der må afvikles eller hvilke datapakker der kan hentes.
Data er placeret på SQL-server version 2008 R2. Alle forespørgsler skal overholde standarten for "Microsofts Transact-SQL". På https://datamodel.lifa.dk er datamodellen for OIS data beskrevet og det muligt at se hvordan de enkelte tabeller, views og procedure er defineret.
Fejlhåndtering
Hvis en forespørgsel fejler retunerer OISservice en XML file med følgende indhold
<?xml version="1.0" encoding="utf-8"?>
<ExecProc Version="2.0.1">
<SQL>exec SEL_AdresseValg 421,1510,9,9</SQL>
<Error>
<Process>Exception ExecProc</Process>
<Message>Procedure or function SEL_AdresseValg has too many arguments specified.</Message>
</Error>
</ExecProc>
Hvor fejl meddelelsen står i <Error> taget.
Beskrivelse af OISservice
På https://www.lifaois.dk/oisservice/OISservice.asmx er servicens endpoints/operations, nedenfor beskrives følgende fire emner.
1. Query
2. GetDatapakke
3. CheckLogin
4. ExecProc
Query
Funktionen Query giver mulighed for at definerer sin egen SQL forespørgsel.
Query har fire parametre:
1. UID: brugernavn
2. PWD: Password
3. SQL: En SQL forespørgsel der overholder Microsoft Transact SQL
4. Meta: Angiver om der ønskes metadata. Hvis 1 kommer der metadata hvis intet kommer der ingen.
På Query kan funktionen testes.
Resultatet af forespørgslen ser således:
<Query Version="2.0.1">
<SQL>select top 10 * from ESRSkatRateView</SQL>
<RecordCount>10</RecordCount>
<Metadata FieldCount="6">
<Field Name="RATEDATO_ID" Type="200" DefinedSize="10" Precision="255"/>
<Field Name="KOMMUNE_NR" Type="2" DefinedSize="2" Precision="5"/>
<Field Name="SKAT_AAR" Type="2" DefinedSize="2" Precision="5"/>
<Field Name="RATENR" Type="2" DefinedSize="2" Precision="5"/>
<Field Name="FORFALD_DATO" Type="200" DefinedSize="10" Precision="255"/>
<Field Name="RETTID_DATO" Type="200" DefinedSize="10" Precision="255"/>
</Metadata>
<Data>
8721;171;2004;1;01-02-04;10-02-04 8722;171;2004;2;01-08-04;10-08-04
8897;485;2004;1;02-02-04;09-02-04 10731;625;2005;1;01-04-05;20-04-05
10732;625;2005;2;01-08-05;22-08-05 10623;659;2005;1;01-02-05;10-02-05
10624;659;2005;2;01-08-05;10-08-05 10625;509;2005;1;01-02-05;15-02-05
10626;509;2005;2;01-08-05;15-08-05 10441;657;2005;1;01-01-05;10-01-05
</Data>
</Query>
<Metadata> </Metadata> Indeholder definition på de enkelte felter.
Type, DefinedSize og Precision definerer felterne som ADO recordset.
<Data> </Data> Feltet indeholder data de enkelte felter er separeret med ';' og records er separeret med CRLF.
VBscript eksempel (Query)
Set httpObj = CreateObject("MSXML2.XMLHTTP.4.0")
httpObj.open "POST", "https://www.lifaois.dk/OISservice/OISService.asmx/Query", False
httpObj.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
httpObj.send ("UID=XXXX&PWD=XXXX&SQL=select top 1 * from BBRBygningView&Meta=")
MsgBox httpObj.responseXML.xml
GetDataPakke
GetDatapakke henter datapakker der bygger på en prædefineret skabelon. Det kunne for eksempel være oplysninger fra ESR,BBR og Matrikelregisteret.
Det er muligt at få defineret sine egne datapakker.
GetDatapakke
har fire parametre:
1. UID: brugernavn
2. PWD: Password
3. Template: Navn på den ønskede datapakke.
4. Par: De parametre pakken skal kaldes med Parameternavn1=værdi, Parameternavn2=værdi...
VBscript eksempel (GetDatapakke)
Set httpObj = CreateObject("MSXML2.XMLHTTP.4.0")
httpObj.open "POST", "https://www.lifaois.dk/OISservice/OISService.asmx/GetDatapakke", False
httpObj.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
httpObj.send ("UID=XXXX&PWD=XXXX&Template=plf&Par=kommune_nr=421,ejd_nr=1995")
MsgBox httpObj.responseXML.xml
CheckLogin
Tjekker om brugernavn og password er valide, det maksimale antal records den aktuelle bruger må hente ved brug af Query og om det aktuelle kald er understøttet af gZip enCoding.
CheckLogin har to parametre:
1. UID: brugernavn
2. PWD: Password
Resultatet er korrekt login:
<?xml version="1.0" encoding="utf-8"?>
<CheckLogin Version="2.0.1">
<Login>Login OK</Login>
<IP>80.62.70.213</IP>
<MaxRec>512</MaxRec>
<gzip_EncodingOK>True</gzip_EncodingOK>
</CheckLogin>
Resultatet er ukorrekt login:
<?xml version="1.0" encoding="utf-8"?>
<CheckLogin Version="2.0.1">
<Error>
<Process>Login</Process>
<Message>Brugernavn og/eller Password ikke korrekt</Message>
</Error>
<gzip_EncodingOK>True</gzip_EncodingOK>
</CheckLogin>
Resultatet af korrekt login men manglende adgang fra pågældende ip-adresse:
<?xml version="1.0" encoding="utf-8" ?>
<CheckLogin Version="2.0.1">
<Error>
<Process>Login</Process>
<Message>Brugeren 'ngh' har ingen adgang til OISservice fra IP-adressen 80.62.70.213. Hvis det er din faste IP-adresse så kontakt LIFA A/S for at få ændret din adgang til OISservice.</Message>
</Error>
<gzip_EncodingOK>True</gzip_EncodingOK>
</CheckLogin>
VBscript eksempel (CheckLogin)
Set httpObj = CreateObject("MSXML2.XMLHTTP.4.0")
httpObj.open "POST", "https://www.lifaois.dk/OISservice/OISService.asmx/CheckLogin", False
httpObj.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
httpObj.send ("UID=XXXX&PWD=XXXX")
MsgBox httpObj.responseXML.xml
ExecProc
ExecProc eksekvere en procedure i databasen, på www.lifaois.dk/datamodel er de enkelte procedure beskrevet nærmere.
ExecProc har fire parametre:
1. UID: Brugernavn
2. PWD: Password
3. Proc: Navn på den ønskede procedure
4. Par: De parametre pakken skal kaldes med.
Resultat er i samme format som for QUERY funktionen.
VB eksempel (ExecProc)
Set httpObj = CreateObject("MSXML2.XMLHTTP.4.0")
httpObj.open "POST", "https://www.lifaois.dk/OISservice/OISService.asmx/ExecProc", False
httpObj.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
httpObj.send ("UID=XXXX&PWD=XXXX&Proc=SEL_AdresseValg&Par=421")
MsgBox httpObj.responseXML.xml
Komprimering
OISservice anvender HTTP ver. 1.1. og bruger datakomprimering (gZip).
Hvis klienten ikke anmoder om komprimerede data - så returneres følgende fejlmeddelelse:
<?xml version="1.0" encoding="utf-8"?>
<ExecProc Version="2.0.1">
<Error>
<Process>Encoding</Process>
<Message>Browseren understøtter ikke HTTP ver. 1.1</Message>
</Error>
</ExecProc>
I VBscript eksemplerne benyttes MSXML2.XMLHTTP40 objektet. Styringen af om XMLHTTP anvender HTTP ver. 1.1 sker via indstillingerne for Internet Explorer.
I dialogen "Egenskaber for Internettet" skal der vælges "Brug HTTP 1.1 og evt. Brug HTTP 1.1 via proxyforbindelser.
