Šajā piemērā datu devējs būs Brenguļu sākumskola, nododamie dati būs gaisa kuģu reģistrs un datu avots būs CSV fails.
¶ Pieteikšanās par datu devēju
Neatkarīgi no izvēlētā datu nodošanas varianta, pirmais solis vienmēr ir pieteikties DAGR pašapkalpošanās portālā par datu devēju. DAGR pašapkalpošanās portāla adrese ir:
- Testa videi: https://test.dagr.gov.lv/
- Produkcijas videi: https://dagr.gov.lv/
Lai pieteiktos par datu devēju, ir jāautentificējas DAGR pašapkalpošanās portālā, tālāk sadaļā "Pieteikumu pārvaldība" jāizvēlas darbība "Datu avota pieteikums" un jāaizpilda pieteikuma forma. Pieteikuma formā norādītajām kontaktpersonām būs iespēja datu devēja vārdā pārvaldīt tehniskos pieslēgumus. Ja datu nodošanas realizācijai tiek piesaistīti ārējie izstrādātāji, tiem piekļuvi rekomendējams dot tikai DAGR testa videi. Kad pieteikums ir reģistrēts, jāpagaida, kamēr DAGR administrators to apstiprinās.
Šī piemēra ietvaros par datu devēju izmantosim Brenguļu sākumskolu ar reģistrācijas numuru 40900031421.
¶ Datu struktūras definēšana
Šī piemēra ietvaros nodosim uz DAGR gaisa kuģu reģistra datus. Piemērā izmantota faktiska Latvijas Atvērto datu portālā pieejama datu kopa - https://data.gov.lv/dati/lv/dataset/gaisa-kugu-registrs.
Pirmais solis datu struktūras definēšanas procesā ir izplānot datu kopas struktūru un reģistrēt to DAGR pašapkalpošanās portāla sadaļā "Izplatīšana" -> "Datu kopas". Pilnā piemērā izmantotā datu struktūras definīcija ir šāda:
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
Uzmanība pievēršama dažām būtiskām niansēm:
- Datu kopas nosaukums. Skatīt rindiņu
name: bss_airship_register. Atbilstoši datu kopu nosaukumu veidošanas rekomendācijām, datu kopa sākas ar "bss", kas ir Brenguļu sākumskolas saīsinājums. Tam seko datu kopas angliskais nosaukums ar mazajiem burtiem, vārdus atdalot ar apakšstrīpu. - Ieraksta atslēga. Skatīt rindiņu
key: registration_mark. Datu kopas ierakstiem tiek izmantota vienkārša atslēga, kas sastāv no viena datu lauka - gaisa kuģa reģistrācijas numura. Šī atslēga reizē nodrošinās ieraksta unikalitāti un kalpos kā meklēšanas parametrs datu ņēmēju ierakstu izgūšanas pieprasījumiem. -
- Komentāri. Ņemot vērā, ka no datu kopas datu struktūras definīcijas tiek automatizēti izveidoti datu izgūšanas servisu apraksti, ir būtiski, lai datu kopas definīcija satur visus iespējamos komentārus, tajā skaitā:
- Datu kopas īsu aprakstu (šajā piemērā
data_description: Gaisa kuģu reģistrs, labās prakses piemērs); - Katra datu lauka pilnu nosaukumu (piemēram
- registration_mark : Reģistrācijas numurs).
- Datu kopas īsu aprakstu (šajā piemērā
- Komentāri. Ņemot vērā, ka no datu kopas datu struktūras definīcijas tiek automatizēti izveidoti datu izgūšanas servisu apraksti, ir būtiski, lai datu kopas definīcija satur visus iespējamos komentārus, tajā skaitā:
Šādi izskatās piemērā dotā datu struktūras definīcija pēc tās reģistrēšanas DAGR pašapkalpošanās portālā:
Kad datu kopas datu struktūras definīcija ir saglabāta, tā parādīsies priekšlikumu vidē (sandbox). Priekšlikumu vide ir DAGR apgabals, kas paredzēts datu nodošanas testēšanai un datu kopas apskatei pirms tās galīgās apstiprināšanas. Šajā piemērā, pēc datu kopas saglabāšanas, ar to saistītie DAGR REST API servisi parādās adresē https://test.dagr.gov.lv/api-docs/sandbox/40900031421/, kur 40900031421 ir datu devēja reģistrācijas numurs. Priekšlikumu vidē datu kopa pieejama tikai pašam datu devējam.
Vizuāli servisu apraksti izskatās šādi:
Kad datu devējs ir ar datu kopas definīciju apmierināts, jālūdz DAGR administrators šo datu kopu apstiprināt. Pēc apstiprināšanas datu kopa būs pieejama DAGR pamata katalogā (dataset). Respektīvi, datu kopas definīcija tiks nodota uz VIRSIS, kur datu devējs varēs piešķirt datu piekļuves atļaujas potenciālajiem datu ņēmējiem.
¶ Datu devēja savienojuma reģistrēšana
Lai varētu sākt nodot datus uz DAGR, izmantojot datu devēja savienotāju, vispirms DAGR pašapkalpošanās portālā ir jāreģistrē savienojums. To var veikt jebkurš lietotājs, kurš apstiprinātajā datu devēja pieteikumā norādīts kā kontaktpersona. Savienojumi reģistrējami DAGR pašapkalpošanās portāla sadaļā "DAGR" -> "Savienotāji".
Piebilde: DAGR portālā un citur dokumentācijā tiek izmantoti divi līdzīgi termini - "savienotājs" un "savienojums". Atšķirība ir tāda, ka savienojums ir noteiktam datu devējam vai datu patērētājam piesaistīti pieslēguma rekvizīti, savukārt savienotājs ir DAGR projekta ietvaros izstrādāta JAVA aplikācija, kas DAGR kodolam pieslēdzas ar noteiktu aplikācijas konfigurācijā norādītu savienojumu jeb pieslēguma rekvizītiem.
Reģistrējot jaunu savienojumu, jānorāda:
- Savienojuma nosaukums. Tiek izmantots informatīviem nolūkiem tikai DAGR pašapkalpošanās portāla ietvaros. Nosaukuma izvēle ir pilnīgi datu devēja vai patērētāja ziņā;
- Savienojuma identifikators. Šis ir savienojuma unikālais identifikators, kas DAGR REST API ietvaros tiek saukts par "client_id". Unikālais identifikators veidojams, izmantojot tikai latīņu burtus un apakšsvītras. Stingra rekomendācija: Savienotāja identifikatoram par prefiksu vēlams izmantot datu devēja nosaukuma saīsinājumu.
- Savienojuma tips. Jānorāda, vai tiek reģistrēts datu devēja vai datu patērētāja savienojums.
- Aktīvs. Pazīme, vai savienojums ir aktīvs;
- Talona dzīves laiks, s. Drošības talona dzīves ilgums sekundēs, kas pēc noklusējuma ir 900 sekundes.
Šī piemēra ietvaros Brenguļu sākumskolai reģistrēsim datu devēja savienotāju ar identifikatoru BSS_DDS_01:
Kad savienotājs ir reģistrēts, tam ir jāpievieno drošības sertifikāts. DAGR no pievienotā sertifikāta saglabā publisko atslēgu, kura pēc tam tiek izmantota, lai pārbaudītu, vai drošības talona pieprasījums parakstīts ar saistīto privāto atslēgu. DAGR pievienojamais x509 sertifikāts var būt arī pašparakstīts. Pastāv vairāki varianti, kā iegūt pašparakstītu X.509 sertifikātu. Piemēram, izmantojot OpenSSL komandrīku, to var paveikt ar šādām komandām:
openssl genrsa -out c:\temp\nosaukums.key 2048
Šī komanda ģenerē privāto atslēgu, kas pēc tam būs nepieciešama, lai parakstītu drošības talona pieprasījumu. Privātā atslēga paliek pie datu devēja un tās aizsargāšana ir datu devēja pienākums.
openssl req -key c:\temp\nosaukums.key -new -x509 -subj "/C=LV/ST=Riga/L=Riga/O=Iestades_nosaukums/OU=IT/CN=nosaukums" -days 365 -out c:\temp\nosaukums.crt
Šī komanda ģenerē pašparakstītu X.509 sertifikātu, kuru jāpievieno DAGR reģistrētajam datu patērētāja savienotājam.
Piemērā izmantotā privātā atslēga: bss_demo.key
Piemērā izmantotais sertifikāts: bss_demo.cer
Stingra rekomendācija: Ja datu devējs caur DAGR izplata vairākas datu kopas no vairākiem avotiem, tad katram avotam rekomendējams reģistrēt un izmantot savu savienojumu.
¶ Datu devēja savienotāja uzstādīšana
Datu devēja savienotājs ir JAVA aplikācija, kas izgūst datus no datu avota, tos transformē un nodod uz DAGR kodolu, izmantojot DAGR REST API. Šajā piemērā parādīts kā datu devēja savienotāju uzstādīt Windows vidē.
¶ Solis 1 - JAVA 17 instalācija
Pieņemam, ka instalējam JAVA 17 Windows vidē.
Vispirms lejupielādējam bināro instalāciju no ražotāja mājas lapas -https://download.oracle.com/java/17/archive/jdk-17.0.12_windows-x64_bin.exe
Tālāk palaižam instalāciju un sekojam grafiskajam vednim.
Pēc instalācijas pārliecināmies, ka JAVA ir veiksmīgi uzstādīta, izpildot komandu java -version.
Var gadīties, ka java komanda netiek atpazīta. Tādā gadījumā vajag pievienot ceļu uz java instalāciju Windows "path" vides mainīgajam.
¶ Solis 2 - datu devēja lejupielāde
Tālāk nepieciešams lejupielādēt jaunāko datu devēja savienotāja versiju. Tā ir pieejama:
- Produkcijas vidē (stabilā versija): https://dagr.gov.lv/download/dagr-connector
- Testa vidē (testa versija): https://test.dagr.gov.lv/download/dagr-connector
Ja aplikācija lejupielādējas bez paplašinājuma, to rekomendējams pievienot, pārsaucot aplikāciju par "dagr-connector.jar".
¶ Solis 3 - aplikācijas vispārējās konfigurācijas sagatavošana
Vienā mapē ar dagr-connector.jar izveidojam konfigurācijas failu ar nosaukumu "application.conf" un iekopējam šajā failā šādu konfigurāciju:
dataset_names = bss_airship_register # datu kopu (servisu) nosaukumi DAGR sistēmā
datasource_type = csv
target_server_uri = "https://test.dagr.gov.lv" # DAGR serveris, kas saņems datus
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
csv.files {
directory = "./data"
filename_pattern = "test.csv"
fields_delimiter = ","
encoding = "UTF8" # 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 = false
}
Pilna references konfigurācija pieejama programmatūras integrācijas instrukcijā. Bet šeit pāriesim pāri piemērā izmantotajai konfigurācijai:
- dataset_names - te ir norādīts datu kopas nosaukums;
- datasource_type - datu avota tips, šajā gadījumā CSV;
- target_server_uri - ja dati tiek nodoti standarta režīmā (dataset), tad DAGR adrese, piemēram https://test.dagr.gov.lv. Bet ja dati tiek nodoti priekšlikumu videi (sandbox), tad adrese formā
https://{dagr_adrese}/sandbox/{datu_devēja_reģ_numurs}, piemēram, https://test.dagr.gov.lv/sandbox/40900031421; - provider.key - izveidotā datu devēja savienojuma privātās atslēgas saturs;
- provider.client_id - izveidotā datu devēja savienojuma identifikators;
- jwt.service.uri - drošības talona pieprasījuma adrese;
- jwt.payload-audience - drošības talona pieprasījuma audience;
- jwt.scope - drošības talona pieprasījuma loma - producer, ja drošības talonu pieprasa datu devējs vai consumer, ja drošības talonu pieprasa datu ņēmējs;
- metadata_file - konfigurācijas fails, kas definē datu avota (šajā gadījumā CSV faila) struktūru;
- akka.quartz.schedules.connector - datu aktualizācijas biežums, kas pierakstīts kā Linux Cron izteiksme. Ja tiek datu aktualizācija veicama tikai vienu reizi uzreiz pēs datu devēja savienotāja palaišanas, tad te var norādīt null vērtību;
- csv.files - sadaļa satur papildus konfigurāciju, kas attiecināma uz CSV failu;
- csv.files.directory - CSV faila atrašanās vieta;
- csv.filename_pattern - CSV faila nosaukums;
- csv.fields_delimiter - lauku atdalītājs;
- csv.encoding - formatējums;
- csv.date_format - datuma formatējums;
- csv.datetime_format - datumlaika formatējums;
- csv.has_header - pazīme, vai CSV fails satur kolonnu nosaukumus pirmajā rindā.
¶ Solis 4 - CSV faila satura konfigurācija
Vienā mapē ar dagr-connector.jar izveidojam konfigurācijas failu ar nosaukumu "connector.yaml" un iekopējam šajā failā šādu konfigurāciju:
name: bss_airship_register
table:
key: registration_mark
fields:
- registration_mark
- model
- construction_year
- serial_number
- registered_on
- aircraft_model_category
connector.yaml fails priekš datu devēja savienotāja apraksta avota struktūru. Precīzāk:
- name - norāda datu kopas nosaukumu;
- table - norāda tabulas nosaukumu, ja datu avots ir JDBC. Faila gadījumā jāatstāj tukšs;
- key - norāda atslēgas lauku;
- fields - uzskaita datu laukus tādā secībā, kā tie ir failā. Lauku nosaukumiem ir jāsakrīt ar tiem, kas ir izmantoti datu kopas definīcijā. Lauku nosaukumi var nesakrist ar kolonnu nosaukumiem CSV faila galvenē, ja tāda ir.
¶ Solis 5 - žurnalēšanas konfigurācija
Vienā mapē ar dagr-connector.jar izveidojam konfigurācijas failu ar nosaukumu "logback.xml" un iekopējam šajā failā šādu konfigurāciju:
<configuration scan="true" scanPeriod="15 seconds" >
<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
<!-- encoders are assigned the type
ch.qos.logback.classic.encoder.PatternLayoutEncoder by default -->
<encoder>
<pattern>%d %highlight(%-5level) %-15logger{15} -%kvp- %msg%n%ex{0}</pattern>
</encoder>
</appender>
<logger name="com.zaxxer.hikari" level="warn"/>
<logger name="dagr.data" level="warn"/>
<logger name="dagr.http" level="warn"/>
<logger name="org.quartz" level="warn"/>
<root level="info">
<appender-ref ref="STDOUT" />
</root>
</configuration>
logback.xml konfigurācijas fails atbild par datu devēja savienotāja žurnalēšanas iestatījumiem. Pēc noklusējuma tie ir "info" vai "warn" līmenī. Bet atkļūdošanas nolūkiem var lietot līmeni "debug".
¶ Solis 6 - datu iekopēšana
Novietojam datu failu konfigurācijā norādītajā mapē. Mūsu piemērā tā ir mape "data", kas izvietota blakus datu devēja savienotājam.
Skatīti datu failu: test.csv
Pēc tam, kad dati tiks nolasīti, datu devēja savienotājs pievienos failam paplašinājumu ".done". Respektīvi, mūsu piemērā test.csv pārtaps par test.csv.done.
¶ Solis 7 - palaižam datu devēja savienotāju
Palaižam datu devēja savienotāju, izpildot komandu:
java -Dconfig.file=./application.conf -Dlogback.configurationFile=./logback.xml -cp ./dagr-connector.jar dagr.Connector
Datu devēja savienotājs pēc palaišanas secīgi veic šādas darbības:
- pārbauda konfigurāciju,
- pieprasa drošības talonu no DAGR REST API,
- lejupielādē datu kopas ierakstu kontrolsummas,
- nolasa datus no datu avota (šajā gadījumā CSV faila),
- nosaka ierakstus, kuros ir izmaiņas, aprēķinot kontrolsummas no datu avota nolasītajiem datiem un salīdzinot tās ar kontrolsummām, kas saņemtas no DAGR REST API,
- nodod mainītos ierakstus uz DAGR REST API.
Rezultātā datu devēja savienotājs parādīs datu nodošanas kopsavilkumu:
Vērība jāpievērš rindiņai Sync done bss_airship_register (file test.csv): 0 inserts, 0 updates, 0 deletes, 374 skips, kas pasaka datu kopas nodošanas statusu. Šajā gadījumā neviens jauns ieraksts netika pievienots, mainīts vai dzēsts, jo datu nodošanas procedūra tika izsaukta atkārtoti ar tiem pašiem datiem.