Date: Thu, 28 Mar 2024 13:25:37 +0000 (UTC) Message-ID: <426071455.56364.1711632337072@faab6ceaf485> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_56363_1324833432.1711632337070" ------=_Part_56363_1324833432.1711632337070 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Siden giver en introduktion til og vejledning i, hvordan man kan anvende= webservices som udstilles p=C3=A5 Datafordeleren.
G=C3=A5 til Guide til REST i Selvbet= jeningen, hvis du har b= rug for helt konkrete anvisninger til at bruge en webservice fra Dat= afordeleren.
I de registerspecifikke servicekat=
ologer vil du under hver metode kunne se eksempler p=C3=A5 hvordan url'en e=
r opbygget og p=C3=A5 siderne
BEM=C3=86RK
P=C3=A5 Datafordeleren er der ikke konfigureret timeout p=C3=A5 webtjene= ster.
REST-tjenester i princippet er designet til relativt simple ad-hoc fores= p=C3=B8rgsler, der returnerer begr=C3=A6nsede datam=C3=A6ngder.
Med REST-tjenesterne finder du eksempelvis svar p=C3=A5 et =C3=B8nsket = =C3=B8jebliksbillede som:
Webservices giver anvenderne mulighed for at hente data ved at kalde = en service.
Datafordeleren underst=C3=B8tter f=C3=B8lgende servicetyper:= p>
De f=C3=B8lgende afsnit vil prim=C3=A6rt beskrive REST-services.
N=C3=A5r en webservice konfigureres genereres der automatisk en url.<= /span>
Opbygningen af url=E2=80=99en sker ud fra f=C3=B8lgende kriterier, som a= ngives i forbindelse med konfigurationen af webservicen:
Strukturen for den genererede url sker i overensstemmelse med f=C3=B8lge= nde skema:
<scheme>://<authority>/<path>/?<parameters>= span>
Strukturen for den samlede url s= ker i overensstemmelse med f=C3=B8lgende skema, n=C3=A5r&= lt;authority> og <path> bliver foldet ud:
<scheme>://<alias>.datafordeler.dk/<owner>/<serv=
ice>/<version>/<metode>/?<parameters><=
/p>
BESKRIVELSE AF URL-OPBYGNING
<scheme> afg=C3=B8res af den valgte protokol og vil = altid v=C3=A6re enten http eller https.
Det anbefales ikke at sende brugernavn/adgangskode ukrypteret. Derfor b=
=C3=B8r der altid anvendes https, hvis disse sikkerhedsakkreditiver anvende=
s.
<authority> udg=C3=B8res af f=C3=B8lgende m=C3=B8= nster <alias>.dat= afordeler.dk
<path>udg=C3= =B8res af f=C3=B8lgende m=C3=B8nster <owner>/<service>/<version>/<metode><= /strong>
<parameters>
I slutningen af url'en angives pa=
rametre, som bliver beskrevet n=C3=A6rmere i det efterf=C3=B8lgende afsnit.=
Parametre d=C3=A6kker over b=C3=A5de sikkerhedsparametre, standardpar= ametre og tjenestespecifikke parametre.
Datafordeleren underst=C3=B8tter en r=C3=A6kke forskellige akkreditiver. = De skal sendes med i kald til tjenester, der ikke har anonym adgang.=
Brug Dataoversigten eller de =
registerspecifikke servicekatologer til at unders=C3=B8ge, hvilken brugerad=
gang den =C3=B8nskede tjeneste kr=C3=A6ver og l=C3=A6s mere om <=
/span>Brugeroprettelse og
Kald med certifi= kater skal ikke ske til det =E2=80=9Dnormale=E2=80=9D endpoint, men skal g= =C3=A5 til et separat endpoint specifikt for anvendelse af certifikater.
Se endpoint for testmilj=C3=B8erne p= =C3=A5 siden Hent data.=
<scheme>://<alias>.datafordeler.dk/<owner>/<serv=
ice>/<version>/<metode>/?username=3Dxxx&password=3Dyyy=
strong>
INDS=C3=86T OPLYSNINGER I URL'EN FOR B= RUGERNAVN/ADGANGSKODE
Brugernavn og adgangskode er obligatoriske parametre, hvis tjenestebruge=
ren er oprettet p=C3=A5 den m=C3=A5de.
Det er tjenestebrugerens brugernavn og adgangskode, som skal tilf=C3=B8jes=
.
F=C3=B8lgende skal tilf=C3=B8jes url'en for at hente h=C3=A6ndelsesbeskede=
r:
xxx - skal erstattes med brugernavn for tjenestebruger
yyy - skal erstattes med adgangsk=
ode for tjenestebruger
Nogle tjenester vil du med andre o= rd kunne tilg=C3=A5 med b=C3=A5de brugernavn/adgangskode og certifikat.&nbs= p;Andre = tjenester vil du af sikkerhedsm=C3=A6ssige =C3=A5rsager kun kunne tilg=C3= =A5r med certifikat.
I de registerspecifikke servicekat= ologer vil du under hver metode kunne se eksempler p=C3=A5 hvordan url'en e= r opbygget og hvordan du kan tilg=C3=A5 den.
En r=C3=A6kke parametre er standard p=C3=A5 Datafordeleren. I webservicekatalogerne vil det fremg=
=C3=A5 om registrets webservices er konfigureret til at benytte disse param=
etre.
Det er muligt at anvende paging for de REST-services, der er konfigure= ret til det.
I webservicekatalogerne vil det fremg=C3=A5 af de generelle informatio= ner om registrets webservices er konfigureret til at benytte paging samt in= formationer om en default paging-st=C3=B8rrelse.
Anvender paging:
Anvender ikke paging:
<=
/p>
Benytter du paging vil den samlede url f=C3=B8lge dette skema:
<scheme>://<alias>.datafordeler.dk/<ow= ner>/<service>/<version>/<metode>/?page=3Dxxx&page= size=3Dyyy
INDS=C3=86T OPLYSNINGER I URL'EN FOR P= AGING
F=C3=B8lgende skal tilf=C3=B8jes url'en for at hente h=C3=A6ndelsesbeske= der med paging:
xxx - skal erstattes med nummeret p=C3=A5 den side, som du =C3=B8nsker.<= br>yyy - skal erstattes = med den sidest=C3=B8rrelse, som du =C3=B8nsker.
Antal elementer i resultats=C3=A6ttet returneres ved at angive paramet= eren count i REST kald.
Benytter du count vil den samlede url f=C3=B8lge dette skema:
<scheme>://<alias>.datafordeler.dk/<owner>/<serv=
ice>/<version>/<metode>/?count=3Dtrue
INDS=C3=86T OPLYSNINGER I URL'EN FOR C= OUNT
F=C3=B8lgende skal tilf=C3=B8jes url'en for at hente antallet af element= er i resultats=C3=A6ttet:
count= =3Dtrue
REST-servicen kan returnere data i formaterne JSON og XML. Angiver du ikke hvilket format du = =C3=B8nsker dit output vil du modtage det i JSON, da de er defaultv=C3=A6rd= ien p=C3=A5 Datafordeleren.
V=C3=A6lger du at specificere formatet, vil den samlede url f=C3= =B8lge dette skema:
<scheme>://<alias>.datafordeler.dk/<ow= ner>/<service>/<version>/<metode>/?format=3Dxxx
INDS=C3=86T OPLYSNINGER I URL'EN FOR F= ORMAT
F=C3=B8lgende skal tilf=C3=B8jes url'en for at hente h=C3=A6ndelsesbeske= der med et bestemt format:
xxx - skal erstattes med enten json eller xml.
En anden muligh= ed er at s=C3=A6tte accept headeren til "application/json" eller "applicati= on/xml".
jsonpCallback: jsonp kan anvendes ved at angive jsonpCallback=3Dxxx. = ;
De registerspecifikke servicekataloger er knyttet til de specifikationer= , som registret har specificeret i deres Dataleverancespecifikation (DLS).&= nbsp;For hver parameter er dens type angivet.
Der benyttes f=C3=B8lgende typer:
I de registerspecifikke serviceka= tologer vil du under hver metode kunne se hvilke parametre, som det er muli= gt at benytte p=C3=A5 den enkelt metode og af hvilken type den er.= p>
Nogle tjenester accepterer at en parameter best=C3=A5r af en liste af v= =C3=A6rdier.
For de REST baserede webservices er dette underst=C3=B8ttet ved at de en= kelte v=C3=A6rdier i listen adskilles af et =E2=80=9D|=E2=80=9D-tegn (pipe = karakter).
Eksempel med 4 v=C3=A6rdier i en liste ti= l en parameter: V=C3=A6rdi1|V= =C3=A6rdi2|V=C3=A6rdi3|V=C3=A6rdi4
EKSEMPEL P=C3=85 KALD MED FLERE CPR NU= MRE
https://= s5-certservices.datafordeler.dk/CPR/CprPersonFullComplete/1/rest/PersonFull= ListComplete?Format=3DJSON&pnr.personnummer.wi=3Dxxxxxxxxxx|xxxxxxxxxx<= /span>
Datoformat f=C3=B8lger ISO 8601 Date and time format. Alle datoer skrive= s med andre ord i formatet yyyy-mm-ddTHH:MM:SS.ssssss, hvor tidsangivelsen = kan udelades.
Tidszonen kan angives enten ved (= 2019-02-05T07:50:14.687580+01:00 (for normaltid/vintertid)), (2019-07-05T07= :50:14.687580+02:00 (for sommertid)) eller ved at benytte Z (2019-07-05T07:= 50:14.687580Z).
For at kalde en stor del af metoderne p=C3=A5 Datafordeleren er det n=C3= =B8dvendigt at tilf=C3=B8je obligatoriske parametre.
I registerspecifikke servicekatologerne vil du under hver metode se ekse= mpler p=C3=A5 hvordan url'en er opbygget og i disse eksempler er tilf=C3=B8= jet eksempler p=C3=A5 de obligatoriske parametre.
Hvordan du skal skrive de obligatoriske parametre er ikke ensrettet p=C3= =A5 tv=C3=A6rs af registrene og det er derfor vigtigt, at du opbygger url'e= n p=C3=A5 baggrund af oplysningerne i servicekataloget for den metode, som = du er interesseret i at benytte.
For hver ikke-obligatorisk parameter er der en default v=C3=A6rdi. Hvis = parameteren udelades i et kald til en tjeneste, s=C3=A5 benytter tjenesten = default v=C3=A6rdien for parameteren ved behandling af kaldet.
I de registerspecifikke servicekataloger er angivet default v=C3=A6rdier= for hvert enkelt parameter.
Webservices kan i Datafordeleren konfigureres til at kr=C3=A6ve kvitteri= nger fra anvenderen.
Alle foresp=C3=B8rgsler til en webservice vil returnere en response-head= er med kvitteringsID (receipt id) og kaldet DataDistributor.ReceiptId.
For at kvittere for data skal du sende en POST anmodning til kvitterings= servicen.
https://<endpoint>.datafordeler.dk/system/receipt/1/rest?userna=
me=3Dxxx&password=3Dyyy
med en request body der ser ud som (json eksempel):
{ "ReceiptId":"zzz" }
hvor =E2=80=9Czzz=E2=80=9D angiver kvitteringsID.
Det skal bem=C3= =A6rkes, at dette afsnit beskriver anvendelse af Datafordelerens egen Token= Server, og det ikke er den f=C3=A6llesoffentlige Token service fra NemLog-= in (Nemlog-in STS - Security Token Service).
For at benytte = SAML2 autentifikation skal du anskaffe en SAML2 token fra Token server= en og tilf=C3=B8je denne token til autentifikationsheaderen i dit kald= .
F=C3=B8lgende eksempel viser hvordan det er gjort i C#.NET, hvor tje= nestebrugerens brugernavn er erstattet med xxx og adgangskode med yyy.
string ADFS_URL =3D "https://fs.datafordeler.dk/adfs/services/trust= /13/usernamemixed"; string REALM =3D "urn:dk:kmd:dd:value:sp:switchboard:knownuser"; string USER_NAME =3D "dfdprod01.sys\\xxx"; string PASSWORD =3D "yyy"; Uri BASE_ADDRESS =3D new Uri("https://services.datafordeler.dk"); string REQUEST_URI=20 =3D "/GeoDK/topo_skaermkort/1/wms/?service=3DWMS&version=3D1.3.0&LA= YERS=3Ddtk_skaermkort&FORMAT=3DIMAGE/PNG&REQUEST=3DGetMap&STYLE= S=3D&CRS=3DEPSG:25832&WIDTH=3D800&HEIGHT=3D545&BBOX=3D19636= 4,5952066,923636,6447934&hest100=3D10"; //Get SAML2 token GenericXmlSecurityToken saml2Token; =20 using (var factory =3D new WSTrustChannelFactory( new UserNameWSTrustBinding(SecurityMode.TransportWithMessageCredential), new EndpointAddress(ADFS_URL)) { factory.TrustVersion =3D TrustVersion.WSTrust13; =20 factory.Credentials.UserName.UserName =3D USER_NAME; factory.Credentials.UserName.Password =3D PASSWORD; =20 RequestSecurityToken rst =3D new RequestSecurityToken { RequestType =3D RequestTypes.Issue, AppliesTo =3D new EndpointReference(REALM), KeyType =3D KeyTypes.Bearer, TokenType =3D "urn:oasis:names:tc:SAML:2.0:assertion", }; =20 IWSTrustChannelContract channel =3D factory.CreateChannel(); saml2Token =3D channel.Issue(rst) as GenericXmlSecurityToken; } =20 //Convert token string saml2TokenBase64 =3D=20 Convert.ToBase64String( System.Text.Encoding.UTF8.GetBytes(saml2Token.TokenXml.OuterXml.ToCharA= rray())); =20 //request a resource with the token=20 HttpClient client =3D new HttpClient(); client.DefaultRequestHeaders.Authorization=20 =3D new AuthenticationHeaderValue("Bearer", saml2TokenBase64); client.BaseAddress =3D BASE_ADDRESS; HttpResponseMessage httpResponseMessage =3D await client.GetAsync(REQUEST_U= RI);
Datafordeleren returnerer standard http statuskoder.