...

Image Added

Dokumenthistorik

Referencer

Anchor
_Toc56157140 _Toc56157140

Anchor
_Toc212718786 _Toc212718786

Introduktion

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.

Anchor
_Ref207096002 _Ref207096002

Anchor
_Ref207096008 _Ref207096008

Anchor
_Toc212718787 _Toc212718787

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 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\]{*}.

Anchor
_Toc209076887 _Toc209076887

Anchor
_Toc209172552 _Toc209172552

Anchor
_Toc212718788 _Toc212718788

Anchor
_Toc209076888 _Toc209076888

Anchor
_Toc209172553 _Toc209172553

Anchor
_Toc212718789 _Toc212718789

Anchor
_Toc209076892 _Toc209076892

Anchor
_Toc209172557 _Toc209172557

Anchor
_Toc212718793 _Toc212718793

Anchor
_Toc209076893 _Toc209076893

Anchor
_Toc209172558 _Toc209172558

Anchor
_Toc212718794 _Toc212718794

Anchor
_Toc209076894 _Toc209076894

Anchor
_Toc209172559 _Toc209172559

Anchor
_Toc212718795 _Toc212718795

Anchor
_Toc209076897 _Toc209076897

Anchor
_Toc209172562 _Toc209172562

Anchor
_Toc212718798 _Toc212718798

Anchor
_Toc209076901 _Toc209076901

Anchor
_Toc209172566 _Toc209172566

Anchor
_Toc212718802 _Toc212718802

Anchor
_Toc209076902 _Toc209076902

Anchor
_Toc209172567 _Toc209172567

Anchor
_Toc212718803 _Toc212718803

Anchor
_Toc209076904 _Toc209076904

Anchor
_Toc209172569 _Toc209172569

Anchor
_Toc212718805 _Toc212718805

Anchor
_Toc209076906 _Toc209076906

Anchor
_Toc209172571 _Toc209172571

Anchor
_Toc212718807 _Toc212718807

Anchor
_Toc209076907 _Toc209076907

Anchor
_Toc209172572 _Toc209172572

Anchor
_Toc212718808 _Toc212718808

Anchor
_Toc209076910 _Toc209076910

Anchor
_Toc209172575 _Toc209172575

Anchor
_Toc212718811 _Toc212718811

Anchor
_Toc209076912 _Toc209076912

Anchor
_Toc209172577 _Toc209172577

Anchor
_Toc212718813 _Toc212718813

Anchor
_Toc209076913 _Toc209076913

Anchor
_Toc209172578 _Toc209172578

Anchor
_Toc212718814 _Toc212718814

Anchor
_Toc209076915 _Toc209076915

Anchor
_Toc209172580 _Toc209172580

Anchor
_Toc212718816 _Toc212718816

Anchor
_Toc209076916 _Toc209076916

Anchor
_Toc209172581 _Toc209172581

Anchor
_Toc212718817 _Toc212718817

Anchor
_Toc209076919 _Toc209076919

Anchor
_Toc209172584 _Toc209172584

Anchor
_Toc212718820 _Toc212718820

Anchor
_Toc209076921 _Toc209076921

Anchor
_Toc209172586 _Toc209172586

Anchor
_Toc212718822 _Toc212718822

Anchor
_Toc209076922 _Toc209076922

Anchor
_Toc209172587 _Toc209172587

Anchor
_Toc212718823 _Toc212718823

Anchor
_Toc209076925 _Toc209076925

Anchor
_Toc209172590 _Toc209172590

Anchor
_Toc212718826 _Toc212718826

Anchor
_Toc212718828 _Toc212718828

Projektsetup

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

Anchor
_Toc212718829 _Toc212718829

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

Anchor
_Toc212718830 _Toc212718830

Appsettings

Opret en appsettings.json fil som indeholder Client ID og Client Secret som blev oprettet og gemt i trin 3.2.
Et eksempel kan være dette:
Image Added
Figur 11: Appsettings.json eksempel
Sørg for appsettings-filen er med i build ved at tilføje følgende til .csproj:
Image Added
Figur 12: .csproj eksempel
Filen er i dette guideeksempel placeret følgende sted:
Image Added
Figur 13: Projektstruktur

Anchor
_Ref199505118 _Ref199505118

Anchor
_Toc212718831 _Toc212718831

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 Added
Figur 14: Kodeeksempel på hentning af access token
Image Added
Figur 15: Kodeeksempel på access token hjælpermetode
For at kalde denne metode med brug af sine værdier fra appsettings.json, kan man eksempelvis gøre følgende:
Image Added
Figur 16: Eksempel på hentning af access token
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.

Anchor
_Toc212718832 _Toc212718832

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.

Anchor
_Ref200451608 _Ref200451608

Anchor
_Toc212718833 _Toc212718833

Hentning af totaldownload

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

1. Wiki Markup
   Kald Datafordelerens GetFile endpoint (dokumentation findes her *\[fildownload_api\]{*})

   1. Brug følgende parametre
      1. Register: BBR
      2. LatestTotalForEntity: Etage
      3. Type: Bitemporal
      4. Format: JSON
   2. Angiv din access token fra Sektion 5 som Bearer token i headeren
2. Gem indholdet lokalt og opbevar filstien i en variabel / konfigurationsnøgle.
3. Træk indholdet fra zip-filen ud

Her fremgår et eksempel på en implementering med ovenstående logik:
Image Added
Figur 17: Kodeeksempel på hentning af total for BBR Etage

Anchor
_Toc212718834 _Toc212718834

Anchor
_Ref200451180 _Ref200451180

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 Added
Figur 18: Kodeeksempel på udtræk af udtræksnummer

Anchor
_Toc212718835 _Toc212718835

Gem udtræks 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 udtræknsnummer)
   4. Primary key: (register, entity)
3. Indsæt udtræksnummeret hentet i 6.2 for primærnøglen.

Image Added
Figur 19: Kodeeksempel på at gemme senest-hentede versionsnummer for et registers entitet.

Anchor
_Toc212718836 _Toc212718836

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 fra trin 6.1 og konverter JSON-objekterne til DTO'erne.

Anchor
_Ref200454272 _Ref200454272

Anchor
_Toc212718837 _Toc212718837

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 Added

Anchor
_Toc212718838 _Toc212718838

Anchor
_Ref200455714 _Ref200455714

Hjælpemetode: ReadLatestTotalOfEntityJsonFile

Følgende kodeeksempel læser filen gemt fra trin 6.1 og konverterer JSON-objekterne fra filen til DTO'en oprettet i trin 6.4.1.
Image Added
Figur 21: Konvertering af JSON til DTO af BBR's entitet Etage

Anchor
_Toc212718839 _Toc212718839

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 afsnit 6.4.1.
2. Indsæt DTO'erne i databasen

Anchor
_Toc212718840 _Toc212718840

Hjælpemetode: EnsureTableExists

Hjælpemetoden opretter tabellen for _bbr_etage_ med de udledte variabler og typer fra afsnit 6.4.1. Her skal det også vides hvad primærnøglen er. Dette kan findes i registrets tilhørende *\[{*}<span style="color: #0f2147"><strong>DLS]</strong></span>. 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{_}).
!worddav165c1e3f2c19fd627ec4626b8abde1d9.png|height=422,width=624!
Figur 22: Kodeeksempel på oprettelse af tabel i databasen for BBR Etage
 \\

Anchor
_Toc212718841 _Toc212718841

Hjælpemetode: UploadDtosToDatabase

For at indsætte DTO'erne i databasen, kan man med fordel bruge COPY-metoden. Heri gennemløbes DTO'erne fra 6.4.2 og indlæses én efter én i databasen på effektiv vis.
Image Added
Figur 23: Indlæsning af DTO'er i databasen vha. COPY

Anchor
_Toc212718842 _Toc212718842

Overordnet rækkefølge

Hele afsnit 6's overordnede rækkefølge af kaldt funktionalitet kan ses i følgende overblik:
Image Added
Figur 24: Overblik over rækkefølge af kaldt funktionalitet

Anchor
_Toc212718843 _Toc212718843

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 sektion 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.

Anchor
_Toc212718844 _Toc212718844

Hentning af navne på nyeste deltafiler

Der oprettes en hjælpemetode som henter de nyeste fildownload for BBR's entitet Etage vha. _GetAvailableFileDownloads_ fra *\[fildownload_api\]{*}, for derefter at filtrere filer fra, så de tilbageværende opfylder følgende kriterier:

1. Har et generationNumber højere end det senest hentede generationsnummer
2. typeOfDownload typen er "DeltaDownload"
3. typeOfData har bitemporaliteten "Bitemporal"
4. containedFileFormat er af typen "json"
5. Seneste version hentes. Dvs. at hvis der f.eks. findes både " BBR_V1Etage_DeltaDownload_json_Bitemporal_295.zip" og " BBRV2_Etage_DeltaDownload_json_Bitemporal_295.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 DTO'en i sektion 6.4.1 til at have version med sig. Guiden her tager kun udgangspunkt i den seneste version, som i dette eksempel er V2.

Image Added
Figur 25: Kodeeksempel på hentning af deltafil-navne for BBR Etage

Anchor
_Toc212718845 _Toc212718845

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.

Anchor
_Toc212718846 _Toc212718846

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
Figur 26: Kodeeksempel på gennemløb af deltafiler

Anchor
_Toc212718847 _Toc212718847

Hælpemetode: DownloadAndProcessDeltaFiles

_DownloadAndProcessDeltaFiles_ henter deltafiler vha. _GetFile_ endpointet fra *\[fildownload_api\]{*}. Dette kodeeksempels funktionalitet foregår på 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 (se sektion 7.2.2.1).
   2. Deltafilens JSON-objekter deserialiseres til en liste af BBREtageDTO (se Figur 16) vha.
   3. DTO'erne tilføjes til databasen vha. hjælpemetoden UpdateDatabaseWithDelta (se sektion 7.2.2.2).
   4. 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 Added
Figur 27: Kodeeksempel på hentning af deltadownloads samt upload til databasen.

Hjælpemetode: GetFile

Denne hjælpemetode bruges til at simplificere hentning af deltafiler vha. _GetFile_ endpointet fra *\[fildownload_api\]{*}.
Først kaldes _GetFile_ endpointet med den access token som blev hentet i sektion 5. Herefter læses indholdet ved hjælp af streaming.
!worddav8f2bd689889bad0faac5fbcbcf92fa6f.png|height=212,width=631!
Figur 28: Kodeeksempel på hjælpermetode til hentning af filer vha. GetFile endpointet

Anchor
_Ref200627812 _Ref200627812

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 Added
Figur 29: Kodeeksempel på deserialisering af JSON-objekter fra deltafiler til DTO'er.

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 Added
Figur 30: Kodeeksempel på opdatering af database med nye Delta DTO'er

Anchor
_Toc212718848 _Toc212718848

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.

...

...