Entitetsbaserede 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 fildownload. Det eneste krav til at hente fildownload er, at man er autentificeret. Dette kan enten være i form af en tjenestebruger med brugernavn og adgangskode eller en API-key – såfremt man ikke forsøger at hente adgangsbegrænset data – eller ved en af de to OAuth autentifikationsmetoder. Læs mere om autentifikation for fildownload.
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 totaldownload og deltadownload. 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.
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 totaldownload 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 deltadownload 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.
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.
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 eller benytter en af de andre autentifikationsmetoder.
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".