- Created by Ann-Sofie Hildebrandt, last modified on Oct 29, 2024
Denne side beskriver adgangen til og den tekniske distribution af fildownload, som er gældende for alle registre på Datafordeleren, der udstiller data med fildownload.
Sideinformation
Begreber
På siderne om fildownload bruges nedenstående begreber. Bemærk at begreberne også bliver yderligere forklaret med eksempler på siderne .
Begreb | Beskrivelse |
Nuværende Datafordeler | |
Filudtræk: | Filudtræk er en metode at få udtræk af data fra Datafordeleren. Man kan som anvender logge på selvbetjeningen og oprette et abonnement på et specifikt filudtræk – evt. med brugerdefinerede parametre, hvorefter filen bliver genereret og er tilgængelig på en FTP-server. Filudtræk er beskrevet på Filudtræk på Datafordeleren. |
Moderniserede Datafordeler | |
Fildownload: | Fildownloads beskrives i denne vejledning. |
Entitet: | En entitet er en fysisk repræsentation af et registerobjekt som findes i Grunddatamodellen. De total- og deltadownloads der kan hentes fra Datafordeleren, indeholder hver især data bestående af en enkelt entitet. |
Totaldownload: | Et totaldownload er et udtræk af alle data for en enkelt entitet og refererer til en enkelt fil. |
Deltadownload: | Et deltadownload er et udtræk af alle data der har ændret sig, siden forrige deltadownload blev lavet, for en enkelt entitet. Et deltadownload består af en enkelt fil. |
Totaludtræk: | Et totaludtræk er et udtræk af alle data i et register eller en delmængde af entiteter fra et register. Et totaludtræk er udgjort at en eller flere totaldownloads. Et totaludtræk kan således bestå af en eller flere filer med tilsvarende entiteter, alt afhængigt af hvor stor en delmængde af et register der er tale om. Bemærk at denne definition kun gælder for fildownloads |
Deltaudtræk: | Et deltaudtræk er et udtræk af alle data der har ændret sig, siden forrige deltaudtræk blev lavet, i et register eller en delmængde af entiteter fra et register. Et deltaudtræk er udgjort af et eller flere deltadownloads. Et deltaudtræk kan således bestå af en eller flere filer med tilsvarende entiteter, alt afhængigt af hvor stor en delmængde af et register der er tale om. |
Om Fildownload
Fildownload er en funktionalitet på Datafordeleren til udstilling af data, men skal ikke misforstås som værende det samme som de abonnementsbaserede filudtræk, der også er på Datafordeleren. Fildownload tilbydes som prædefinerede entitetsbaserede fildownloads og baserer sig på de datamodeller som registrene har på Datafordeleren.
En entitet svarer til en tabel i Grunddatamodellen som er defineret i registrenes datamodel: https://grunddatamodel.datafordeler.dk/. En entitet kan eksempelvis være en "Adresse" fra DAR, en "Bygning" fra BBR eller et "Jordstykke" fra MAT. Det at fildownload er entitetsbaserede betyder at et fildownload indeholder data for en enkelt type af entitet. Der leveres entitetsbaserede fildownload på tabulære data og ikke for rasterdata (billeddata). Tabulære data forstås som strukturerede data der kan opbevares i tabeller, som fx adresser men ikke billedtyper som skærmkort.
Fildownload genereres løbende i bestemte intervaller for en række registre, hvorefter filerne kan hentes gennem et REST-API, der udstiller de genererede fildownloads. Det eneste krav til at hente fildownload er, at man har en tjenestebruger med brugernavn og adgangskode. Fildownload bruger ikke abonnementer, da de allerede ligger klar til at blive hentet. REST-API'et beskrives nærmere i afsnittet Sådan henter du fildownload, mens skema for generering samt frekvenser for generering beskrives nærmere i afsnittet Skema for generering af fildownload.
En opsummering hvad fildownload består af, kan ses i ovenstående figur. Figuren viser 3 registre:
- Register A, som har 5 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret og har også en enkelt reference til en entitet i register C udenfor registeret.
- Register B, som har 6 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret og har også en enkelt reference til en entitet i register A udenfor registeret.
- Register C, som har 6 entiteter. Registerets entiteter refererer til hinanden indbyrdes indenfor registeret.
Registrenes entiteter har alle fildownload, som både består af totaldownloads og deltadownloads. Det skal her bemærkes at Register C har fravalgt at der bliver genereret fildownload for deres entitet nr. 5 og 6 i dette eksempel.
Typer af fildownload
Datafordeleren udstiller flere typer af entitetsbaserede fildownload. Der findes 2 typer af fildownload, nemlig totaldownloads og deltadownloads. Datafordeleren opbevarer ét totaldownload pr. type pr. entitet, mens der opbevares deltadownloads 14 dage fra de blev genereret.
Hvis der genereres fildownload for en entitet, bliver der altid genereret både totaldownload og deltadownload. Udover at der findes flere typer af fildownloads, findes der også flere typer af filtreringer på den data som de genererede fildownloads indeholder. Dette skyldes at delmængder af data på Datafordeleren er bitemporal og at der dermed kan være flere forekomster af det samme objekt over tid i to tidsdimensioner.
- Fuldt bitemporalt fildownload: Et fuldt bitemporalt fildownload inkluderer alt, hvad angår både registreringstid og virkningstid.
- Temporalt fildownload: Et temporalt fildownload filtrerer registreringsdimensionen fra, men beholder virkningsdimensionen.
- Fildownload med aktuelle data: Både registreringstiden og virkningstiden er sat til at være på det pågældende tidspunkt fildownload blev lavet.
Det er muligt at kombinere en type fildownload med en type af bitemporal filtrering og filformat. En opsummering af, hvilke fildownloads der eksisterer kan ses i nedenstående tabel.
Type af fildownload | Type af bitemporal filtrering | Typer af filformater |
Totaldownload | Bitemporal | JSON, GML og GPKG |
Totaldownload | Temporal | |
Totaldownload | Aktuel | |
Deltadownload | Bitemporal |
Filformater
Nedenstående tabel viser, hvilke registre der har fildownload på deres entiteter, samt hvilke filformater der er tilgængelige for registrenes entiteter. Et kryds i en række i tabellen indikerer at filformatet generelt er understøttet for det givne registers entiteter.
Register | Forkortelse | JSON | GPKG | GML |
Bygnings- og Boligregistret | BBR | X | ||
Danmarks Administrative Geografiske Inddeling | DAGI | X | X | X |
Danmarks Adresseregister | DAR | X | ||
Danmarks Fikspunktregister | FIKSPUNKT | X | X | X |
Danske Stednavne | DS | X | X | X |
DHM Højdekurver | DHMhoejdekurver | X | X | X |
DHM Oprindelse | DHMOprindelse | X | X | X |
Ejendomsbeliggenhedsregistret | EBR | X | ||
GeoDanmark Vektor | GEODKV | X | X | X |
Matriklen2 | MAT | X | X | X |
Det skal bemærkes det ikke er alle entiteter for et register der har fildownloads i GPKG og GML-format, selvom dette er indikeret i tabellen. Der skal gøre sig følgende gældende for at en entitet understøttes i GPKG eller GML-format:
- GPKG-formatet understøttes på en entitet hvis entiteten indeholder 0 eller 1 geometrier.
- GML-formatet understøttes på en entitet hvis entiteten indeholder minimum 1 geometri.
Bemærk
GPKG-formatet understøttes på entiteter uden geometri for at gøre dem tilgængelige i et format, der nemt kan importeres i en database og bruges til at sammenkæde med andre entiteter og datasæt.
Bemærk
Henter du fildownload i GML-formatet indeholder zip-filen også skemafilen (XSD'en) for entiteten.
Har du brug for entitetens skemafil skal du derfor hente den i GML-formatet.
Udtræksnumre
Udtræksnumre er en fortløbende talrække der beskriver tidsmæssig sammenhæng mellem data i et register. Hver gang der genereres fildownload for et register, påsættes alle fildownload ved samme generering det samme udtræksnummer. Dette bevirker at fildownload med det samme udtræksnummer indeholder konsistente data indenfor registerets egen data. Denne egenskab er særlig relevant hvis man som anvender er interesseret i at sammensætte data fra flere entiteter i et register.
Det er her vigtigt at understrege, at udtræksnumrene kun er fortløbende per register, og at hvert register derfor har sin egen fortløbende talrække, der er uafhængig af andre registre. Udtræksnumre kan derfor ikke garantere referentiel integritet på tværs af registrenes data, da dette afhænger af registrenes indlæsningstidspunkter, samt indlæsningsfrekvens.
Sammenhæng mellem total- og deltaudtræk
Det er muligt at vedligeholde en lokal kopi af registrenes data som findes på Datafordeleren ved at hente totaludtræk – og herefter løbende hente deltaudtræk.
Kopien etableres først lokalt, ved at hente totaldownloads for den/de entiteter der er interesse for, for at skabe totaludtrækket. Idet totaludtrækket er hentet, skal det bemærkes hvilket udtræksnummer totaludtrækket har, da udtræksnummeret skal bruges til at identificere hvilke deltadownloads der er relevante at hente, for at skabe det samlede deltaudtræk der kan opdatere den initiale kopi af data. Et totaldownload og deltadownload med det samme udtræksnummer indeholder data fra samme generation. Dette betyder at deltaudtræk med samme udtræksnummer som et totaludtræk indeholder dermed ingen data som ikke også er indeholdt i totaludtrækket. Det udtræksnummer der skal bruges til at opdatere kopien af data, er dermed det næste udtræksnummer i talrækken.
Et eksempel på dette kan ses i nedenstående figur, som viser en række genererede deltaudtræk, samt et genereret totaludtræk. Hver generering har resulteret i, at der enten er blevet genereret et deltaudtræk og/eller et totaludtræk. Det kan ses på figuren, at der eksisterer både et totaludtræk, samt et deltaudtræk med udtræksnummeret 3 og 10. Såfremt det ønskes at etablere en kopi af data fra entiteten, kan totaludtrækket med udtræksnummeret 3 først hentes – og så herefter hente deltaudtrækkene med udtræksnummer 4, 5 og 6 for at vedligeholde datakopien. Det er således ikke nødvendigt at hente deltaudtrækket med udtræksnummer 3, da deltaudtrækket blev genereret på samme tid som totaludtrækket.
Spring i udtræksnumre
Dette afsnit er særligt relevant for anvendere, der implementerer programmel, som anvender udtræksnumre til at indhente fildownload automatisk. Der kan i sjældne tilfælde forekomme et spring i udtræksnumre. Dette skyldes, at der eksisterer et nyere udtræksnummer for det pågældende register, og at generering af fildownload, derfor, vil bruge det nyere udtræksnummer for at sikre konsistente data inden for registeret.
Processen for indhentning af deltaudtræk bør, på baggrund af ovenstående, følge følgende logik:
- Tjek hvilket udtræksnummer der er påsat senest indhentede deltaudtræk.
- Indhent deltaudtræk med udtræksnumre der er større end det sidst indhentede deltaudtræks udtræksnummer.
- Dette sikrer at alle nyere deltaudtræk altid hentes uden at der springes nogle over, selvom der sker spring i udtræksnummeret på deltaudtrækkene.
Navngivning af fildownload
De fildownload der genereres på Datafordeleren følger alle en navnestandard, der hjælper med at beskrive hvad indholdet af filen er. Navnestandarden ser ud som set på nedenstående figur.
Et fildownload som følger navnestandarden kan derfor eksempelvis have navn som følgende:
- DAR_V1_Adresse_TotalDownload_JSON_Bitemporal_10.zip
- DAR_V1_Adresse_DeltaDownload_JSON_Bitemporal_11.zip
- BBR_V1_Bygning_TotalDownload_JSON_Temporal_123.zip
- MAT_V1_Lodflade_TotalDownload_GPKG_Current_7.zip
- DAGI_V1_Kommuneinddeling_TotalDownload_GML_Current_42.zip
Man kan ud fra navngivningen af ovenstående fildownload udlede følgende:
- Fildownload nr. 1 indeholder et fuldt bitemporalt totaldownload af Adresse-entiteten som ligger i DAR. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Filen har udtræksnummer 10.
- Fildownload nr. 2 indeholder et fuldt bitemporalt deltadownload af Adresse-entiteten som ligger i DAR. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Deltafilen har udtræksnummer 11 og ville derfor indeholde alle ændringer der var sket for Adresse-entiteten siden udtræksnummer 10. Denne deltafil ville derfor kunne bruges til at opdatere en datakopi der havde indlæst fildownload nr. 1, som har udtræksnummer 10.
- Fildownload nr. 3 indeholder et temporalt totaldownload af Bygning-entiteten som ligger i BBR. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en JSON-fil. Filen har udtræksnummer 123.
- Fildownload nr. 4 indeholder et totaldownload med aktuelle data af Lodflade-entiteten som ligger i MAT. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en GPKG-fil. Filen har udtræksnummer 7.
- Fildownload nr. 5 indeholder et totaldownload med aktuelle data af Kommuneinddeling-entiteten som ligger i DAGI. Filen der downloades er en ZIP-fil, men ZIP-filen indeholder en GML-fil. Filen har udtræksnummer 42.
Generering af fildownload
Skemaet nedenfor viser, hvornår der genereres fildownload for registrene på Datafordeleren. Bemærk at et register kan have frabedt sig at få genereret fildownload for bestemte entiteter i deres datamodel og vil således ikke blive genereret efter skemaet. Lige så snart et fildownload er genereret, vil det være tilgængeligt igennem REST-API'et, som udstiller fildownload. REST-API'et beskrives nærmere i afsnittet Sådan henter du fildownload.
Register | Type af fildownload | Genereres hvornår (mellem kl. 3 og 6 om natten) |
EBR | Totaldownload | Lørdag |
DAR | Totaldownload | Lørdag |
BBR | Totaldownload | Lørdag |
MAT | Totaldownload | Søndag |
DAGI | Totaldownload | Søndag |
GEODKV | Totaldownload | Søndag |
DS | Totaldownload | Mandag |
DHMOprindelse | Totaldownload | Mandag |
DHMHoejdekurver | Totaldownload | Mandag |
FIKSPUNKT | Totaldownload | Mandag |
Alle registre | Deltadownload | Hver nat |
Såfremt, at der genereres et deltadownload, men der ikke er sket dataændringer siden sidste gang, hvor der blev genereret et deltadownload for en pågældende entitet, vil deltadownloadet være tomt.
Hvis der genereres et totaldownload uden at der er sket dataændringer siden sidste gang, det blev genereret, vil det nye totaldownload i JSON-, GML- eller GPKG-format have et ældre udtræksnummer i sit filnavn end den zip-fil den er indeholdt i.
Eksempelvis er det muligt at hente en fil med følgende navn:
- DAR_V1_Adresse_Total_JSON_Bitemporal_10.zip
Her er udtræksnummeret på ZIP-filen 10, men ZIP-filen kan godt indeholde en JSON-fil med følgende navn:
- DAR_V1_Adresse_Total_JSON_Bitemporal_9.json
JSON-filen har et lavere udtræksnummer end ZIP-filen, da der ikke er sket nogen ændringer i data siden sidste totaludtræk blev genereret for Adresse-entiteten. Såfremt der heller ikke sker nogen ændringer i Adresse-entiteten inden næste generering, vil ZIP-filen få udtræksnummer 11, mens den indeholdte JSON-fil stadig vil have udtræksnummer 9.
Hvornår slettes et fildownload på Datafordeleren
Et totaldownload slettes når følgende kriterier er opfyldt:
- Udløbsdatoen (ExpirationDate) er overskredet, og
- en nyere version af samme "gruppe" af totaldownload er tilgængelig til anvendere.
"Gruppe" referer til alle filer, som er samme version, entitet, replikeringskanal, datatype og format. Totaldownload bliver grupperet for at sikre, at der altid er et tilgængelig totaldownload for alle totaldownloadsgrupper, hvis der ikke er genereret et nyt totaldownload før et download er udløbet.
Et deltadownload slettes hvis:
- Udløbsdatoen (ExpirationDate) er overskredet
Deltadownload bliver genereret dagligt og opbevares i 14 dage, hvorefter de bliver slettet.
Sådan henter du fildownload
Fildownload på Datafordeleren tilgås via et REST-API. Dette afsnit beskriver, hvordan det vil være muligt at danne et overblik over hvilke fildownload du kan kan hente, samt hvorledes relevante fildownload herefter hentes. REST-API'et indeholder to metoder som kan kaldes. REST-API'et kræver at du først har oprettet en tjenestebruger med brugernavn og password.
Ovenstående figur viser hvordan REST-API'et overordnet set anvendes. Her kaldes metoden "GetAvailableFileDownloads" først for at danne et overblik over mulige filer der er tilgængelige, hvorefter relevante filer hentes, ved at kalde metoden "GetFile".
Metode: GetAvailableFiledownloads
Metode: GetAvailableFiledownloads | |
URL | https://<env>-api.datafordeler.dk/FileDownloads/GetAvailableFileDownloads? |
HTTP-metode | GET |
Headere i forespørgsel | Content-Type: application/json |
Format | JSON |
Returværdier |
|
Adgang | Tjenestebruger med brugernavn og password |
Dato- og tidsformat | Datoformat følger ISO 8601 Tidszonen er UTC |
Parametre
Navn | Type | Beskrivelse | Valgfri |
Register | String | Begrænser responsen til kun at indeholde fildownloads fra det angivne register. Følgende registre kan angives:
| Ja |
Version | String | Begrænser responsen til kun at indeholde fildownloads der er i den angivne version. Parameteret kan kun angives hvis "Register" parameteret er angivet. | Ja |
Entity | String | Begrænser responsen til kun at indeholde fildownloads der er af samme type som den angivne entitet. Parameteret kan kun angives hvis "Register" parameteret er angivet. | Ja |
Returværdier
Metoden returnerer metadata om fildownloads, der følger strukturen beskrevet i følgende tabel. Der er ikke nogen sortering defineret, så resultater optræder i tilfældig rækkefølge.
Felt | Beskrivelse |
Filename | Navnet på filen som kan downloades. |
Register | Angiver hvilket register data i filen tilhører. |
EntityName | Angiver navnet på registerentiteten som filens data tilhører. |
Frequency | Angiver hvornår/hvor ofte der bliver genereret en ny fil af samme type med nyt udtræksnummer. |
TypeOfDownload | Angiver om filen er et totaldownload eller et deltadownload. |
TypeOfData | Angiver hvilken bitemporal filtrering der er anvendt på data i filen. Denne kan enten være "Bitemporal", "Temporal" eller "Current". |
Version | Angiver underlæggende version af filens data. |
GenerationNumber | Angiver udtræksnummeret. |
PointInTime | Angiver tidspunkt for registrerings- og virkningstid der blev anvendt ved generering af fildownload. Feltet er kun sat hvis der er tale om et deltadownload eller et Temporalt eller Current totaldownload. Datoformat følger ISO 8601 Tidszonen er UTC |
GenerationTime | Angiver tidspunktet for hvornår filen blev genereret. Datoformat følger ISO 8601 Tidszonen er UTC |
ExpirationDate | Angiver hvornår filen ikke længere udstilles på Datafordeleren. Datoformat følger ISO 8601 Tidszonen er UTC |
ContainedFileFormat | Angiver hvilket filformat ZIP-filen indeholder. |
OutputFileFormat | Angiver filformatet på selve filen som kan downloades. |
Eksempler på brug af metoden
Se tilgængelige fildownloads for DAGI:
Se tilgængelige fildownloads for "Bygning"-entiteten:
Se tilgængelige fildownloads i version 1 i EBR:
Metode: GetFile
Metode: GetFile | |
URL | https://<env>-api.datafordeler.dk/FileDownloads/GetFile? |
HTTP-metode | GET |
Headere i forespørgsel | Content-Type: application/json |
Format | JSON |
Returværdier |
|
Adgang | Tjenestebruger med brugernavn og password. |
Dato- og tidsformat | Datoformat følger ISO 8601 Tidszonen er UTC |
Parametre
Navn | Type | Beskrivelse |
---|---|---|
Filename | String | Specificerer en specifik fil til download. Dette parameter kan kun angives alene. |
Register | String | Specificerer, hvilket register der ønskes download fra. Hvis ikke parametrene 'LatestTotalForEntry' og 'Type' angives, bliver alle registerets totaldownloads downloadet.
|
LatestTotalForEntity | String | Henter det seneste totaldownload for den specificerede entitet. 'Type' parameteret skal angives, såfremt dette parameter er angivet. |
Type | String | Angiver hvilken type fildownload der skal downloades for entiteten. 'LatestTotalForEntity' parameteret skal angives, såfremt dette parameter er angivet. |
Format | String | Angiver hvilket filformat der ønskes. Hvis 'LatestTotalForEntity' parameteret er angivet, skal dette parameter også angives. |
Version | String | Angiver hvilken version fildownloadet skal være i. Såfremt dette parameter ikke angives, vælges den nyeste version. |
Returværdier
Denne metode returnerer altid en eller flere filer ved HTTP 200 - OK.
Eksempler på brug af metoden
Hent en specifik deltafil fra Danske Stednavne registeret:
Kaldet returnerer en enkelt fil i en ZIP-fil.
Hent totaldownloads for alle entiteter i BBR:
Kaldet returnerer flere filer i en samlet ZIP-fil.
Hent totaldownload med aktuelle data i GML-format for en bestemt entitet i Fikspunkt-registeret:
Kaldet returnerer en enkelt fil i en ZIP-fil.