¶ Priekšnosacījumi
¶ Pieteikums
Lai varētu izveidot savienojumu un izplatīt datus, DAGR portālā ir jābūt reģistrētam un apstiprinātam datu devēja pieteikumam.
Pieteikšanās process detalizētāk aprakstīts datu devēja ceļa kartē.
¶ Savienojums un drošības talons
Datu izplatīšana notiek ar tehniskajiem lietotājiem jeb savienojumiem. Savienojumus datu devēja kontaktpersonas reģistrē DAGR pašapkalpošanās portālā. Reģistrētos savienojumus tālāk var izmantot, lai nodotu datus uz DAGR kodolu, izmantojot datu devēja savienotāju vai DAGR REST API.
Savienojumu reģistrēšanas un drošības talona pieprasīšanas procesi detalizētāk arpakstīti autentifikācijas sadaļā.
¶ Datu kopas definēšana
DAGR publicējamās un izplatāmās datu vienības tiek sauktas par datu kopām. Datu kopa ir konkrēta datu devēja ierakstu kolekcija ar unikālu nosaukumu un noteiktu datu struktūru.
Datu kopu izplatīšana sākas ar datu kopas reģistrēšanu. Datu kopas reģistrēšana sastāv no šādiem soļiem:
- Reģistrēšana priekšlikumu vidē (sandbox). Vispirms datu devējs reģistrē datu kopu, norādot tās nosaukumu, datu struktūru un citus parametrus DAGR pašapkalpošanās portāla priekšlikumu vidē (sandbox). Priekšlikumu vidē reģistrētās datu kopas ir pieejamas tikai pašam datu devējam un šī vide ir paredzēta datu izplatīšanas izstrādes un sākotnējās testēšanas vajadzībām. Priekšlikumu vidē esošās datu kopas var uzskatīt par datu kopu melnrakstiem.
- Pārcelšana uz pamata vidi (dataset). Kad datu devējs aprobējis datu kopu un izplatīšanas procesus priekšlikumu vidē, tas lūdz DAGR pārvaldnieku pārcelt datu kopu uz pamata vidi (dataset). DAGR pārvaldnieks pārliecinās, ka datu kopa ir korekta un pārceļ to uz pamata vidi. Pamata vidē esošās datu kopas ir pieejamas datu patērētājiem un aprakstāmas VIRSIS sistēmā. Pamata vidē esošās datu kopas var uzskatīt par DAGRī publicētajām datu kopām.
- Aprakstīšana VIRSIS sistēmā. Piekļuves tiesību piešķiršana datu saņēmējiem uz datu devēja publicētajām datu kopām notiek VIRSIS sistēmā. Līdz ar to, ja vien datu kopa nav publiskas pieejamības, tad tā ir jāapraksta VIRSIS sistēmā un uz tās bāzes ir jāreģistrē informācijas pakalpojumus. Tas ļaus datu ņēmējiem pieteikties uz pakalpojumu un noslēgt vienošanos par tā izmantošanu, tādējādi iegūstot datu piekļuves atļauju.
¶ Priekšlikumu vidē (sandbox)
Reģistrēt datu kopas var priekšlikumu vidē, kas atrodama DAGR pašapkalpošanās portāla sadaļā “Datu izplatīšana” -> “Datu kopas”. Datu kopas definīcija sastāv no šādiem datiem:
- Nosaukums. Unikāls datu kopas nosaukums, kas veidots no latīņu burtiem un ir bez atstarpēm;
- Datu devējs. Datu devēja reģistrācijas numurs un nosaukums;
- Komentārs. Brīvā formā norādīts komentārs;
- Struktūra. Datu struktūras definīcija YAML formātā, kas satur šādus elementus:
- Nosaukums (name). Datu kopas nosaukums, jāsakrīt ar ekrānformā norādīto;
- Atslēga (key). Datu kopas primārā atslēga, kas sastāv no viena vai vairākiem datu kopas pirmā līmeņa datu laukiem.
- Apraksts (data_description). Datu kopas nosaukums jeb apraksts pilniem vārdiem.
- Datu struktūras koks (fields). Hierarhisks saraksts ar datu laukiem, to datu formātiem un pilnajiem nosaukumiem. DAGR atbalsta neierobežoti dziļas datu struktūras.
Datu kopas definīcijas piemērs DAGR pašapkalpošanās portāla testa vidē:
Pēc datu kopas reģistrēšanas priekšlikumu vidē (sanbox) tā ir pieejama datu devējam izmēģinājuma režīmā. Respektīvi, servisi datu nodošanai un apskatei pieejami DAGR REST API (https://test.dagr.gov.lv/api) sadaļā “sandbox”. Smilškastes režīms izmantojams datu nodošanas pārbaudei un atkļūdošanai. Kad tas paveikts, tad jālūdz DAGR pārvaldniekam pārcelt datu kopa no smilškastes uz pamata sadaļu.
¶ Datu struktūras definīcijas sintakse
Datu struktūras definīcijas elementi veidojami atbilstoši šādai sintaksei:
-
name: {nosaukums}
DAGR datu kopas definīcijai jāsākas ar datu kopas nosaukumu. Nosaukumam datu struktūras definīcijā jāsakrīt ar datu kopas nosaukumu, kurš norādīts datu kopas ievades kartiņā. -
key: {atslēgas lauks nr.1}, {atslēgas lauks nr.2}, {utt.}
Tālāk jānorāda datu lauki, kas veido ieraksta atslēgu. Atslēga var sastāvēt no viena vai vairākiem datu struktūras pirmā hierarhijas līmeņa datu laukiem, kam tālāk jāparādās datu struktūras defincijā elementā "fields". Papildus: Ja atslēgas sastāvā ir datu lauki, kas nav ar biznesa nozīmi, bet nepieciešami unikalitātes nodrošināšanai, tos var ielikt iekavās, lai datu saņēmējiem datu izgūšanas pieprasījumos neprādītos iespēja pēc tiem meklēt. Piemēram:key: person_code, year(, id) -
data_description: {datu kopas apraksts}
Apraksta elementā norādāms datu kopas pilnais nosaukums vai īss apraksts. Aprakstam ir informatīva nozīme, bet to ir būtiski aizpildīt, jo tas parādīsies datu kopas datu izgūšanas servisu aprakstos. -
fields: - {lauka_nosaukums} {lauka_formāts} : {lauka apraksts} - {salikta elementa nosaukums} * : comments : {salikta elementa komentārs} fields: - {lauka_nosaukums} {lauka_formāts} : {lauka apraksts}Visbeidzot datu struktūras elementā norādāms hierarhisks uzskaitījums ar datu kopas datu laukiem, to formātiem un aprakstiem. Datu struktūras elementā pēc būtības ir diva veida apakšelementi - datu lauki un saliktie elementi:
- Datu lauki, kur katram laukam ir nosaukums, tips un apraksts. Ja nenorāda datu tipu, tad tiek pieņemts, ka tas ir burtciparu kombinācija (string). Par datu tipiem plašāks apraksts nākamajās sadaļās;
- Salikti elementi reprezentē hierarhijas līmeņus. Tiem ir nosaukums, komentārs un saraksts ar apakšelementiem, kas atkal var būt datu lauki vai salikti elementi. Ja datu kopas ieraksti varēs saturēt vairāk kā vienu saliktā elementa vērtību (array), tad saliktā elementa definīcijā tas aiz saliktā elementa nosaukuma jāatzīmē ar reizinājuma zīmi “*”.
Piebilde: Lai arī tehniski datu struktūras elementā datu lauku apraksti un salikto elementu komentāri nav obligāti, tomēr rekomendējams tos pievienot. Šie apraksti un komentāri parādās datu kopas datu izgūšanas servisos un ļaut datu saņēmējiem spriest par datu lauku un hierarhijas elementu biznesa nozīmi.
Praktiski datu kopu definīciju piemēri pievienoti šīs lapas noslēgumā piemēru sadaļā.
¶ Nosaukumu politika
Lai nodrošinātu nosaukumu vienveidību, stingra rekomendācija ir datu kopas nosaukumu rakstīt angliski ar mazajiem burtiem, vārdus atdalīt ar apakš strīpu un prefiksā norādīt iestādes nosaukumu. Daži piemēri:
- ur_legal_entity (Uzņēmumu reģistra tiesību subjekti);
- vzd_address (Valsts zemes dienesta adreses);
- vbtai_orphan_certificate (Valsts bērnu tiesību aizsardzības inspekcijas bāriņu apliecības).
¶ Atslēgas izvēle
Datu kopas atslēgai jeb ierakstu primārajam identifikatoram ir ļoti liela nozīme DAGR arhitektūrā, tamdēļ tā izvēlei ir jāpievērš liela uzmanība. Datu kopas atslēga tiek veidota no viena vai vairākiem datu kopas datu laukiem.
Atslēga kā ierakstu primārais identifikators
Datu kopas atslēgai ir obligāti jābūt unikālai. Caur DAGR izplatāmie dati DAGR kodolā tiek uzglabāti key-value paradigmā, kur key ir ieraksta atslēga un value ir jebkuras sarežģītības datu struktūra JSON formātā. Gadījumā, ja izvēlētā atslēga izrādīsies neunikāla, tad datu sinhronizācija no datu avota uz DAGR kodolu strādās nekorekti - ieraksti ar neunikālajām atslēgām pie katras datu aktualizācijas reizes viens otru pārrakstīs un izskatīsies, ka datu kopā ir vairāk izmaiņu nekā to ir patiesībā.
Atslēga kā ierakstu meklēšanas iespēja
Datu ņēmējiem ir iespēja datu kopas ierakstus meklēt tikai pēc pilnas vai daļējas atslēgas (obligāti norādot atslēgas pirmo datu lauku un opcionāli norādot nākamos). Tamdēļ atslēga jāveido no datu laukiem ar biznesa nozīmi - personas koda, reģistrācijas numura, adreses koda, dokumenta numura, u.c. Piemēram, uzņēmuma gada pārskatu datu kopai varētu būt atslēga, kas sastāv no reģistrācijas numura / gada / dokumenta numura. Šāda atslēga ļautu meklēt ierakstus pēc reģistrācijas numura VAI pēc reģistrācijas numura un gada VAI uzreiz pēc visiem trim datu laukiem.
Gadījumā, ja ieraksta unikalitātes nodrošināšanai nepieciešams izmantot kādu datu lauku, kuram nav biznesa nozīmes, tad tas liekams atslēgas beigās un iekļaujams iekavās. Iekavās iekļautie lauki netiks piedāvāti meklēšanā.
Atslēga kā tiesību filtrs
DAGR un VIRSIS ļauj kontrolēt piekļuves tiesības datu kopas ierakstiem balstoties uz datu kopas atslēgā iekļauto datu lauku vērtībām. Detalizētāks apraksts pieejams tiesību pārvaldības apsvērumu sadaļā.
¶ Datu lauku tipi
Ņemot vērā, ka DAGR struktūrētos datu kopu datus izplata JSON formātā, izmantojot OpenAPI standartam atbilstošus datu izplatīšanas servisus un to aprakstus, datu kopu datu struktūras definīcijā var izmantot šādus datu lauku datu tipus:
intjebintegerveseliem skaitļiem;numberpeldošā punkta decimālajiem daļskaitļiem;stringburtciparu virknēm vispārīgā gadījumā, bet ar datumu un laiku saistītos gadījumos:dateburtciparu virknēm, kas satur datuma vērtību formētu atbilstoši RFC 3339 5.6 sadaļai;dateTimejebtimestampburtciparu virknēm, kas satur datuma un laika vērtību formētu atbilstoši RFC 3339 5.6 sadaļai;time, burtcipiaru virknēm, kas satur laika vērtību.
booleanpatiesuma ("true" vai "false") vērtībām.
Pailus datu lauku datu tipiem DAGR datu izplatīšanas servisos izmanto arī array un object datu tipus, kuri tiek noteikti no DAGR datu kopas datu struktūras definīcijas hierarhijas jeb saliktajiem elementiem.
Ja datu nodošanai uz DAGR tiek izmanots DAGR REST API, tad par datu konvertāciju uz korektajiem formātiem jārūpējas DAGR REST API izmantotājam. Savukārt ja datu nodošanai uz DAGR tiek izmantots datu devēja savienotājs, tad datu konvertāciju no avota datu tipiem uz datu definīcijā minētajiem tipiem veic datu devēja savienotājs.
¶ Piekļuves tiesību apsvērumi
Definējot izplatāmās datu kopas struktūru ir jāņem vērā VIRSIS piedāvātās tiesību pārvaldības iespējas un ar tām saistītie ierobežojumi.
Piekļuves atļaujas datu lauku griezumā
VIRSIS sistēmā datu piekļuves atļaujās ir iespējams norādīt, kuri no datu kopas datu laukiem datu patērētājam būs pieejami. No tā izriet, ka:
- Rekomendējams DAGR izvietot vienu plašāku (ar vairāk datu laukiem) datu kopu un katram datu saņēmējam pieejamo datu lauku apjomu norādīt VIRSIS atļaujā, nevis veidot vairākas šauras (ar mazāk datu laikiem) datu kopas, kur katrai piekļuve nedrošināma citam datu saņēmājam;
- Ja izplatāmie ieraksti satur apakšierakstus, kur katram apakšierakstam atkarībā no kāda datu lauka vērtības, tas ir vai nav pieejams noteiktam datu saņēmājam, šos apakšierakstus var apsvērt nodalīt atevišķos sarakstos. Piemēram, iedomāsimies datu kopu, kas satur personas aktīvos un atceltos sertifikātus ar datu struktūru:
Šajā gadījumā ir viens saraksts Certificates, kas satur visus sertifikātus un datu saņēmējam var vai nu piešķirt piekļuvi sertifikātu elementam un tādējādi visu sertifikātu datiem, vai arī nepiešķirt pieļuvi sertifikātu elementam un tādējādi neļaujot apskatīt nevienu no sertifikātiem. Taču, ja dažiem datu saņēmējiem nepieciešama piekļuve tikai aktuālajiem sertifikātiem un citiem datu saņēmējiem visiem sertifikātiem, tad sertifikātu sarakstu var sadalīt divos sarakstos, kas katrs satur sava statusa sertifikātus, šādi:{ "PersonCode":"32118410604", "PersonName":"Janis Testiņš", "Certificates": [ { "CertificateNumber":"213423523", "ValidFrom":"2010-07-09", "Status":"valid" }, { "CertificateNumber":"345345", "ValidFrom":"1997-01-01", "Status":"revoked" } ] }
Šajā gadījumā vienam datu saņēmējam var piešķirt piekļuvi tikai ValidCertificates elementam, bet citiem gan ValidCertificates, gan RevokedCertificates elementiem.{ "PersonCode":"32118410604", "PersonName":"Janis Testiņš", "ValidCertificates":[ { "CertificateNumber":"213423523", "ValidFrom":"2010-07-09", "Status":"valid" } ], "RevokedCertificates":[ { "CertificateNumber":"345345", "ValidFrom":"1997-01-01", "Status":"revoked" } ] }
Piekļuves atļaujas ierakstu griezumā
Papildus piekļuves tiesībām datu lauku griezumā VIRSIS sistēma atbalsta piekļuves tiesības arī ierakstu līmenī, ļaujot vai liedzot datu saņēmējiem piekļuvi noteiktiem datu kopas ierakstiem atkarībā no vērtībām noteiktos konkrētā ieraksta datu laukos. Šo funkcionalitāti turpmāk sauksim par tiesību filtriem. Būtiski: filtrēt iespējams ir tikai pēc datu laukiem, kas ir iekļauti datu kopas atslēgā. Līdz ar to veidojot datu kopas datu struktūru, ir rūpīgi jāapsver, kuri datu lauki iekļaujami atslēgā. Šobrīd tiek atbalstīti šādi tiesību filtri:
- Atbilstība noteiktai vērtībai vai vērtību kopai. Atļaujā pie noteiktā datu lauka norādīta viena vai vairākas vērtības, kuras datu laukam jāsatur, lai tas būtu pieejams datu saņēmējam. Piemēram, iedzīvotāja datu kopas atslēgā varētu iekļaut iedzīvotāja deklarētās adreses ATVK kodu, kas ļautu piekļuvi iedzīvotāju datiem dalīt pēc dzīvesvietas teritoriālās vienības, kas varētu būt noderīgi izplatot datus pašvaldību vajadzībām.
- Lielāks vai mazāks par noteiktu vērtību. Atļaujā pie noteiktā datu lauka norādīta vērtība, kura jāsasniedz vai kuru nedrīkst sasniegt, lai ieraksts datu saņēmējam būtu pieejams. Piemēram, iedzīvotāju datu kopas primārajā atslēgā varētu norādīt personas vecumu, kas ļautu datu piekļuvi personu datiem dalīt pēc persons vecuma, kas varētu būt noderīgi izplatot datus skolām. Šis filtrs piemērojams gan skaitļiem, gan datumiem.
- Senāks vai jaunāks par noteiktu laika posmu. Atļaujā pie noteiktā datu lauka var norādīt, cik senu vai nesenu vērtību tam jāsatur, lai ierkasts būtu pieejams datu saņēmējam. Piemēram, dokumentu datu kopas ieraksta atslēgā varētu iekļaut dokumenta iesniegšanas datumu, kas ļautu piekļuvi piešķirt pēc dokumenta senuma, teiksim, tikai tiem dokumentiem, kas nepārsniedz divu gadu vecumu.
Plašāks filtru izklāsts pieejams nākamajās sadaļās, bet, plānojot datu kopas datu struktūru, būtiski atcerēties, ka datu lauki, pēc kuru vērtībām paredzēts kontrolēt piekļuvi noteiktiem datu kopas ierakstiem, ir jāiekļauj datu kopas atslēgā. Papildus ātrdarbības nolūkos jārūpējas, lai filtrējamo datu lauku skaits nav pārāk liels - nav rekomendējams piekļuves tiesību filtriem pakļaut vairāk kā trīs datu kopas datu laukus.
¶ Pamata vidē (dataset)
Datus no izmēģinājuma vides (sandbox) uz pamata sadaļu (dataset) var pārcelt DAGR pārvaldnieks pēc datu devēja lūguma. Pārcelšanas procesa ietvaros DAGR pārvaldnieks datu kopu verificē un papildina ar metadatiem.
Lai pārceltu datu kopu uz pamata sadaļu, DAGR pārvaldnieks DAGR portāla pārvaldības daļā atver sadaļu “Izplatīšana” -> “Priekšlikumu vide”. Šajā sadaļā ir saraksts ar visu datu devēju reģistrētajām datu kopām priekšlikumu vidē (sandbox). No šī saraksta pārvaldnieks izvēlas uz pamata sadaļu pārceļamo datu kopu, to atver un spiež pogu “Saglabāt” – tas pārceļ datu kopu no priekšlikumu vides (sanbox) uz pamata sadaļu (dataset).
Lai pabeigtu datu kopas pārcelšanu, pārvaldnieks atver pārcelto datu kopu DAGR portāla pārvaldības daļas sadaļā “Izplatīšana” -> “Datu kopas” un to precizē, norādot šādus parametrus:
- data_owner_code norāda datu devēja reģistrācijas numuru pēdiņās;
- data_owner_name norāda datu devēja nosaukumu;
- data_namespace norāda datu devēja saīsinājumu, kurš tiek izmantots servisu definīciju grupēšanai sadaļā https://test.dagr.gov.lv/api;
- subject_type norāda datu kopas ieraksta subjekta tipu jeb to, uz ko norāda ieraksta primārā atslēga. Dokumenta rakstīšanas brīdī DAGR reģistrētajām datu kopām pastāv šādi subjekta tipi: “persona”, “uzņēmums” un “adrese”. Jaunām datu kopām var būt nepieciešams reģistrēt jaunus subjekta tipus. Datu kopām, kurām subjekta tips ir “persona”, tiek piemērota paplašināta auditācija – papildus datu pieprasījuma metadatiem tiek saglabāts arī saraksts ar ierakstu identifikatoriem (personas kodiem), kuri bijuši pieprasījuma atbildē;
- subeject_id_fieldname ir jānorāda datu lauka nosaukums no datu struktūras, kurš satur subjekta identifikatoru.
- monitor_missing_keys var norādīt, vai datu kopai var monitorēt ierakstus, kas nav datu kopā. Pēc noklusējuma šī vērtība ir false.
- is_public_dataset var norādīt, vai datu kopa ir publiska un pieejama bez VIRSIS datu atļaujas. Pamatā paredzēts izmantot testa anonimizētajām datu kopām DAGR testa vidē.
¶ VIRSIS sistēmā
Pēc tam, kad DAGR ir pievienota izplatāmās datu kopas definīcija, datu kopa jāapraksta VIRSIS sistēmā un jāizveido ar to sasistīts informācijas pakalpojums. Plašāka instrukcija ar ekrānšāviņiem atrodama VIRSIS sistēmas dokumentācijā, bet kopumā process sastāv no šādiem soļiem:
- DAGR datu kopas reģistrēšana VIRSIS sistēmā. Sadaļā "Vienotais reģistrs-DAGR datu kopas" ir jāizvēlas darbība "Pievienot ierakstu" un no saraksta jāizvēlas DAGR definētā datu kopa. Piebilde: Sarakstā parādās tikai tās datu kopas, kuras no DAGR priekšlikumu vides (sandbox) ir pārceltas uz pamata vidi (dataset);
- Informācijas resursa izveide. VIRSIS sistēmā ir jāizveido jauns informācijas resurss, jāpārliecinās, ka tas ir statusā kopija/melnraksts, resursam jādefinē datu lauki un tie jāsasaista ar iepriekšējā solī pievienotās DAGR datu kopas datu laukiem;
- Informācijas resursa publicēšana. Pēc datu lauku sasaistes izveides, informācijas resurss ir jāpublicē;
- Pakalpojuma izveide. Pēc informācijas resursa publicēšanas ir jāizveido jauns pakalpojums un tam jāpiesaista publicētais informācijas resurss.
Pēc augstākminēto soļu izpildes datu saņēmēji varēs pieteikties uz informācijas pakalpojumu un pieteikuma saskaņošanas rezultātā iegūt piekļuvi sasitītajām DAGR datu kopām.
¶ Datu nodošanas varianti
Kad izplatāmā datu kopa definēta, ir jāizvēlas datu nodošanas variants.
DAGR piedāvā šādus variantus, kā nodot datus no datu avota uz DAGR kodolu:
- Izmantojot DAGR REST API. Datu devējs var organizēt datu nodošanu uz DAGR, izmantojot DAGR REST API pieejamos datu nodošanas servisus. Shēmā redzamais serviss
POST /jwt/connect/tokenizmantojams drošības talona pieprasīšanai. Tālāk servissPUT /updateizmantojams datu nodošanai. Papildus servissGET /updates_sha256, ļauj izgūt sarakstu ar DAGR kodolā esošo ierakstu identifikatoriem un ierakstu vērtību kontrolsummām, kas var tikt izmantots nododamo izmaiņu atpazīšanai.
Šis datu nodošanas variants ir salīdzinoši vienkāršs, bet prasa izmaiņas datu devēja informācijas sistēmā. Detalizētāks datu nodošanas mehānisma apraksts atrodams sadaļā par datu nodošanu, izmantojot REST API. - Izmantojot datu devēja eksistējošos REST, SOAP vai gRPC datu izplatīšanas servisus. Ja datu devējam ir eksistējoši datu izplatīšanas servisi, kas nodrošina iespēju atklāt datu kopas ierakstus un to izmaiņas, tad datu nodošanai uz DAGR var izmantot šos servisus. Šajā gadījumā datu nodošana uz DAGR tiks organizēta, izmantojot datu devēja savienotāju, kurš nolasīs datus no eksistējošajiem datu devēja servisiem un nodos uz DAGR kodolu caur DAGR REST API. Šis variants neprasa izmaiņas datu devēja pusē, bet prasa pielāgotas izstrādes darbus DAGR projekta pusē, lai iestrādātu datu devēja eksistējošo servisu atbalstu datu devēja savienotāja komponentē. Ņemot vērā, ka šis variants prasa pielāgotu izstrādi DAGR pusē, tā izvēle saskaņojama ar DAGR pārvaldnieku.
- Nolasot datus no failiem. Datus uz DAGR kodolu var nodot no csv, txt, json vai xml tipa failiem. Šajā gadījumā datu nodošana uz DAGR organizējama, izmantojot datu devēja savienotāju, kurš nolasīs datus no failiem un nodos tos uz DAGR kodolu caur DAGR REST API. Pieņemot, ka datu avota sistēmai eksistē mehānisms, kā eksportēt datus uz failiem, šis datu nodošanas mehānisms neprasa izstrādes pielāgojumus ne datu devēja ne DAGR pusē – viss, kas nepieciešams, ir uzstādīt un nokonfigurēt datu devēja savienotāju.
- Nolasot datus no DBVS ar SQL. Datus uz DAGR kodolu var nodot, izmantojot lasīšanas režīma SQL pieslēgumu avota datu bāzei. Šajā gadījumā datu nodošana uz DAGR organizējama, izmantojot datu devēja savienotāju, kurš nolasīs datus no datu bāzes, izmantojot JDBC pieslēgumu, un nodos tos uz DAGR kodolu caur DAGR REST API. Lai nebūtu nepieciešams atvērt piekļuvi avota datu bāzei no ārējā tīkla, šajā gadījumā datu devēja savienotāju rekomendējams uzstādīt datu devēja infrastruktūrā. Šis datu nodošanas mehānisms neprasa izstrādes pielāgojumus ne datu devēja ne DAGR pusē - viss, kas nepieciešams, ir uzstādīt un nokonfigurēt datu devēja savienotāju.
- Nolasot datus no DBVS transakciju datnēm. Datu nodošanu uz DAGR iespējams organizēt, izmantojot Debezium (https://debezium.io/) tehnoloģiju, kas ļauj datus nolasīt no datu bāzu transakciju failiem. Šajā gadījumā uzstādāms Debezium pieslēgums datu avota datu bāzei, kurš datus nodos uz DAGR kodola Kafka rindu. Šis datu nodošanas mehānisms neprasa izstrādes pielāgojumus ne datu devēja ne DAGR pusē, bet tas var prasīt būtiskas izmaiņas avota DBVS konfigurācijā.
No uzkrātās DAGR izmantošanas pieredzes sevi vislabāk ir pierādījusi datu izgūšana no DBVS ar SQL pieprasījumiem (ceturtais variants) vai failiem (trešais variants), izmantojot datu devēja savienotāju. Salīdzinoši vienkārša ir arī datu tieša ierakstīšana DAGR REST API (pirmais variants).
Tehnoloģiski augstākminētie datu nodošanas varianti realizējami:
- Izmantojot DAGR REST API. Šajā gadījumā datu nodošanu uz DAGR kontrolē datu avota sistēma;
- Izmantojot datu devēja savienotāju. Šajā gadījumā datu izgūšanu un nodošanu uz DAGR kontrolē datu devēja savienotājs par avotu izmantojot datu bāzi, datnes (CSV, TXT, JSON) vai eksistējus datu devēja datu izplatīšanas servisus;
- Izmantojot Debezium savienotāju. Debezium savienotājs ļauj izgūt datus no datu bāzu žurnālfailiem.
Tālākajās nodaļās pieejamas instrukcijas katrai no tehnoloģijām.
¶ Izmantojot REST API
Datu nodošanu uz DAGR datu devējs var organizēt pats savā sistēmā, izmantojot DAGR REST API.
Vispirms tiek pieprasīts drošības talons un tālāk ar to tiek darbināti šādi servisi:
PUT {dagr_adrese}/update/{service_name}. Šis serviss nosūta strukturētus datus uz DAGR JSON formātā;PUT {dagr_adrese}/file/{namespace}/{path_and_filename}. Šis serviss uz DAGR nosūta datnes. Datu devējam pieejams arī DELETE serviss datnes dzēšanai un GET serviss datnes lejupielādei;GET {dagr_adrese}/updates_sha256/{service_name}. Šis serviss ļauj izgūt uz DAGR nosūtīto strukturēto datu ierakstu identifikatorus un kontrolsummas. Serviss izmantojams izmaiņu atpazīšanai, kā arī atkļūdošanas nolūkiem;GET {dagr_adrese}/updates_last_timestamp/{service_name}. Šis serviss ļauj noteikt pēdējo uz DAGR nosūtīto izmaiņu datumu un laiku. Servisu var izmantot izmaiņu atpazīšanai, ja datu avotā tiek uzturēti izmaiņu veikšanas datumi un laiki.
Minēto servisu apraksti OpenAPI standartā pieejami:
- Testa vidē: https://test.dagr.gov.lv/api-docs/update
- Produkcijas vidē: https://dagr.gov.lv/api-docs/update
Servisus iespējams izmantot tikai ar datu devējam izsniegto DAGR drošības talonu. Par savienojuma reģistrēšanu un drošības talona izgūšanu detalizētāk skatīt autentifikācijas sadaļā.
¶ Strukturētu datu iesūtīšana
Strukturēti dati uz DAGR nododami, izmantojot /update servisu:
- Datu nodošanai uz pamata vidi (dataset) servisa adrese veidojas šādi:
PUT {dagr_adrese}/update/{datu_kopas_nosaukums} - Datu nodošanai uz izmēģinājuma vidi (sandbox) servisa adrese veidojas šādi:
PUT {dagr_adrese}/sandbox/{datu_devēja_reģ_nr}/update/{datu_kopas_nosaukums}
Nododamie dati iekļaujami servisa saturā (body) JSON formātā. Servisam var nodot uzreiz vairākus ierakstus, kur katrs ieraksts norādāms šādā formā:
{
"key": "string",
"timestamp": "2024-03-06T10:04:55.297Z",
"value": "string"
}
Datu lauku nozīme:
- “key” ir ieraksta primārā atslēga. Ja uz DAGR nododamais ieraksts saturēs jaunu iepriekš uz DAGR nenodotu atslēgas vērtību, tad tas tiks uzskatīts par jaunu ierakstu un pievienots DAGR datu kopai kā jauns ieraksts. Ja uz DAGR nododamais ieraksts saturēs iepriekš uz DAGR jau nodotu atslēgas vērtību, tad tās tiks uzkatītas par ieraksta izmaiņām un jaunā ieraksta vērtība pārrakstīs iepriekšējo vērtību.
- “timestamp” ir neobligāti norādāma vērtība. Pēc noklusējuma par šo vērtību tiks uzstādīts datu nodošanas brīža datums un laiks. Manuāli šo vērtību paredzēts norādīt tikai veicot pirmreizējo datu nodošanu uz DAGR, lai uz DAGR nodotu informāciju par ierakstu pēdējo izmaiņu laiku avota sistēmā. Ja šī vērtība tiek norādīta, tad ieraksti iesūtīšanas brīdī kārtojami pēc šīs vērtības augošā secībā. Konstatējot situāciju, kur ierakstāmā ieraksta “timestamp” mazāks par iepriekšējā ieraksta “timestamp”, DAGR ierakstāmā ieraksta norādīto “timestamp” aizvietos ar ierakstīšanas brīža datumu un laiku.
- “value” ir paša ieraksta biznesa dati. Value ir norādāma kā burtciparu (string) virkne, kas satur eskeipotu JSON datu objektu. Ja uz DAGR tiek nodota tukša ieraksta vērtība ("value": null), tad tā tiek uzskatīta par dzēšanas operāciju un ieraksts no DAGR tiek dzēsts.
Tātad, izmantojot /update servisu var veikt šādas trīs darbības:
- Pievienot jaunu ierakstu – padodot uz /update servisu ierakstu ar jaunu “key” vērtību;
- Atjaunināt ieraksta vērtību – padodot uz /update servisu ierakstu ar eksistējošu “key” vērtību;
- Dzēst ierakstu – padodot uz /update servisu ierakstu ar eksistējošu “key” vērtību un “value” norādot tukšu (null) vērtību.
Datu nodošanas servisa izsaukuma piemērs (trīs ierakstu pievienošana):
curl --location --request PUT 'https://test.dagr.gov.lv/sandbox/40003562863/update/tst_company_service_report' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46VEVTVC1MTkI6REFHUi5TVFMiLCJzdWIiOiI0MDAwMzU2Mjg2MyIsImF1ZCI6WyJwcm9kdWNlciIsInVybjpURVNULUxOQjpEQUdSLlNUUy9yZXNvdXJjZXMiXSwiZXhwIjoxNzEwNDAxNjExLCJuYmYiOjE3MTA0MDA3MTEsImlhdCI6MTcxMDQwMDcxMSwibGVnYWxlbnRpdHkiOiI0MDAwMzU2Mjg2MyIsImNsaWVudF9pZCI6ImRlbW9fZGRzX2Nvbm5lY3Rvcl8xIiwic2NvcGUiOlsicHJvZHVjZXIiXX0.aOahd4FnJXzt5rjBzw_zMtFWL0gBUIIT2rwIG7bcdZLkd8NqEsYtq2qOqkfnncwm-iSn9uYV-lOM6q02NHcXVA68NU56PQkX_DvM-Vl251GFtZFR8z9Tu64J1EaBWI2DR7x6BG7ULxO_bRzUaBSn6VrBkGxNe0YoerJ5uMJZex7q461ed5UxCk0Hl8-BE4eWSE-OJCnaTAHcDnLaCEiIQgiwL9jbq4hmWTe_O_0EO5zwRv0QiueLhHQ7whBallI5fX0WSH0cXINt7GRwcqP5UuMbpQ_-dwnBcEtcS-Iaj3Auz9ycrU3mIkldld4EnVs1OeaLmXakBk8AvR8mRHIq7A' \
--data '[
{
"key": "40003562863/2023/5634634",
"value": "{\n \"Id\": 5634634,\n \"CompanyName\": \"UNISO SIA\",\n \"RegistrationNumber\": \"40003562863\",\n \"IsLicensed\": true,\n \"Year\": 2023,\n \"Status\": \"apstiprināts\",\n \"Submitted\": \"2024-03-06T09:22:11.593Z\",\n \"Clients\": [\n {\n \"CompanyName\": \"VARAM\",\n \"RegistrationNumber\": \"90000028508\",\n \"ClientSince\": \"2022-01-12\",\n \"Services\": [\n {\n \"Name\": \"Programmatūras izstrāde\",\n \"DateFrom\": \"2023-01-01\",\n \"DateTo\": \"2023-12-31\"\n }\n ]\n }\n ],\n \"VerifiedBy\": {\n \"Name\": \"Jānis\",\n \"Surname\": \"Sprukts\",\n \"Position\": \"Sistēmu arhitekts\"\n }\n}"
},
{
"key": "40003562863/2022/5634234",
"value": "{\n \"Id\": 5634234,\n \"CompanyName\": \"UNISO SIA\",\n \"RegistrationNumber\": \"40003562863\",\n \"IsLicensed\": true,\n \"Year\": 2022,\n \"Status\": \"apstiprināts\",\n \"Submitted\": \"2023-03-06T09:22:11.593Z\",\n \"Clients\": [\n {\n \"CompanyName\": \"VARAM\",\n \"RegistrationNumber\": \"90000028508\",\n \"ClientSince\": \"2022-01-12\",\n \"Services\": [\n {\n \"Name\": \"Programmatūras izstrāde\",\n \"DateFrom\": \"2022-01-12\",\n \"DateTo\": \"2022-12-31\"\n },\n\t\t{\n \"Name\": \"Konsultācijas\",\n \"DateFrom\": \"2022-02-12\",\n \"DateTo\": \"2022-03-12\"\n }\n ]\n },\n\t{\n \"CompanyName\": \"VRAA\",\n \"RegistrationNumber\": \"90001733697\",\n \"ClientSince\": \"2022-01-01\",\n \"Services\": [\n {\n \"Name\": \"Programmatūras izstrāde\",\n \"DateFrom\": \"2022-01-01\",\n \"DateTo\": \"2022-12-31\"\n }\n ]\n }\n ],\n \"VerifiedBy\": {\n \"Name\": \"Jānis\",\n \"Surname\": \"Sprukts\",\n \"Position\": \"Sistēmu arhitekts\"\n }\n}"
},
{
"key": "40003562863/2022/56332",
"value": "{ \"Id\": 56332, \"RegistrationNumber\": \"40003562863\", \"Year\": 2022 }"
}
]'
Piemērā redzams, ka galvenē (header) tiek padots drošības talons un tālāk saturā (data) tiek padotas divas ierakstu vērtības. Drošības talona pieprasīšana aprakstīta autentifikācijas sadaļā, savukārt viens no piemērā nododamajiem ierakstiem neeskeipotā formātā izskatās šādi:
{
"Id": 5634634,
"CompanyName": "UNISO SIA",
"RegistrationNumber": "40003562863",
"IsLicensed": true,
"Year": 2023,
"Status": "apstiprināts",
"Submitted": "2024-03-06T09:22:11.593Z",
"Clients": [
{
"CompanyName": "VARAM",
"RegistrationNumber": "90000028508",
"ClientSince": "2022-01-12",
"Services": [
{
"Name": "Programmatūras izstrāde",
"DateFrom": "2023-01-01",
"DateTo": "2023-12-31"
}
]
}
],
"VerifiedBy": {
"Name": "Jānis",
"Surname": "Sprukts",
"Position": "Sistēmu arhitekts"
}
}
Augstākminētais piemērs sagatavots datu kopai ar šādu datu struktūras definīciju:
name: tst_company_service_report
key: RegistrationNumber, Year(, Id)
data_description: Gada atskaite par uzņēmuma sniegtajiem pakalpojumiem
fields:
- Id long : Atskaites ID
- CompanyName : Uzņēmuma nosaukums
- RegistrationNumber : Uzņēmuma reģistrācijas numurs
- IsLicensed boolean : Ir licenzēts pakalpojumu sniedzējs
- Year int : Gads
- Status : Atskaites statuss
- Submitted timestamp : Atskaites iesniegšanas datums un laiks
- Clients * :
comments : Uzņēmuma klienti
fields:
- CompanyName : Uzņēmuma nosaukums
- RegistrationNumber : Uzņēmuma reģistrācijas numurs
- ClientSince date : Datums kopš kura ir klients
- Services * :
comments : Sniegtie pakalpojumi
fields:
- Name : Pakalpojuma nosaukums
- DateFrom date : pakalpojuma sniegšanas sākuma datums
- DateTo date : Pakalpojuma sniegšanas beigu datums
- VerifiedBy :
comments : Pārskata pārbaudītājs
fields:
- Name : Vārds
- Surname : Uzvārds
- Position : Amats
Datu nodošanas servisa izsaukuma piemērs (ieraksta dzēšana):
curl --location --request PUT 'https://test.dagr.gov.lv/sandbox/40003562863/update/tst_company_service_report' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46VEVTVC1MTkI6REFHUi5TVFMiLCJzdWIiOiI0MDAwMzU2Mjg2MyIsImF1ZCI6WyJwcm9kdWNlciIsInVybjpURVNULUxOQjpEQUdSLlNUUy9yZXNvdXJjZXMiXSwiZXhwIjoxNzA5NzIxNjIyLCJuYmYiOjE3MDk3MjA3MjIsImlhdCI6MTcwOTcyMDcyMiwibGVnYWxlbnRpdHkiOiI0MDAwMzU2Mjg2MyIsImNsaWVudF9pZCI6ImRlbW9fZGRzX2Nvbm5lY3Rvcl8xIiwic2NvcGUiOlsicHJvZHVjZXIiXX0.Qm0lUSjblBRoX9Xkt8HPeERjHf9Ul_e6CYsZLsZYj7d5OHHLSOb8EH-Sz8apIGbK8tQKbdtBKhUKbgVMPIOsqnDVIguKNTq4drZn_IOgkhvucHIO4yHtYsNE240HlvIctfLzi2_7vCYB5r816XeS_Y3PdS7CwQW1H5I_w4O7Uzp71FGS8hNuh8BBe7RcScL4TVZjMEuxVh67BeMNHsrNREumeuPoPHEGABrDTK2YEn_4biphbGW5iYY5a4PnoKtOAN_pChs0Ug0Ojm18e8AK8fahDF7c4nNLmemNzyidOmwhOSCCIwjW_N82N1qX7OPrFluszC7AYm0RLGk5sGMD2Q' \
--data '[
{
"key": "40003562863/2023/5634634",
"value": null
}
]'
¶ Izmaiņu atpazīšana
Ja nepieciešams konstatēt, kādi ieraksti ir nodoti uz DAGR, var izmantot servisu:
GET {dagr_adrese}/updates_sha256/{service_name}.
Šis serviss atgriež sarakstu ar ierakstu atslēgām un SHA256 ierakstu vērtību kontrolsummām uz DAGR nodotajiem datiem. Ilglaicīgi katram unikālajam ierakstam jeb ieraksta atslēgai DAGR uzglabā pēdējo nodoto vērtību un kontrolsummu, bet īslaicīgi un izmēģinājuma vidē (sandbox) tiek uzglabātas visas nodotās ierakstu vērtības un kontrolsummas.
Servisa /updates_sha256 atbildes piemērs:
[
{
"key": "40003562863/2023/5634634",
"offset": 0,
"sha256": "b4b5f8353f1d6bc7ab1db2637afa28cb1ce33fb67e4e0cef7f0d785884c8eac5"
},
{
"key": "40003562863/2022/5634234",
"offset": 1,
"sha256": "a6d2b783425ca15c86fbb88c3a05fe643c2e78e7bb57bd581e8fedffc0a4bdcc"
},
{
"key": "40003562863/2023/5634634",
"offset": 2,
"sha256": null
},
{
"key": "40003562863/2022/56332",
"offset": 3,
"sha256": "42a70d82a114352e4af97610d8b4c756ff6586cc7557c5ac12af583dd18d5346"
}
]
Piemērā redzam, ka ierakstam ar atslēgu 40003562863/2023/5634634 uz DAGR vispirms nodota viena vērtība, tad cita vērtība un visbeidzot ieraksts dzēsts. Pēc tam uz DAGR nodots ieraksts ar atslēgu 40003562863/2022/56332.
SHA256 kontrolsummu rēķināšanai DAGR izmanto OpenSSL bibliotēku. Online rīks, kas pārbaudīts, ka sakrīt ar DAGR aprēķinātājām SHA256 vērtībām: https://tools.keycdn.com/sha256-online-generator
Lai nodrošinātu, ka uz DAGR tiek nodotas tikai izmaiņas, izmantojot updates_sha256 servisu, realizējams šāds mehānisms:
- Jāsagatavo saraksts ar datu avotā esošo ierakstu atslēgām un aprēķinātajām ierakstu vērtību sha256 kontrolsummām;
- Jāsaņem saraksts ar DAGR ierakstīto ierakstu atslēgām un sha256 kontrolsummām no DAGR izmantojot updates_sha256 servisu;
- Jāsalīdzina saraksti un jāveic šādas darbības:
- Visi ieraksti ar atslēgām, kuras ir avota sistēmā, bet nav DAGR ir jauni ieraksti. Tie ir nododami uz DAGR;
- Visi ieraksti ar sakrītošām atslēgām un sakrītošām kontrolsummām ir ieraksti, kuru vērtības nav mainījušās. Šos ierakstus uz DAGR nodot nav nepieciešams;
- Visi ieraksti ar sakrītošām atslēgām un dažādām kontrolsummām ir modificēti ieraksti. Šo ierakstu jaunās vērtības ir nododamas uz DAGR;
- Visi ieraksti ar atslēgām, kuras ir DAGR, bet nav avota sistēmā ir dzēsti ieraksti. Šo ierakstu dzēšanas fakts ir nododams uz DAGR (līdzīgi kā tiek nodots jauns vai modificēts ieraksts, tikai ieraksta vērtības laukā norādot null).
Piebilde: Ja DAGR atgriež vairākus ierakstus ar vienādām atslēgām, tad faktiskā pēdējā ierakstītā vērtība būs ar lielāko offset vērtību.
Augstāk minētais mehānisms ir tāds pats, kā tiek izmantots datu devēja savienotājā.
¶ Failu pievienošana
Failu nodošanai uz DAGR izmantojams serviss PUT /file/{namespace}/{path_and_filename}, kur {namespace} ir datu devēja datu kopām izmantojamā vārdtelpa.
Datnes pievienošanas piemērs:
curl -X 'PUT' \
'https://test.dagr.gov.lv/file/vsaa/test_file_name.txt' \
-H 'accept: text/plain' \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46VEVTVC1MTkI6REFHUi5TVFMiLCJzdWIiOiI5MDAwMTY2OTQ5NiIsImF1ZCI6WyJwcm9kdWNlciIsInVybjpURVNULUxOQjpEQUdSLlNUUy9yZXNvdXJjZXMiXSwiZXhwIjoxNzEwMzI4MDI4LCJuYmYiOjE3MTAzMjcxMjgsImlhdCI6MTcxMDMyNzEyOCwibGVnYWxlbnRpdHkiOiI5MDAwMTY2OTQ5NiIsImNsaWVudF9pZCI6IlZTQUFfVEVTVF9ERFNfMSIsInNjb3BlIjpbInByb2R1Y2VyIl19.gZgNI6451nrLAMYp4UHRWLbTGIvPjIBxPpP1j2xiU5RyUf2lraD3CWdmyFyBIrlhzSjmQ5ITvrtJrvlMm0ID4j3BPoDiUsrOtR-6OFEbR3rwYLruQyu_CiHDBLbyfyWr8KKSbyov834-37x1wrZjablC-t_tncs7Uyd9-pvQp_RjkVmEYgwfPLiq-edOyczQQ4WwcYwVoYKgH05yA5TX3LQ7n4oOGvJvMa9KoZenU2a49y4bLAxwQGKtxV_kox75ABMXroaGT51l1FpTRz1AnzCBh6n4D3s3D0novL2IpqYgBxA5jhybkwJPd1ynD_n4SVQDJNlLp_UiRYq-gnbCGw' \
-H 'Content-Type: application/octet-stream' \
--data-binary '@test_file.txt'
Papildus PUT servisam, datu devējam pieejams arī DELETE /file/{namespace}/{path_and_filename} serviss, kas ļauj datni dzēst un GET /file/{namespace}/{path_and_filename}, kas ļauj datni lejupielādēt.
¶ Izmantojot savienotāju
Datu devēja savienotājs ir JAVA aplikācija, kas izgūst datus no datu avota, tos transformē un nodod uz DAGR kodolu, izmantojot iepriekšējā nodaļā aprakstīto DAGR REST API. Datu devēja savienotājs ir izvietojams datu devēja infrastruktūrā, lai nebūtu jāatver piekļuve datu avotam ārpus datu devēja tīkla infrastruktūras un datu devējam būtu pilna kontrole pār datu devēja savienotāju un tā konfigurāciju.
Datu devēja savienotāja sekmīgai darbināšanai ir nepieciešamas šādas datnes:
- dagr-connector.jar jeb datu devēja savienotāja aplikācija. Datu devēja savienotāja jaunākā versija vienmēr pieejama:
- Produkcijas vidē (stabilā versija): https://dagr.gov.lv/download/dagr-connector
- Testa vidē (testa versija): https://test.dagr.gov.lv/download/dagr-connector
- application.conf jeb konfigurācijas fails, kas satur informāciju par pieslēgumu DAGR kodolam (datu devēja savienotāja identifikators, privātā atslēga, DAGR kodola adreses), informāciju par datu avotu (avota veids, avota pieslēguma informācija), ceļu uz datu avota definīciju, savienotāja darbināšanas biežumu u.c. konfigurācijas parametrus.
- connector.yaml jeb datu struktūras kartējuma fails, kas nosaka, kā dati no datu avota struktūras transformējami uz DAGR pašapkalpošanās portālā definēto datu kopas mērķa datu struktūru.
- logback.xml jeb žurnalēšanas uzstādījumu fails, kas definē datu devēja savienotāja žurnāla pierakstu veidošanas apjomu.
¶ Vides sagatavošana
DAGR datu devēja savienotāja darbināšanai nepieciešama JAVA 17. Datu devēja savienotāju iespējams darbināt uz darbstacijas, fiziskajiem serveriem, virtuālajiem serveriem, kā arī konteinerizācijas platformās.
Vienkāršs veids, kā uzinstalēt nepieciešamo JAVA versiju uz Windows darbstacijas, aprakstīts labās prakses piemēros:
Pieejams arī apraksts, kā datu devēja savienotāju darbināt Kubernetes platformā.
¶ Konfigurācijas sagatavošana
Datu devēja savienotāja vispārējā konfigurācija tiek glabāta failā ar nosaukumu "application.conf".
¶ Minimālā nepieciešamā konfigurācija
dataset_names = bss_pet_report
datasource_type = jdbc
target_server_uri = "https://test.dagr.gov.lv"
provider.key = "MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQCiqEiuBAjfopw2oDu0tq3VonE1XoOlCzP58etLS0FTq+Ff7uCqYJm9X3P26NyCnKY+C+w7Su/qBpaSYol5s1+yAWQkiXaB3t9sXVRqnIrKboAm4YNKMIpqN2HctiWZepVn8+4R0xH1H9GXFeP0TIlWRc1Cvit4OBjyjuzMhRif0xaij6T1T3YAhLf0nqh1RsUdWg0GGGGOAxQ2+boDf+fqrjeWMYeXp7lxYXs69T8OygBYhiRg8ca6hivbLbRxOfpkt0C4oOg6pEuqptK0wUVrHwUeaDA+oINKcqmFeQpAgHr9n/MDqcyzQUoCoI2x0ajnUom1IhFYQ1XC1G+JJYCnAgMBAAECggEABXyy0vf83/p0KvLrK19Rlu2KGc2h7ZfmqCMNQnbRRy7QWrRMF5ihpxNIw1wQpZv+Oa/yR1UcVHiQwh3D2yX+GkWqE1d1zCTGGbmTnEhtStiWcc6qvKki347AZOSEzobQR8z2oNr4y0bzAutF9jBSHmXFal/QR0JxM6w2+HacTDaSI8ThFXcK01pGyN2IUIo9ephjTZfNVfY4ja53wsqNWll5JMeKoB0vLACVzze0/8kLUsxJnALL7xhpPR7tnjkR2MS4y/xDHBar2SH9U7oh6xyQbdAfoKBIUX8EQmP5WdH5vjjUL8Ec9txgxuxWVhqPEJFr4X7Q2WZ9Ea4UPBjLnQKBgQDBYR5nCjS5RhjrvTiWKjtLiBYhSSz3+nJPHM9z/3mgoLsAEMV873MimsDCJkqFWwGKi+2Wv+0Yrr7F/fjBl4BFotVf2yptU31ezeK7ptppbYf90JZV7/uhIIbaOFDbJCTc/Nfw2ROHWxnlehj0nM++DATXj7dwFFza3ezYaRRS5QKBgQDXVFpjwyQfFm0r3VoV1fO3Pipcj8Rq5ZRMw/lHve7o/IsA6iQRVfTK4p8L5VgU6OhtBGU/h8RTC3zxUHW6CUt2cMy4HtJGI0FBm3U9R5dF6c+DAUFAwWfi04UNVr2lOYAB8tHhe9Hq84dA8ymGO95KmmcjREWh9Eqz7BYDmnUQmwKBgGONpwQu6eOz5aJ/IIGWLj59Sb9LF752DaES2O4DyM7b0EmBWNovv5tCBhgtdFHg/xMfZGomVl5Nn+L4E7c+UogHA0g84UO1JqbG4YHvrSN3gvo1ByAo0ucpgqMXOPEIU339IQJaDsaxLMzJpc1QaVaSg2+iCjLGGOOIOqVSu2bNAoGBAMZitRSMyU7K/rIXMdREVlJRN/4nhrNl6QgA1j4+w0pswjSJg8llBC+YMyhmmIxLOTiXgCDUGRDZ2LcLhitsPNZWfoZz/w8XlBu5+n4G41xKWiE8mr3qcqgMcN0lOXxsSX+CE9RGm9R3ofk5DtzZc6gQMU3QrMbVp620qWOQfqJZAoGBAKnyTMZP6ftV3+6Yr8byMcAgfZ1NKjqdqPDcUvfLADKo0V8yxCv+aQVydn6rNwByOYpHU5vvNATFkgVpRK8tUnPX99UICi1eRwdzaz1xUxqW98++0ipd6eT7sDBl9yM4yaYKBqGE18babO4XF0iP95ujMqVsrDO3UxxMKOflL+NU"
provider.client_id = "BSS_DDS_01"
jwt.service.uri = "https://test.dagr.gov.lv/jwt/connect/token"
jwt.payload-audience = "urn:TEST-LNB:DAGR.STS/connect/token"
jwt.scope = "producer"
metadata_file = "./connector.yaml"
# If "akka.quartz.schedules.connector" is set to null, connector will run once and exit
akka.quartz.schedules.connector = null
jdbc {
data {
jdbcUrl = "jdbc:postgresql://localhost:5432/test_db"
username = "root"
password = "root"
}
}
¶ Konfigurācijas skaidrojumi
¶ Pilnā references konfigurācija
####### DAGR CONNECTOR CONFIG #######
pekko.http.client.connecting-timeout = 13s
pekko.http.client.idle-timeout = 11 s
pekko.http.host-connection-pool.max-open-requests = 2
pekko.http.host-connection-pool.max-retries = 0 # Konektivitātes atkļūdošanai. Ja > 0, noderēs do_connection_test
pekko.stream.materializer.subscription-timeout.timeout = 31s
pekko.quartz.defaultTimezone = "Europe/Riga"
# If "pekko.quartz.schedules.connector" is set to null, connector will run once and exit
# Seconds(0-59,-*/) Minutes(0-59,-*/) Hours(0-23,-*/)
# Day_of_month(1-31,-*?/LW) Month(1-12/jan-dec,-*/) Day_of_week(1-7/sun-sat,-*?/L#)
# '*' - all, '?' - any, '-' - interval, ',' - extra values separator, '/' - increment, i.e. 5/15 is 5,20,35,50
# 'L' - last, 'W' - weekday, '#' - nth of month, i.e. 6#3 is third friday
pekko.quartz.schedules.connector {
description = "Sends data changes to DAGR REST API"
expression = "*/12 * * ? * *"
}
data.datetime.truncate_to = seconds # Datumlaika saīsināšana, ja te nav null. Iespējamās vērtības: seconds, millis, micros, nanos
data.timezone = "Europe/Riga" # tiek izmantots, lai formatētu dateTime datus
data.validation = enforced # Vērtības: enforced, enabled, off. Ja enforced vai enabled, pārbaudīs atbilstību metadatu failā norādītajam obligātumam un šablonam.
dataset_names = my_service # datu kopu (servisu) nosaukumi DAGR sistēmā
datasource_type = csv # csv vai jdbc vai json vai dagr
do_connection_test = false # Konektivitātes atkļūdošanai - vai pirms datu sūtīšanas vispirms sūtīt tukšu datu kopu, lai pārliecinātos par konekcijas darīgumu
connection_test_interval= 55 s # Konektivitātes atkļūdošanai - laiks, kas pagājis kopš iepriekšējās datu sūtīšanas, kad jāizpilda konekcijas tests, (sk. augstāk)
dry_run = false # Testēšanas nolūkiem. Ja true - neveiks izmaiņas uz servera
dry_run_full = false # Testēšanas nolūkiem. Ja true - neprasīs statusu un neveiks izmaiņas uz servera
report_duplicates = true # Ienākošo datu kvalitātes pārbaude
delete_unpaired_records = true # Vai dzēst ierakstus, kuri neatradās ienākošajā ("lokālajā") datu kopā
target_server_data {
validate_on_startup = false # Atkļūdošanai. Vai pirms pirms pirmās sinhronizācijas salīdzināt (ja iespējams) datus DAGR datu izmaiņu rindā un DAGR datubāzē
}
target_server_uri = null # "https://dagr.gov.lv/" # DAGR serveris, kas saņems datus
provider.key.path = null # path to private key file
provider.key = null # "MIICeAIBAD..." # private key if provider.key.path is not set
provider.client_id = null # "MY_ORG_connector_X"
jwt.service.uri = null # "https://dagr.gov.lv/Identities.STS/connect/token"
#jwt.service.with-host-header = true
jwt.payload-audience = null # "urn:LNB:DAGR.STS/connect/token"
jwt.scope = producer
metadata_file = "./connector.yaml"
input-files = "/tmp" # mape failiem papildus uzdevumu veikšanai (attiecas uz atsevišķiem konektoru tipiem, piem. fpr, ur)
progress_report_interval= 10 s # cik bieži atskaitīties par tekošo statusu
# Automātiskie paziņojumi tehniskajām kontaktpersonām
report_problems.by_email = false
report_problems.interval = 30 m
report_problems.timezone = "Europe/Riga" # tiek izmantots datumlaika formatēšanai automātiskajos paziņojumos
# Informācija par konektora stāvokli
report_status.connector_config = true # nosūtīt konektora konfigurāciju, izņemot jebkādus 'key', 'password', 'secret' un 'username'
# Šī sadaļa attiecas tikai uz csv konektoru ----------------------------------
# codifs.json - outer object key is codif name, inner object represents codif keys and values
csv.codifs_file = null # ${csv.files.directory}/codifs.json
csv.files {
directory = "."
filename_pattern = ${dataset_names}.csv
fields_delimiter = ","
encoding = "UTF-8" # https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html
date_format = "[d.M.u[.]][M/d/u][u-M-d]"
datetime_format = "[[u-M-d][u.M.d][' ']['T']H:m[:s][.SSS][.SS][.S]['X']['Z'][Z]]"
has_header = true
}
# Šī sadaļa attiecas tikai uz jdbc konektoru ---------------------------------
jdbc {
use_connection_pool = true
data {
jdbcUrl = "jdbc:hsqldb:mem:main"
username = "SA"
password = ""
# Ja use_connection_pool ir true, tad tiks ņemti vērā papildus iestatījumi:
# https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby
maximumPoolSize = 1
readOnly = true
}
}
# Šī sadaļa attiecas tikai uz json konektoru ---------------------------------
json.files {
directory = "."
filename_pattern = ${dataset_names}.json
}
¶ Izmantojot Debezium
¶ Piemēri
¶ Datu kopu definīcijas
Gaisakuģu saraksts izmēģinājumu vidē (sandbox)
Šī ir pavisam vienkārša viena līmeņa labās prakses piemēra datu kopa.
name: bss_airship_register
key: registration_mark
data_description: Gaisa kuģu reģistrs, labās prakses piemērs
fields:
- registration_mark : Reģistrācijas numurs
- model : Modeļa numurs
- construction_year : Izražošanas gads
- serial_number : Sērijas numurs
- registered_on : Reģistrācijas datums
- aircraft_model_category : Gaisa kuģa kategorija
Atskaites par mājdzīvniekiem izmēģinājumu vidē (sandbox)
Šī ir sarežģītāka vairāku līmeņu labās prakses piemēra datu kopa.
name: bss_pet_report
key: Code(, Year, Id)
data_description: Atskaite par personas mājdzīvniekiem, labās prakses piemērs
fields:
- Id : Pārskata identifikators
- Code : Personas kods
- Name : Vārds
- Surname : Uzvārds
- Year int : Gads
- Submitted timestamp : Atskaites iesniegšanas datums un laiks
- Status : Pārskata statuss
- Pets * :
comments : Mājdzīvnieku saraksts
fields:
- Species : Suga
- Breed : Šķirne
- Age int : Vecums
- Name : Vārds
Latvijas goda ģimenes apliecības pamata vidē (dataset)
Šis ir faktiskas datu kopas definīcijas piemērs ar vienlīmeņa datu struktūru.
name: sif_honourable_family_card
comments: "Latvijas Goda ģimenes apliecību dati"
data_owner_code: "90001237779"
data_owner_name: Sabiedrības integrācijas fonds
data_description: Latvijas Goda ģimenes apliecību dati
subject_type: persona
subject_id_fieldname: personas_kods
key: personas_kods
fields:
- numurs : Apliecības numurs
- vārds : Apliecības turētāja vārds
- uzvārds : Apliecības turētāja uzvārds
- personas_kods : Apliecības turētāja personas kods
- tips : Apliecības tips
- izveidošanas_datums date : Apliecības izveidošanas datums
- derīguma_termiņš date : Apliecības derīguma termiņš
- ir_anulētaboolean : Pazīme, ka apliecība ir anulēta
- hash : Apliecības kontrolsumma. 30 ciparu skaitlis, kas sākās ar 1234, turpinās ar apliecības numuru un noslēdzas ar 14 ciparu gadījuma skaitli.