Etablering af lokal kopi af Danmarks adresser
Leder du efter den gamle replikerings-guide, hvor der benyttes sekvensnumre? Den kan stadig tilgås her.
DAWA udstiller en lang række data i et format, der gør det nemt at etablere en lokal kopi af data. En lokal kopi kan etableres ved at hente et udtræk. Herefter kan den lokale kopi vedligeholdes ved at hente de hændelser, som er indtruffet siden udtrækket blev dannet.
DAWA tilbyder en reference-implementation af en replikeringsklient.
DAWA indlæser data i transaktioner. Hver transaktion tilknyttes et unikt, fortløbende nummer kaldet transaktions-ID'et for transaktionen. DAWA udfører transaktionerne atomisk, dvs. at enten er en transaktionen med i et udtræk eller intet er med. Dette sikrer at data er konsistente, eksempelvis at en adgangsadresse og dens tilknytninger oprettes og slettes i den samme transaktion.
Udtræk og hændelser er tilknyttet en transaktion. Udtrækket for en given transaktion er et "snapshot" af hvordan data så ud umiddelbart efter denne transaktion, dvs. uden de ændringer som efterfølgende transaktioner har medført. Hændelser er tilknyttet den transaktion, som foretog den ændring, som hændelsen afspejler.
Når klientsystemer etablerer en lokal kopi kan transaktionerne anvendes til at sikre, at den lokale kopi også er konsistent. Dette gøres ved at sikre, at alle de udtræk klienten henter er er tilknyttet samme transaktions-ID. Klienten gemmer udtrækkene samt transaktions-ID. Den lokale kopi indeholder således de data, som DAWA indeholdte umiddelbart efter transaktionens udførelse.
Når DAWA herefter udfører yderligere transaktioner har klienten brug for at opdatere den lokale kopi. DAWA udstiller metadata omkring de udførte transaktioner. Klienten kan derfor hente en liste over transaktioner, som er gennemført af DAWA siden klienten etablerede den lokale kopi. Klienten kan opdatere den lokale kopi ved at hente og udføre de hændelser, som er indtruffet i de efterfølgende transaktioner.
Hver hændelse i DAWA er ligeledes tilknyttet et fortløbende sekvensnummer. Tidligere versioner af DAWA udstillede ikke transaktions-ID'er - i stedet anvendes sekvensnumre. Vi anbefaler, at nye klienter anvender transaktions-ID'er og ikke sekvensnumre.
DAWA udstiller data i et normaliseret format. Det betyder, at data i videst mulige omfang ikke er gentaget. For eksempel indeholder adgangsadresser ikke et vejnavn, da vejnavnet er indeholdt i vejstykket.
Etablering af et udtræk består overordnet set af nedenstående trin.
Det er ønskværdigt, at udtrækkene for de forskellige entiteter er konsistente. Dette sikres ved at anvende samme transaktions-ID for de forskellige udtræk. Det mest hensigtsmæssige er at anvende transaktions-ID for den senest udførte transaktion:
GET https://api.dataforsyningen.dk/replikering/senestetransaktiontxid) for den seneste transaktion som DAWA
har udført.Hent et udtræk for hver entitet der ønskes en lokal kopi for. txid-parameteren
anvendes, således det sikres at udtrækkene er konsistente med hinanden. For basale adressedata
er det nødvendigt at hente adgangsadresser, adresser, vejstykker og postnumre:
GET https://api.dataforsyningen.dk/replikering/udtraek?entitet=adgangsadresse&txid=123123
GET https://api.dataforsyningen.dk/replikering/udtraek?entitet=adresse&txid=123123
GET https://api.dataforsyningen.dk/replikering/udtraek?entitet=vejstykke&txid=123123
GET https://api.dataforsyningen.dk/replikering/udtraek?entitet=postnummer&txid=123123Man skal altid benytte seneste transaktions-id når der hentes udtræk. Det giver ikke mening at hente gamle udtræk.
Udtræk og transaktions-ID gemmes lokalt. Det er vigtigt også at gemme transaktions-ID, da dette anvendes når den lokale kopi efterfølgende skal opdateres.
Hvordan udtræk helt gemmes afhænger af hvilken database der anvendes. Replikerings-API'et udstiller en normaliseret datamodel, som er velegnet til at at gemme i en SQL-database, hvor der anvendes en tabel pr. entitet.
En lokal kopi kan opdateres ved hjælp af DAWAs hændelses-API. Hændelses-API'et udstiller information om hvilke ændringer af data der er udført er blevet. En ændring er enten en oprettelse (insert), en opdatering (update) eller en sletning (delete).
Alle hændelser er tilknyttet et transaktions-ID, og kan fremsøges ud fra dette. Forud for opdateringen af den lokale kopi har klienten gemt transaktions-ID for de udtræk klienten har indlæst. For at opdatere den lokale kopi skal klienten altså hente og udføre alle hændelser med et større transaktions-ID.
Klienten starter med at hente seneste metadata for seneste transaktion:
GET https://api.dataforsyningen.dk/replikering/senestetransaktionKlienten kan vælge at indlæse begge transaktioner på én gang, eller klienten kan vælge at indlæse hver transaktion enkeltvis. I eksempelt her indlæser vi transaktionerne enkeltvist. Først hentes metadata for den næste transaktion der skal indlæses, som har transaktions-ID 123124:
GET https://api.dataforsyningen.dk/replikering/transaktioner?txid=123124GET https://api.dataforsyningen.dk/replikering/haendelser?entitet=adgangsadresse&txid=123124
GET https://api.dataforsyningen.dk/replikering/haendelser?entitet=adresse&txid=123124Herefter udføres de ændringer som hændelserne angiver på den lokale kopi. Hvis der anvendes en transaktionel database vil det være hensigtsmæssigt at gøre det i én transaktion, så data altid er indbyrdes konsistente.
Det anbefales, at man i replikerings-klienten implementerer support for, at lokale data også kan opdateres ved at lave et nyt, komplet udtræk, som kan benyttes hvis der af en eller anden grund opstår en fejl i den inkrementielle opdatering.
DAWA stiller hændelser til rådighed i minimum et år. Forsøg på at hente hændelser som er ældre end et år kan resultere i en fejl 400.
Replikerings-API'et udstiller en maskinlæsbar datamodel. Denne datamodel kan benyttes i implementationen af replikerings-klienter. Den indeholder information om hvilke entiteter der findes, hvilke attributter de har, og hvad typerne er på attributterne. Reference-implementationen af en replikerings-klient er baseret på den maskinlæsbare datamodel.
Visse entiteter indeholder store geometrier. Det kan være regioner, kommuner eller steder.
Disse geometrier er ikke indlejrede i udtræk og hændelser. I stedet er der en URL der peger på geometrien.
Det fremgår af datamodellen hvilke geometri-attributter
der potentielt kan have referencer i stedet for indlejrede geometrier.
Disse attributter har angivet "offloaded": true.
Hvis en attribut ikke er indlejret, så er værdien af attributten et objekt der har en $url property.
Replikerings-klienten skal hente den URL der er angivet i $url for at få fat i geometrien.
Bemærk, at attributter der har i datamodellen har angivet "offloaded": true kan indeholde
både offloadede og ikke-offloadede rækker.
DAWA garanterer ikke referentiel integritet. F.eks. er det muligt at der kan være oprettet adresser med en vejkode og kommunekode, som endnu ikke refererer til et vejstykke.
Adressedata opdateres i nær-realtid. Hændelserne udstilles typisk 1-2 minutter efter at ændringen er udført i DAR. Relaterede data, så som stednavne, DAGI-tilknytninger og matrikelkortet opdateres én gang i døgnet.