Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Mindre tekstrettelse

Denne side beskriver hvordan du som anvender kan etablere et kopiregister lokalt ved at hente totaldownload og herefter vedligeholde det ved at hente deltadownload.

Der tages i dette eksempel udgangspunkt i at oprette et kopiregister bestående af én entitet fra ét register. I dette eksempel vil det være registret BBR med sin entitet Etage af typen bitemporal.

Bemærk at processen beskrevet i eksemplet kan gentages, hvis der ønskes flere entiteter for samme eller andre registre.


Table of Contents

Sideinformation

Display Metadata
hidetableheadertrue




Forudsætninger og afgrænsninger


Følgende forudsætninger og afgrænsninger gælder for at kunne følge guiden:

  • Guiden antager anvenderen har opsat en database på forhånd. I eksemplet bruges en Postgres database.
  • Guiden beskriver ikke hvordan man opsætter et batchjob som eksempelvis Windows Task Scheduler. Det antages at anvenderen selv vælger måden at gøre dette på.
  • Guiden behandler ikke opdatering af flere entiteter på én gang. Dette kan dog gøres ved at gentage processen beskrevet i guiden.
  • CVR tillader ikke man kan hente deltadownload.
  • For at få adgang til data, skal man først have oprettet en bruger i Datafordeler Administrationen med tilhørende OAuth Shared Secret. Der henvises til følgende guide: Brugeroprettelse Datafordeler Administration.

...

 

...

Version

...

0.6

...

 

...

Status

...

05 - Approved

...

 

...

Godkender

...

Kristian Jørgensen

...

© Copyright 2025 Netcompany
All rights reserved.

...

Forfatter

...

mnq@netcompany.com

...

 

Dokumenthistorik

Version

Dato

Forfatter

Status

Bemærkninger

0.1

15-05-2025

Marcus Norton Quistgaard

Udkast

 

0.2

12-06-2025

Marcus Norton Quistgaard

Udkast

Første udkast til internt review

0.3

13-06-2025

Rasmus Dupont Søgaard

Udkast

Review af første udkast

0.4

13-06-2025

Marcus Norton Quistgaard

Færdig

Review kommentarer indarbejdet og dokument er klar til review ved KDS.

0.5

05-09-2025

Marcus Norton Quistgaard

Færdig

Dokument tilrettet jf. review-møde med KDS.

0.6

2025-09-09

Simon Snabe Sørensen

Færdig

Billeder og kode eksempler er opdateret til at bruge variable navne som stemmer overens med begrebslisten.

0.6.1

2025-10-30

Kristian Jørgensen

Approved

 

...

Reference

...

Titel

...

Forfatter

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="16da7fc9-d669-4656-9e2b-3e31e7057b05"><ac:plain-text-body><![CDATA[

...

[Fildownload API

...

https://confluence.sdfi.dk/pages/viewpage.action?pageId=151999753]
]]></ac:plain-text-body></ac:structured-macro>
https://confluence.sdfi.dk/pages/viewpage.action?pageId=151999753

...

Datafordeleren

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="aeb544ca-fb0b-4001-9737-2bfa4fb05a4b"><ac:plain-text-body><![CDATA[

...

[DLS udstilling

...

https://confluence.sdfi.dk/display/DML/DLS-udstilling]
]]></ac:plain-text-body></ac:structured-macro>
https://confluence.sdfi.dk/display/DML/DLS-udstilling

...

Datafordeleren

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="427abb94-5261-457e-908f-d7754a581834"><ac:plain-text-body><![CDATA[

...

[fildownload_guide]

...

[C0200 - Brugervejledning - Transitionsguide for fildownload samt etablering og vedligeholdelse af kopiregister

...

https://goto.netcompany.com/cases/GTE1416/SDFEDDP/_layouts/15/guestaccess.aspx?guestaccesstoken=ncosLPJxKqq8cxmKFqqpIh%2foCXnaoCC%2fh0zCzwuSRmE%3d&docid=2_1b803e8c54b63481da189745363085a2b&rev=1]

...

Datafordeleren

...

]]></ac:plain-text-body></ac:structured-macro>

...

<ac:structured-macro ac:name="unmigrated-wiki-markup" ac:schema-version="1" ac:macro-id="402760b9-9e0d-4c01-90be-3fc3e87266ea"><ac:plain-text-body><![CDATA[

...

[C0200 - Portal - Anvender flow

...

https://goto.netcompany.com/cases/GTE1416/SDFEDDP/Deliverables/Change/C0200%20Portal%20-%20Anvender%20flow.docx]

...

Datafordeleren

...

]]></ac:plain-text-body></ac:structured-macro>

...

Dette dokument beskriver hvordan en anvender kan etablere et kopiregister lokalt ved at hente totaldownload og herefter vedligeholde det ved at hente deltadownloads.
Der tages i dette dokument udgangspunkt i at oprette et kopiregister bestående af én entitet fra ét register. I dette eksempel vil det være registret BBR med sin entitet Etage af typen bitemporal. Bemærk at processen beskrevet i indeværende dokument kan gentages, hvis der ønskes flere entiteter for samme eller andre registre.

...

Følgende forudsætninger og afgrænsninger gælder for at kunne følge guiden:

  • Guiden antager anvenderen har opsat en database på forhånd. I eksemplet bruges en Postgres database.
  • Guiden beskriver ikke hvordan man opsætter et batchjob som eksempelvis Windows Task Scheduler. Det antages at anvenderen selv vælger måden at gøre dette på.
  • Guiden behandler ikke opdatering af flere entiteter på én gang. Dette kan dog gøres ved at gentage processen beskrevet i guiden.
  • CVR tillader ikke man kan hente deltadownloads.
  • Wiki Markup
    For at få adgang til data, skal man først have oprettet en bruger i Datafordeler Administrationen med tilhørende OAuth Shared Secret. Der henvises til følgende guide: *\[Portal_guide\]{*}.

...






Projektsetup


I dette guideeksempel bliver der brugt et C# projekt. Til dette er der blevet opsat et regulært C# Console App Project.

...

...




NuGet pakker


Følgende NuGet pakker som ikke medfølger automatisk ved opsætning af nyt projekt skal i dette guideeksempel tilføjes vha. NuGet Package Manager Console:

  • Install-Package Microsoft.Extensions.Configuration.Json
  • Install-Package Npgsql

...




Appsettings


Opret en appsettings.json fil som indeholder Client ID og Client Secret som blev oprettet

...

og gemt under Forudsætninger og afgrænsninger.

Et eksempel kan være dette:
Image Modified

...


Sørg for appsettings-filen er med i build ved at tilføje følgende til .csproj:
Image Modified

...


Filen er i dette guideeksempel placeret følgende sted:
Image Modified

...

...






Hentning af access token til at tilgå API


For at kunne tilgå Datafordelerens API, skal der hentes en access token, som har en kortvarig holdbarhed.

Først oprettes der en metode til at hente access token ud

...

fra Client ID og Client Secret. Denne kontakter https://auth.datafordeler.dk/realms/distribution/protocol/openid-connect/token som er endpointet der bruges til at hente access token.




Bemærk at følgende blot er et eksempel på hvordan det kan implementeres.

Image Modified

...


Image Modified

...


For at kalde denne metode med brug af sine værdier fra appsettings.json, kan man eksempelvis gøre følgende:

Image Modified

...




Her er der sat op således at der bruges en ConfigurationBuilder til at hente fra appsettings.json, hvorefter ens access token gemmes i den lokale variabel

...

accessToken.






Etablering af kopiregister


Efter at have hentet en access token, kan man nu bruge denne til at hente seneste totaldownload for en entitet fra et givent register for at etablere et kopiregister. I det følgende eksempel vil vi hente totaldownload for BBR's entitet Etage.

...

...




Hentning af totaldownload


For at hente totaldownload er der i dette eksempel lavet en metode som gør følgende:

...


  1. Kald

...

  1. Datafordelerens GetFile

...

...

    1. Brug følgende parametre
      1. Register: BBR
      2. LatestTotalForEntity: Etage
      3. Type: Bitemporal
      4. Format: JSON
    2. Angiv din access token

...

    1. fra Hentning af access token til at tilgå API som Bearer token i headeren
  1. Gem indholdet lokalt og opbevar filstien i en variabel / konfigurationsnøgle.
  2. Træk indholdet fra zip-filen ud




Her fremgår et eksempel på en implementering med ovenstående logik:

Image Modified

...

...

...




Identificering af udtræksnummer


Da der kan findes opdateringer til totaldownload'et gennem efterfølgende deltadownload, skal udtræksnummeret fra totaldownload'et identificeres. Da filnavnet fra deltadownload'et slutter med et udtræksnummer kan det nemt trækkes ud vha. regular expressions.




Følgende eksempel trækker versionsnummeret ud fra filstien der blev gemt i forrige trin.

Image Modified

...

...




Gem

...

udtræksnummeret i databasen


For at gemme det senest hentede udtræksnummer mellem kørsler, vil der i dette eksempel blive oprettet en tabel i databasen til at indeholde et udtræksnummer for entiteter i et register.

Implementeringen følger denne rækkefølge:

  1. Opret forbindelse til databasen
  2. Opret tabel i databasen (hvis den ikke eksisterer) med følgende kolonner
    1. Register
    2. Entity (Entitet)
    3. Latest_generation_number (Seneste

...

    1. udtræksnummer)
    2. Primary key: (register, entity)
  1. Indsæt udtræksnummeret hentet i

...

  1. Identificering af udtræksnummer for primærnøglen.




Image Modified

...

...




Konvertering af hentet totaldownload til Data Transfer Object (DTO)


Indlæsning i databasen af den hentede entitets totaldownload, bruger følgende fremgangsmåde:

  1. Udled entitetens variabler og tilhørende typer samt opret DTO
  2. Læs filen gemt

...

  1. fra Hentning af totaldownload og konverter JSON-objekterne til DTO'erne.

...




Udledning af entitetens variable og tilhørende typer samt DTO-oprettelse


Først oprettes en DTO til BBR's entitet Etage kaldt "BBREtageDTO.cs". For at udlede variablerne samt typerne som fremgår i en entitet, kan man gøre følgende for BBR Etage eksemplet:

  1. Tilgå https://datafordeler.dk/dataoversigt/
  2. Vælg "Tjeneste: GraphQL Schema".
  3. Vælg "Bygnings- og Boligregistret (BBR)".
  4. Tryk herefter "Hent GraphQL Skema".
  5. Heri kan typer udledes.




Et eksempel på den udledte BBR Etage DTO fremgår i følgende:
Image Modified

...

...




Hjælpemetode: ReadLatestTotalOfEntityJsonFile


Følgende kodeeksempel læser filen gemt fra

...

Hentning af totaldownload og konverterer JSON-objekterne fra filen til DTO'en oprettet i

...

Udledning af entitetens variable og tilhørende typer samt DTO-oprettelse

Image Added

...

...




Indlæsning af DTO'er i databasen


For at indlæse DTO'erne i databasen er følgende fremgangsmåde implementeret:

  1. Opret en hjælpemetode som opretter tabellen for bbr_etage med de udledte variabler og typer fra

...

...

...




Hjælpemetode: EnsureTableExists

...


Hjælpemetoden

...

opretter

...

tabellen

...

for

...

bbr_etage

...

med

...

de

...

udledte

...

variabler

...

og

...

typer

...

fra Udledning af entitetens variable og tilhørende typer samt DTO-oprettelse. Her skal det også vides hvad primærnøglen er. Dette kan findes i registrets tilhørende DLS.

BBR bruger eksempelvis følgende fil, som findes i DLS’en: BBR_v2.4.1_2018.05.07_Bilag

...

26

...

-

...

Primær

...

nøgler.xlsx

...




For BBR’s Etage-entitet

...

gælder

...

følgende

...

composite-key:

...

(

...

id_lokalId,

...

registreringFra,

...

virkningFra

...

).

Image Added




Hjælpemetode: UploadDtosToDatabase


For at indsætte DTO'erne i databasen, kan man med fordel bruge COPY-metoden. Heri gennemløbes DTO'erne

...

fra Hjælpemetode: ReadLatestTotalOfEntityJsonFile og indlæses én efter én i databasen på effektiv vis.

Image Modified

...

...




Overordnet rækkefølge


Hele

...

afsnittet Etablering af kopiregister overordnede rækkefølge af kaldt funktionalitet kan ses i følgende overblik:

Image Modified

...

...

...






Vedligeholdelse af kopiregister gennem deltadownload for entitet


Efter at have hentet totaldownload'et for en entitet, holdes denne entitet opdateret vha. deltadownload. Deltadownload kommer én gang i døgnet og man kan derfor med fordel opsætte en scheduled task, som henter deltadownload dagligt og opdaterer databasens rækker for en given entitet.

Det skal her bemærkes, at da totaldownload dannes én gang om ugen, kan der allerede været kommet adskillige deltadownload siden den nyeste total man har hentet. Det anbefales derfor, at man sætter hentningen af deltadownload op med det samme.




Denne

...

del beskriver eksempler på hvordan man kan opsætte hentning af deltadownload samt opdaterer databasen med dens værdier for BBR's entitet Etage.

Det overordnede flow fremgår således:

  1. Navnene hentes på alle deltafiler som har et udtræksnummer højere end det sidst hentede totaldownload/deltadownload.
  2. Deltafilerne hentes ud fra navnene.
  3. Deltafilerne castes til DTO'er og tilføjes til databasen.
  4. Det sidste hentede generationsnummer opbevaret i databasen opdateres med generationsnummeret fra den nyeste af de deltadownloads som blev tilføjet.

...




Hentning af navne på nyeste deltafiler

...


Der

...

oprettes

...

en

...

hjælpemetode

...

som

...

henter

...

de

...

nyeste

...

fildownload

...

for

...

BBR’s entitet

...

Etage

...

vha.

...

...

,

...

for

...

derefter

...

at

...

filtrere

...

filer

...

fra,

...

...

de

...

tilbageværende

...

opfylder

...

følgende

...

kriterier:

  1. Har et generationNumber højere end det senest hentede generationsnummer
  2. typeOfDownload typen er

...

  1. ”DeltaDownload”
  2. typeOfData har bitemporaliteten

...

  1. ”Bitemporal”
  2. containedFileFormat er af typen

...

  1. ”json”
  2. Seneste version

...

  1. Dvs. at hvis der f.eks. findes både

...

  1. BBR_V1_Etage_DeltaDownload_json_Bitemporal_295.

...

  1. zip” og

...

  1. BBR_V2_Etage_DeltaDownload_json_Bitemporal_295.

...

  1. zip” vil V1 sorteres fra. Ønsker man at udstille både version 1 og version 2 osv., skal man undlade at filtrere fra her samt udvide

...

  1. DTO’en i Udledning af entitetens variable og tilhørende typer samt DTO-oprettelse til at have version med sig. Guiden her tager kun udgangspunkt i den seneste version, som i dette eksempel er V2.




Image Modified

...

...

...




Hentning af nyeste deltafiler samt indlæsning i databasen


Efter at navnene på de nye deltafiler nu er fundet og gemt i den lokale variabel newDeltas, skal filerne nu hentes, castes til DTO'er, så de herefter kan bruges til at opdatere databasen.

...




Gennemløb af nyeste deltadownload


Første trin gennemløber de hentede deltafiler og kalder hjælpemetoden DownloadAndProcessDeltaFiles som henter filerne, caster dem til DTO'er samt ligger den i databasen. Denne metode uddybes i næste sektion.

...

Image Added

...

...




Hælpemetode: DownloadAndProcessDeltaFiles

...


DownloadAndProcessDeltaFiles

...

henter

...

deltafiler

...

vha.

...

...

...

.

...

Dette

...

kodeeksempels

...

funktionalitet

...

foregår

...

...

følgende

...

måde:

  1. Navnene på deltafilerne sorteres efter generationNumber, så entiteterne i databasen opdateres i korrekt rækkefølge. Dvs. at deltafiler der slutter på xxx_395.zip eksempelvis indsættes i databasen før xxx_396.zip.
  2. De sorterede deltafiler gennemløbes én efter én, hvor følgende sker:

    ...

      1. Deltafilen download vha. hjælpemetoden GetFile.
      2. Deltafilens JSON-objekter deserialiseres til en liste af BBREtageDTO (se

    ...

    ...

      1. DTO’erne tilføjes til databasen vha. hjælpemetoden UpdateDatabaseWithDelta

    ...

      1. .

    ...

      1. GenerationNumber fra filens navn udledes vha. Regex. Hvis generationsnummeret er højere end latest_version fra databasen, opdateres databasen med det nye generationsnummer. Dette bruges til at holde styr på det senest hentede generationsnummer, så man ikke overskriver med ældre versioner / unødigt henter allerede-indlæste filer.


    Image Modified

    ...

    ...




    Hjælpemetode: GetFile

    ...


    Denne

    ...

    hjælpemetode

    ...

    bruges

    ...

    til

    ...

    at

    ...

    simplificere

    ...

    hentning

    ...

    af

    ...

    deltafiler

    ...

    vha.

    ...

    ...

    ...

    .

    Først kaldes GetFile endpointet med den access token som blev hentet i Hentning af access token til at tilgå API. Herefter læses indholdet ved hjælp af streaming.


    Image Added

    Kodeeksempel på hjælpermetode til hentning af filer vha. GetFile endpointet




    Hjælpemetode: DeserializeDeltaFile


    Denne hjælpemetode bruges til at deserialisere deltafilens JSON-objekter til en liste af BBREtageDTO'er.

    Hjælpemetoden udpakker zip-filen for derefter at gennemløbe JSON-filerne og caste dem til DTO'er.

    Image Modified

    ...




    Hjælpemetode: UpdateDatabaseWithDelta


    Denne hjælpemetode bruges til at opdatere databasen med de nye delta DTO'er. Den gør følgende:

    1. Opretter forbindelse til databasen
    2. Tjekker at bbr_etage tabellen findes. Hvis ikke, oprettes denne.
    3. Gennemløber alle DTO'erne en ad gang, hvor der for hver enkelte oprettes en query til databasen som køres mod databasen.




    Image Modified

    ...

    ...






    Afrunding


    Efter at have fulgt trinene op til denne sektion, er der nu følgende funktionalitet tilgængelig i rækkefølge:

    1. Visual Studio projekt i C# er opsat med relevante NuGet pakker samt appsettings.
    2. Programmatisk hentning af access token til kald mod API'erne
    3. Det nyeste totaldownload er hentet for BBR's Etage entitet. Herunder er dens generationsnummer samt filens objekter lagt i deres respektive tabeller i databasen.
    4. Deltadownloads med nyere generationsnumre end seneste totaldownload hentes. De tilhørende objekter placeres i databasen samt det senest-hentede generationsnummer opdateres i databasen.