Page tree
Skip to end of metadata
Go to start of metadata


Siden giver en introduktion til og vejledning i, hvordan man kan anvende webservices som udstilles på Datafordeleren.

Gå til Guide til webservice på Selvbetjeningen (REST) , hvis du har brug for helt konkrete anvisninger til at bruge en webservice fra Datafordeleren.






Servicetyper

Webservices giver anvenderne mulighed for at hente data ved at kalde en service.

Datafordeleren understøtter følgende servicetyper:

  • WMS Web Mapping Service
  • WFS Web Feature Service
  • WCS Web Coverage Service
  • WMTS Web Map Tile Service
  • TMS Tile Map Service
  • REST REpresentationel State Transfer
  • CSW Catalog Service for the Web (udstiller metadata)

De følgende afsnit vil primært beskrive REST-services.




Opbygning af url for en webservice

Når en webservice konfigureres genereres der automatisk en url.

Opbygningen af url’en sker ud fra følgende kriterier, som angives i forbindelse med konfigurationen af webservicen:

  • Protokol (http/https)
  • Webservicetype (REST, WFS, WMS, WMTS, WCS, TMS)
  • Webservicenavn
  • Version af webservicen

Strukturen for den genererede url sker i overensstemmelse med følgende skema:

<scheme>://<authority>/<path>/?<parameters>


Strukturen for den samlede url sker i overensstemmelse med følgende skema, når<authority> og <path> bliver foldet ud:

<scheme>://<alias>.datafordeler.dk/<owner>/<service>/<version>/<metode>/?<parameters>





BESKRIVELSE AF URL-OPBYGNING


<scheme>

Afgøres af den valgte protokol og vil altid være enten http eller https.

Det anbefales ikke at sende brugernavn/adgangskode ukrypteret. Derfor bør der altid anvendes https, hvis disse sikkerhedsakkreditiver anvendes.

<authority> udgøres af følgende mønster <alias>.datafordeler.dk

  • <alias>
    Når webservicen konfigureres op i Datafordelerens testmiljø, vil <alias> blive valgt ud fra en pulje af tilgængelige aliasser, som er tilknyttet den i konfigurationen valgte webservicetype.
    Se listen over Miljøer og Portaler på Datafordeleren, som viser Datafordelerens aliasser.

<path>udgøres af følgende mønster <owner>/<service>/<version>/<metode>

  • <owner>
    Angiver hvilket register der ejer webservicen og sikrer at der tillades navnesammenfald på tjenester på tværs af registre, men ikke inden for det samme register.
  • <service>
    Angiver webservicens navn.
  • <version>
    Angiver hvilken version af webservicen der er tale om.
  • <metode> 
    Angives afhængigt af webservicetypen. Ved DAGI-tjenester kan der angives WFS eller WMS.
    For REST-service  angives der REST samt eventuelt navn på metoden fx REST/adresse, da en REST-service kan have flere metoder.

<parameters>
I slutningen af url'en angives parametre, som bliver beskrevet nærmere i det efterfølgende afsnit.





Parametre

Parametre dækker over både sikkerhedsparametre, standardparametre og tjenestespecifikke parametre.



Sikkerhedsparametre

Datafordeleren understøtter en række forskellige akkreditiver. De skal sendes med i kald til tjenester, der ikke har anonym adgang.

Brug Dataoversigten til at undersøge, hvilken brugeradgang den ønskede tjeneste kræver og læs mere om Brugeroprettelse og Brugeradgang  Datafordeler.dk.




OCES certifikater

Kald med certifikater skal ikke ske til det ”normale” endpoint, men skal gå til et separat endpoint specifikt for anvendelse af certifikater.

Url vil for webservices med certifikater i i zone 0 starter med.
https://certservices.datafordeler.dk/

Url vil for webservices med certifikater i i zone 5 starter med.
https://s5-certservices.datafordeler.dk/

Se endpoint for testmiljøerne i Listen over endpoint




Brugernavn/adgangskode

Vil du benytte brugernavn/adgangskode som akkreditiver, skal parametre inkluderes i kald til tjeneste og den samlede url vil følge dette skema:

<scheme>://<alias>.datafordeler.dk/<owner>/<service>/<version>/<metode>/?username=xxx&password=yyy


INDSÆT OPLYSNINGER I URL'EN FOR BRUGERNAVN/ADGANGSKODE

Brugernavn og adgangskode er obligatoriske parametre, hvis tjenestebrugeren er oprettet på den måde. 
Det er tjenestebrugerens brugernavn og adgangskode, som skal tilføjes.
Følgende skal tilføjes url'en for at hente hændelsesbeskeder:

xxx - skal erstattes med brugernavn for tjenestebruger
yyy - skal erstattes med adgangskode for tjenestebruger




Standardparametre

Datafordeleren understøtter en række standardparametre, som kan benyttes ved alle webservices.


Paging

Det er muligt at anvende paging for de REST-services, der er konfigureret til det.

Benytter du paging vil den samlede url følge dette skema:

<scheme>://<alias>.datafordeler.dk/<owner>/<service>/<version>/<metode>/?page=xxx&pagesize=yyy


INDSÆT OPLYSNINGER I URL'EN FOR PAGING

Følgende skal tilføjes url'en for at hente hændelsesbeskeder med paging:

xxx - skal erstattes med nummeret på den side, som du ønsker.
yyy - skal erstattes med den sidestørrelse, som du ønsker.



Count

Antal elementer i resultatsættet returneres ved at angive parameteren count i REST kald.

Benytter du count vil den samlede url følge dette skema:

<scheme>://<alias>.datafordeler.dk/<owner>/<service>/<version>/<metode>/?count=true

INDSÆT OPLYSNINGER I URL'EN FOR COUNT

Følgende skal tilføjes url'en for at hente antallet af elementer i resultatsættet:

count=true



Format

REST-servicen kan returnere data i formaterne JSON og XML.

Vælger du at specificere formatet, vil den samlede url følge dette skema:

<scheme>://<alias>.datafordeler.dk/<owner>/<service>/<version>/<metode>/?format=xxx

En anden mulighed er at sætte accept headeren til "application/json" eller "application/xml". 

INDSÆT OPLYSNINGER I URL'EN FOR FORMAT

Følgende skal tilføjes url'en for at hente hændelsesbeskeder med et bestemt format:

xxx - skal erstattes med enten json eller xml.



jsonpCallback

jsonpCallback: jsonp kan anvendes ved at angive jsonpCallback=xxx. 





Tjenestespecifikke parametre

Nogle tjenester accepterer at en parameter består af en liste af værdier.

For de REST baserede webservices er dette understøttet ved at de enkelte værdier i listen adskilles af et ”|”-tegn (pipe karakter).

Eksempel med 4 værdier i en liste til en parameter:

Værdi1|Værdi2|Værdi3|Værdi4




Kvitteringer

Webservices kan i Datafordeleren konfigureres til at kræve kvitteringer fra anvenderen.

Alle forespørgsler til en webservice vil returnere en response-header med kvitteringsID ( receipt id) og kaldet DataDistributor.ReceiptId.

For at kvittere for data skal du sende en POST anmodning til kvitteringsservicen.

https://<endpoint>.datafordeler.dk/system/receipt/1/rest?username=xxx&password=yyy

med en request body der ser ud som (json eksempel):

{ "ReceiptId":"zzz" }

hvor “zzz” angiver kvitteringsID.





Ticket

Det anbefales at anvende tickets som alternativ til brugernavn og adgangskoder, hvis en url skal overdrages til tredje part, hvor brugernavn og adgangskode ikke skal fremgår af url'en. For eksempel hvis et website vil vise et kort fra Datafordeleren.

Det skal bemærkes, at dette afsnit beskriver anvendelse af Datafordelerens egen Ticket Server, og det ikke er den fællesoffentlige Token service fra NemLog-in (Nemlog-in STS - Security Token Service).



Du kan hente en ticket ved at kalde denne service: 

https://<endpoint>/system/getticket/1/custom?service=xxx&username=yyy&password=zzz

Tilføj owner, service, version og metode samt tjenestebrugerens brugernavn og adgangskode til url'en. 

Kald url'en i din browser og du får returneret din ticket til den service, som du ønsker at kalde.

INDSÆT OPLYSNINGER I URL'EN FOR AT HENTE EN TICKET

Følgende skal tilføjes url'en for at hente en ticket

xxx - skal erstattes med <path> (<owner>/<service>/<version>/<metode>) i url'en.
yyy - skal erstattes med tjenestebrugerens brugernavn i url'en.
zzz - skal erstattes med tjenestebrugerens adgangskode i url'en.

Ticket skal erstatte brugernavn og adgangskode i url'en, når du kalder din tjeneste på følgende måde:

https://<endpoint>/<owner>/<service>/<version>/<metode>/<parameters>&ticket=ttt


INDSÆT OPLYSNINGER I URL'EN FOR AT HENTE EN TJENESTE MED TICKET

Følgende skal tilføjes url'en for at hente en tjeneste med ticket

ttt - skal erstattes med med den ticket, som du har hentet ved at kalde Ticket Serveren.


EKSEMPEL - OPSÆTNING AF TICKET TIL SKÆRMKORT


For at hente en ticket for skærmkort benyttes følgende url:

https://service.datafordeler.dk/system/getticket/1/custom?service=GeoDK/topo_skaermkort/1/wms&username=yyy&password=zzz

Her bliver xxx erstattet med <path> (GeoDK/topo_skaermkort/1/wms) i url'en, yyy bliver erstattet med tjenestebrugerens brugernavn i url'en og zzz bliver erstattet med tjenestebrugeren adgangskode i url'en.


Eksempel på url til Skærmkort med ticket:

https://service.datafordeler.dk/GeoDK/topo_skaermkort/1/wms/service=WMS&version=1.3.0&LAYERS=dtk_skaermkort&FORMAT=IMAGE/PNG&REQUEST=GetMap&STYLES=&CRS=EPSG:25832&WIDTH=800&HEIGHT=545&BBOX=196364,5952066,923636,6447934&ticket=ttt






Token

Det skal bemærkes, at dette afsnit beskriver anvendelse af Datafordelerens egen Token Server, og det ikke er den fællesoffentlige Token service fra NemLog-in (Nemlog-in STS - Security Token Service).

For at benytte SAML2 autentifikation skal du anskaffe en SAML2 token fra Token serveren og tilføje denne token til autentifikationsheaderen i dit kald.

Følgende eksempel viser hvordan det er gjort i C# .NET, hvor tjenestebrugerens brugernavn er erstattet med xxx og adgangskode med yyy.


EKSEMPEL PÅ TOKEN I C#.NET
string ADFS_URL = "https://fs.datafordeler.dk/adfs/services/trust/13/usernamemixed";
string REALM = "urn:dk:kmd:dd:value:sp:switchboard:knownuser";
string USER_NAME = "dfdprod01.sys\\xxx";
string PASSWORD = "yyy";
Uri BASE_ADDRESS = new Uri("https://services.datafordeler.dk");
string REQUEST_URI 
= "/GeoDK/topo_skaermkort/1/wms/?service=WMS&version=1.3.0&LAYERS=dtk_skaermkort&FORMAT=IMAGE/PNG&REQUEST=GetMap&STYLES=&CRS=EPSG:25832&WIDTH=800&HEIGHT=545&BBOX=196364,5952066,923636,6447934&hest100=10";


//Get SAML2 token
GenericXmlSecurityToken saml2Token;
 
using (var factory = new WSTrustChannelFactory(new UserNameWSTrustBinding(), ADFS_URL))
{
    factory.TrustVersion = TrustVersion.WSTrust13;
 
    factory.Credentials.UserName.UserName = USER_NAME;
    factory.Credentials.UserName.Password = PASSWORD;
 
    RequestSecurityToken rst = new RequestSecurityToken
    {
        RequestType = RequestTypes.Issue,
        AppliesTo = new EndpointReference(REALM),
        KeyType = KeyTypes.Bearer,
        TokenType = "urn:oasis:names:tc:SAML:2.0:assertion",
    };
 
    IWSTrustChannelContract channel = factory.CreateChannel();
    saml2Token = channel.Issue(rst) as GenericXmlSecurityToken;
}
 
//Convert token
string saml2TokenBase64 = 
    Convert.ToBase64String(
    System.Text.Encoding.UTF8.GetBytes(saml2Token.TokenXml.OuterXml.ToCharArray()));
 
//request a resource with the token 
HttpClient client = new HttpClient();
client.DefaultRequestHeaders.Authorization 
    = new AuthenticationHeaderValue("Bearer", saml2TokenBase64);
client.BaseAddress = BASE_ADDRESS;
HttpResponseMessage httpResponseMessage = await client.GetAsync(REQUEST_URI);







Statuskoder

Datafordeleren returnerer standard http statuskoder

Se listen over statuskoder