...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
...
Tabel 3: Oversigt over registre med adgangsbegrænsede data.
...
...
...
...
...
...
...
...
...
...
...
...
Datatyper
...
Understøttede operatorer
...
...
...
...
...
...
...
Boolean
...
...
...
...
Datatyper | Understøttede operatorer | PostGis Link |
Geometri | contains(koordinatsystem, geometri) | https://postgis.net/docs/ST_Contains.html |
| covers(koordinatsystem, geometri) | https://postgis.net/docs/ST_Covers.html |
| coveredBy(koordinatsystem, geometri) | https://postgis.net/docs/ST_CoveredBy.html |
| crosses(koordinatsystem, geometri) | https://postgis.net/docs/ST_Crosses.html |
| intersects(koordinatsystem, geometri) | https://postgis.net/docs/ST_Intersects.html |
| within(koordinatsystem, geometri) | https://postgis.net/docs/ST_Within.html |
| overlaps(koordinatsystem, geometri) | https://postgis.net/docs/ST_Overlaps.html |
| touches(koordinatsystem, geometri) | https://postgis.net/docs/ST_Touches.html |
...
Geometrisk operator | Omvendte operator |
contains | within |
covers | coveredBy |
coveredBy | covers |
crosses | Ingen. crosses er symmetrisk |
intersects | Ingen. intersects er symmetrisk |
within | contains |
overlaps | Ingen. overlaps er symmetrisk |
touches | Ingen. touches er symmetrisk |
...
Point POINT (3 5) Line LINESTRING (6 4, 8 2, 7 1) Polygon POLYGON (1 1, 3 3, 4 2, 4 0, 1 1) |
...
Der er to typer queries, som man kan udføre på bitemporale data:
- Interval-queries, hvor man ønsker data, der er bitemporalt gyldige i en bestemt tidsperiode.
- Point-in-time-queries, hvor man ønsker bitemporalt gyldige data pr. deres angivne tidspunkt.
...
Alle registre der understøtter bitemporal filtrering, understøtter filtrering på både virkningstidspunkt og registreringstidspunkt bortset fra CVR. CVR er det eneste register, hvor anvendere ikke kan specificere et registreringspunkt i deres query. For CVR sættes registreringstidspunktet derimod altid til tidspunktet for forespørgslen, dvs. "registreringstid = NOW()". Det er muligt at filtrere på virkningstidspunktet på sædvanlig vis.
...
GraphQL-tjenesterne understøtter paging af resultater. At resultaterne pagineres vil sige at resultaterne inddeles i "sider" og returneres én ad gangen. Anvendere vil således få én side returneret ad gangen og kan efterfølgende lave et nyt kald for at få næste side for på den måde at gennemgå hele datasættet.
Pagingen er cursor-baseret, hvilket vil sige at der returneres en reference, en såkaldt cursor, til første og sidste resultat (for edges ved hvert enkelt resultat) i det returnerede datasæt ved hvert kald. Denne cursor kan derefter bruges til at hente flere sider ved at anmode om mere data fra cursorens værdi. I praksis kan anvendere bruge cursor-værdien i en efterfølgende query, til at hente den næste side af data, startende fra den position, der er angivet ved den pågældende cursor. Paging er implementeret således at flere identiske anmodninger ved hjælp af den samme cursor vil returnere de samme data, forudsat at registrene ikke opdaterer de underliggende data i mellemtiden.
Paging er udelukkende implementeret som fremadgående paging. Det vil sige, at anvenderne kan hente den næste side af resultater fra en given cursor. Bagudgående paging understøttes ikke.
...
Paging består af tre datastrukturer: PageInfo samt nodes eller edges.
PageInfo indeholder metadata om den nuværende paging og består af følgende felter:
- hasNextPage: Dette felt angiver, om der er endnu en side med resultater.
- hasPreviousPage: Dette felt angiver, om der eksisterer en forrige side med resultater. Da vi ikke understøtter bagudgående pagination, er dette altid sat til false.
- startCursor: Dette felt er en cursor, der peger på det første datapunkt i resultatdatasættet.
- endCursor: Dette er en cursor, der peger på det sidste datapunkt i resultatsættet. Denne cursor kan bruges af anvenderen til at hente den næste side af data.
Mens metadata kan hentes via PageInfo, kan data hentes enten som en liste af nodes eller en liste af edges. Nodes og edges adskiller sig på følgende måde:
- I resultatsættet er nodes en liste af datapunkter.
- I resultatsættet er edges en liste af datapunkter med et ekstra metadatafelt: Cursoren, der matcher hver datapunkt.
Det anbefales, at anvendere benytter nodes til standard paginganmodninger, da PageInfo-metadataene er tilstrækkelige. Hvis anvenderne har brug for at paginere fra en hvilken som helst position på den aktuelle side og ikke fra slutningen af den aktuelle side, skal edges benyttes.
Det er tilladt for anvendere at specificere i deres GraphQL-queries, at de ønsker både nodes og edges returneret. Dette frarådes, da resultatsættet vil indeholde de samme data to gange.
...
Paging har to inputargumenter, der kan specificeres i en query:
- first: Dette argument angiver hvor mange resultater anvenderen ønsker returneret. Dette er sidestørrelsen og skal være et ikke-negativt tal. Hvis dette argument udelades fra query'en, returneres standardantallet af resultater.
- after: Dette argument angiver cursoren til det første datapunkt i det resulterende datasæt. Hvis dette argument udelades fra query'en, returneres den første side.
Hvis anvenderen angiver ugyldige værdier for nogen af disse argumenter, vil tjenesterne returnere en fejlmeddelelse, der informerer dem om, at de har angivet ugyldige pagingargumenter.
Standardantallet af resultater, der returneres hvis brugeren ikke har angivet en første værdi, er 100. Den maksimalt tilladte sidestørrelse er 1000, og hvis værdien af first er større end den maksimalt tilladte sidestørrelse returneres en fejlmeddelelse.
...
| Wiki Markup |
|---|
*"nodes": \[* |
...
...
...
I GraphQL-tjenesterne versioneres hvert register separat, og alle entiteter, der tilhører det samme register, versioneres under det samme versionsnummer som registret. Det vil sige, at DAR og BBR kan eksistere separat som DAR/v2 og BBR/v5. Men hvis BBR har en change til Bygning-entiteten i deres datamodel, vil alle entiteter i BBR blive opgraderet til BBR/v6, og BBR/v5 vil derefter efter en overgangsperiode blive udfaset.
...
Som en sikkerhedsforanstaltning og af performance-hensyn tilskrives hver query en cost. En cost er en beregnet talværdi der indfanger hvor kompleks og omkostningstung en given query er for Datafordeleren at processere. Costen udregnes inden en query processeres, hvorefter den pågældende query enten sendes videre i systemet eller bliver afvist hvorved anvenderen vil modtage en fejlmeddelselse der informerer om at query'en var for kompleks.
Udregningen af cost er blandt andet baseret på følgende specifikationer:
- Sidestørrelse: Størrelse på paging-siderne der returneres. Jo større sider, jo mere data returneres, hvilket giver en højere cost.
- Filtre: Antallet og type af filtre der benyttes i en query påvirker også costen. Jo flere filtre, jo højere cost. Derudover er geometri-filtre mere omkostningstunge og resulterer defor i en højere cost. Se evt. afsnit 2.4, 2.5 og 2.6 for en oversigt over de forskellige typer af filtre.
- Entiteter: Almindelige og store entiteter har forskellige omkostninger associeret med dem. Store entiteter er mere omkostningstunge end mindre entiteter.
- Felter: Forskellige typer felter har forskellige omkostninger. Geometrier og sammensatte Et sammensat felt er et felt der indeholder andre felter. felter er dyrere end almindelige felter.
Som anvender skal man ikke tage stilling til hvor omkostningstung en query er så længe den ikke overstiger den maksimale cost, i hvilket tilfælde den pågældende query vil blive afvist med en fejlbesked.
...
Hent Schema
Hent Schema |
|
URL | https://graphql.datafordeler.dk/<register>/<version>/schema |
HTTP-metode | GET |
Headere i forespørgsel | Content-Type: application/json |
Returværdier |
|
Adgang | Tjenestebruger med brugernavn og password, IT-system med API-nøgle, OAuth Shared Secret eller OAuth Certifikat. |
Parametre
Navn | Type | Beskrivelse | Obligatorisk? |
Register | String | Angiver hvilket register det pågældende skema skal hentes for.
| Ja |
Version | String | Angiver hvilken version af datamodellen det pågældende register skal være. | Ja |
Returværdier
Denne tjeneste returnerer altid en fil ved HTTP 200 – OK. Filen indeholder et GraphQL-schema med metadata om GraphQL-tjenesten, der beskriver hvilke entiteter der findes for det pågældende register og hvordan data fra disse hentes.
Eksempler på brug af tjenesten
Hent skema for DAGI med versionsnummer v2 ved brug API-nøgle:
Send query
...
Send query
...
...
URL
...
https://graphql.datafordeler.dk/<register>/<version>
...
HTTP-metode
...
GET & POST
...
Headere i forespørgsel
1) Åben Postman og klik på ”Collections” i venstre side. Collections er en folder/mappe med et bestemt navn, hvor du kan samle alle dine queries til Datafordeleren og eventuelt navngive dem efter behov.
For at oprette en collection trykker du på ”+” ikonet og vælger ”Blank collection”. Derefter kan du i toppen navngive din collection.
2) Når en collection er oprettet, kan du oprette en request ved at højreklikke på sin collection eller trykke på de 3 prikker og derefter vælge ”Add request”.
Her kan du også navngive din request efter behov.
3) Når requesten er oprettet kan du i HTTP metoden vælge GET, hvis du vil hente et GraphQL-skema, eller POST hvis du vil sende en query.
Dette eksempel tager udgangspunkt i en POST request med OAuth-credentials til BBR.
I feltet til URL’en kan du indsætte https://graphql.datafordeler.dk/BBR/v1 for at kunne lave queries til BBR-version 1.
4) Vælg requesten i venstre side (hvis den ikke allerede er aktiv som i det forrige trin) og klik på ”Authorization” for at skifte til en anden fane. Her skal du vælge ”OAuth 2.0” i ”Auth Type” menuen.
Postman skulle gerne skifte indholdet når du har valgt en ny auth type.
5) Du skal herefter scrolle ned i den aktive ”Authorization” fane indtil du kan se en ”Configure New Token” overskriften.
Under overskriften vil der være en række felter som skal udfyldes som beskrevet herunder.
- I ”Token Name” kan du give din Access Token et passende navn.
- I ”Grant type” menuen skal du vælge ”Client Credentials”. Her vil Postman ændre felterne under med dem som relevant for din konfiguration af OAuth.
- I ”Access Token URL” skal du indsætte følgende link - https://auth.datafordeler.dk/realms/distribution/protocol/openid-connect/token
- I ”Client ID” skal du indsætte det Client ID som de har modtaget efter at have oprettet det i OAuth sektionen på Datafordeler Administration.
- I ”Client Secret” skal du indsætte den Shared Secret som du har modtaget efter at have oprettet det i OAuth sektionen på Datafordeler Administration.
- Anvenderen kan ignorere ”Scope” feltet, men skal verificere at ”Client Authentication” feltet er sat til ”Send as Basic Auth header”.
6) Efter du har udfyldt de nødvendige felter, kan du hente dit Access Token ved at rulle ned indtil du ser en orange knap der hedder ”Get New Access Token” og klikke på den.
Derefter vil Postman åbne et vindue som indikerer at applikationen er gået i gang med at hente Access Token fra Datafordeleren.
Når Access Token er hentet, vil Postman opdatere vinduet med et grønt flueben og med teksten ”Authentication complete”. Herefter kan du vente 5 sekunder eller trykke på ”Proceed” knappen i nederste højre hjørne. Herefter vil Postman åbne et nyt vindue.
7) Når Postman har åbnet det næste vindue, vil Access token og dets navn stå under ”Token Details”.
Du kan nu trykke på ”Use Token” til at bruge den til at lave queries i Postman eller kopierer access token til anden applikation.
8) Hvis du trykker på ”Use Token” vil Postman automatisk udfylde det i den request som du oprettede tidligere. Herefter kan du lukke vinduet og klikke på ”Body” fanen, efterfuldt ved at klikke på GraphQL muligheden længst til højre. Til sidst kan du skrive en GraphQL-query til BBR og indsætte det i ”Query” tekstfeltet.
9) Når du er klar til at indsende din query kan du trykke på ”Send” oppe i højre hjørne.
Herefter vil svaret fra GraphQL tjenesten blive vist i bunden.
2) Herefter skal OAuth 2.0-indstillinger opsættes for certifikatet. Gå ind under ”Authorization” i requesten, og scroll ned til ”Configure New Token”.
Under overskriften vil der være en række felter som skal udfyldes som beskrevet herunder.
a. I ”Token Name” kan du give din Access Token et passende navn.
b. I ”Grant type” menuen skal du vælge ”Client Credentials”. Her vil Postman ændre felterne under med dem som relevant for din konfiguration af OAuth.
c. I ”Access Token URL” skal du indsætte følgende link - https://auth-oces.datafordeler.dk/realms/distribution/protocol/openid-connect/token.
d. I ”Client ID” skal anvenderen indsætte det Client ID som de har modtaget efter at have oprettet det i OAuth sektionen på Datafordeler Administration.
e. Du kan ignorere ”Scope” feltet, men skal verificere at ”Client Authentication” feltet er sat til ”Send client credentials in body”.
3) Vælge ”Settings” oppe i højre hjørne:
4) Vælg herefter ”Add Certificate”.
5) Angiv herefter ”host” og certifikatet.
- Host skal være https://auth-oces.datafordeler.dk.
- PFX file skal pege på certifikatet som indeholder den private nøgle. Det er vigtigt at dette certifikat stemmer overens med det certifikat som blev uploadet inde i portalen.
- Passphrase skal stemme overens med password til certifikatet.
- Bemærk at det kan være nødvendigt at installere ”Den Danske Stat” rodcertifikatet på anvenders maskine for at maskinen stoler på det certifikat der er vedhæftet inde i Postman.
For POST-requests:
...
Body
For GET-requests:
...
Returværdier Returværdierne for HTTP-statuskoderne afhænger af hvilken Accept-header der specificeres. Disse værdier er hvis Accept-headeren ikke er angivet som beskrevet i "Headere i forespørgsel".
...
- Returnerer HTTP 200 – OK, ved succes.
- Returnerer HTTP 400 – Bad Request, ved angivelse af forkerte parametre.
- Returnerer HTTP 404 – Not Found, hvis den angivne ressource ikke kan findes.
- Returnerer HTTP 500 – Internal Server Error, hvis der er sket en ukendt fejl
...
Adgang
...
- Ikke-adgangsbegrænset data: IT-system med API-nøgle, OAuth Shared Secret eller OAuth Certifikat.
- Adgangsbegrænset data: IT-system med OAuth Shared Secret eller OAuth Certifikat og på en defineret IP-Allowlist og så skal IT-systemet have eksplicit godkendelse fra det pågældende register. Se afsnit 0 for yderligere information.
Parametre
Navn | Type | Beskrivelse | Obligatorisk? |
Register | String | Angiver hvilket register det pågældende skema skal hentes for.
| Ja |
Version | String | Angiver hvilken version af datamodellen det pågældende register skal være. | Ja |
Returværdier
Denne tjeneste returnerer et json-response ved HTTP 200 – OK.
Eksempler på brug af tjenesten
Hent de første 100 datapunkter fra entiteten DAR_Adresse fra version 1 af DAR ved at sende nedenstående query ved brug af API-nøgle til endepunktet:
...
...