Šajā piemērā datu devējs būs Brenguļu sākumskola un nododamie dati būs izglītības dokumenti.
DAGR REST API piemērs izvēlēts kā pirmais, jo tas labi ilustrē DAGR pamatprincipus un neprasa vienu pārējiem datu nodošanas veidiem nepieciešamu soli - datu devēja savienotāja komponentes izmantošanu.
Izmantojot DAGR REST API, datu devējs var pats pilnā mērā kontrolēt datu nodošanu uz DAGR.
¶ 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 informāciju par personu izglītību. Piemērā izmantotā datu struktūra ir atvasināta no faktiskas DAGR sistēmā publicētas datu kopas datu struktūras.
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_person_education
key: PersonCode(, Id)
data_description: Izglītības dokumenti, labās prakses piemērs
fields:
- Id int: izglītības dokumenta ID
- PersonCode: Personas kods
- PersonName: personas vārds
- PersonOtherNames: personas citi vārdi
- PersonSurname: personas uzvārds
- EducationDegreeId int: Izglītības pakāpes ID
- EducationDegree: Izglītības pakāpe
- EducationTypeId int: Izglītības veida ID
- EducationType: Izglītības veids
- EducationDocumentTypeId int: Dokumenta veida ID
- EducationDocumentType: izglītības dokumenta veids
- InstitutionName: Izglītības iestādes nosaukums
- DocumentIssueDate date: izglītības dokumenta izsniegšanas datums
- EducationProgramName: izglītības programma
- Specialities * :
comments: Specialitāte
fields:
- Name
- Qualifications * :
comments: Kvalifikācija
fields:
- Name
- Series: sērija
- Number: numurs
- MainEducationTypeId int:
- MainEducationType:
- ModifiedOn dateTime: izmaiņu datums
Uzmanība pievēršama dažām būtiskām niansēm:
- Datu kopas nosaukums. Skatīt rindiņu
name: bss_person_education. 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: PersonCode(, Id). Datu kopas ierakstiem tiek izmantota salikta atslēga, kas sastāv no personas koda un ieraksta identifikatora avota sistēmas datu bāzē. Personas kods tiek izmantots meklēšanas nolūkiem. Respektīvi, lai dotu iespēju datu ņēmējiem datu kopas ierakstus izgūt pēc personas koda. Taču vienai personai var būt vairākas izglītības, tamdēļ ieraksta unikalitātes nodrošināšanai personas kods papildinās ar ieraksta datu bāzes identifikatoru. Saliktās atslēgas daļa, kas nav obligāti izmantojama meklējot ierakstus, ir iecelta iekavās. - Hierarhija. Šīs datu kopas datu struktūra ir hierarhiska. Katrs no ierakstiem var saturēt sarakstu ar specialitātēm un kvalifikācijām. Hierarhijas augšējo līmeni reprezentē objekta nosaukums, kas beidzās ar zvaigznīti (piemēram:
- Specialities * :). Nākamajās rindiņās ar divu tukšuma zīmju lielāku atstarpi no kreisās malas ir saraksta nosaukums (piemēram:comments: Specialitāte) un tam seko sarakstā iekļauto ierakstu datu lauku uzskaitījums. - 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: Izglītības dokumenti); - Katra datu lauka pilnu nosaukumu (piemēram
- PersonCode: Personas kods); - Hierarhisko objektu nosaukumus (piemēram
comments: Specialitāte).
- Datu kopas īsu aprakstu (šajā piemērā
Šā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 saraksts 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 nodošana
¶ Datu devēja savienojuma reģistrēšana
Lai varētu sākt izmantot DAGR REST API, 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. DAGR REST API izmantošanas kontekstā gan ar savienojumu, gan ar savienotāju tiek saprasti pieslēguma rekvizīti.
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, kas 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.
¶ Drošības talona pieprasīšana
DAGR REST API lieto RFC 7519 standartam atbilstošus JWT drošības talonus. Lai izmantotu datu nodošanai nepieciešamos DAGR REST API servisus, vispirms ir jāiegūst JWT drošības talons.
Drošības talonu pieprasīšana un izsniegšana notiek saskaņā ar OAuth 2.0 OpenId Connect standarta Client Credentials Flow plūsmu. Talona pieprasīšanas adrese:
- Testa vidē: https://test.dagr.gov.lv/jwt/connect/token
- Produkcijas vidē: https://dagr.gov.lv/jwt/connect/token
Drošības talona izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/jwt/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Cache-Control: no-cache' \
--data-urlencode 'client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer' \
--data-urlencode 'client_assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJCU1NfRERTXzAxIiwianRpIjoiOTM0MDljYWMtYzU5ZC00NjRkLTg3MTgtNGM5MTliOGZhY2Y5IiwiaXNzIjoiQlNTX0REU18wMSIsImF1ZCI6InVybjpURVNULUxOQjpEQUdSLlNUUy9jb25uZWN0L3Rva2VuIiwiZXhwIjoiMTcyNDMzMTk0NSIsIm5iZiI6IjE3MjQzMjgzNDUifQ.xUV_IJcJRnELzJGznNpqsat-GVx8HesuRMg8-5bm7iAQIwNOIX6qLQR5_eKeogloIFNzYwd1ohOZkahByfC3fXUubX6ejVKnzn9NB-e45LBAOHQfkwYM2LV1_xX2w9dUuZg2vd3LFB8DUh7uRAg1SAV8yEVSrM26wua-4io0gDxf3VyBTLp0u3tdeUAAv9haS2XOCUcw1ku5iilFVdNnQlprZPjZ21Z3EL6Yr5mqSUrpnjQfnMJ8RGwpPupmv1XU82e8fPuwQedqofS6YxE5YUA93B99FK_2Yw0VXs8_b4Ng1hnx_nBq5wt5q5w4UK1kA7FFDErkzIEkw0rb6xr87g' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=BSS_DDS_01' \
--data-urlencode 'scope=producer'
Šajā izsaukumā client_id ir datu devēja savienojuma identifikators un client_assertion ir jāsagatavo atbilstoši RFC 7515 JSON Web Signature(JWS) standartam. Respektīvi, client_assertion sastāv no 'Header' un 'Payload', kas parakstīti ar savienojuma privāto atslēgu. ‘Header’ veidojams kā JSON objekts, kas satur paraksta parametrus, piemēram:
{
"typ" : "JWT",
"alg" : "RS256"
}
'Payload' ir iekļaujama šāda informācija (testa videi):
{
"sub": {savienojuma identifikators},
"jti": {uuid},
"iss": {savienojuma identifikators},
"aud": urn:TEST-LNB:DAGR.STS/connect/token,
"exp": {derīguma termiņš, max nbf + 1 stunda},
"nbf": {parakstīšanas datums un laiks}
}
Drošības talona izsaukuma atbildes piemērs:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46VEVTVC1MTkI6REFHUi5TVFMiLCJzdWIiOiJCcmVuZ3XEvHUgc8SBa3Vtc2tvbGEiLCJhdWQiOlsicHJvZHVjZXIiLCJ1cm46VEVTVC1MTkI6REFHUi5TVFMvcmVzb3VyY2VzIl0sImV4cCI6MTcyNDMyOTI0NywibmJmIjoxNzI0MzI4MzQ3LCJpYXQiOjE3MjQzMjgzNDcsIml6emlfaWVzdCI6ZmFsc2UsImxlZ2FsZW50aXR5IjoiNDA5MDAwMzE0MjEiLCJjbGllbnRfaWQiOiJCU1NfRERTXzAxIiwic2NvcGUiOlsicHJvZHVjZXIiXX0.sZ3IvN6u-uQ_doH3z2BDWxApuZePuEhu0i9RGem5nIC1soavZxTOhfhnJQU2ezkhtS7AULb7phMigorm3QGH_ogPyozj5mZ5j_QD1J_nPytIra4vbf6XHEN2PP2rDSvNq4QeFV75j_claYN5GUw-A13SeD2ERjbw5QCWbDBR_kUvhRNzBX1qD3JfVHstQAWvrZcye-nqAqYsY17YdXp192MZhwjXFIYsgknPfMIuDSR8RCXD05FZ0-PCfuhOb82nWcYzMVgqhlB7P33t5EAbVxKnOnQsNcgFFRLQnGu1xfuk81JxuW70Ziqbmrg_wIV95Y-Ll_orWXqr0ZtPg48Xtw",
"expires_in": 900,
"token_type": "Bearer",
"scope": "producer",
"expires_epoch_utc": null
}
Drošības talona satura atšifrēšanai un pārlūkošanai ērti izmantot: https://jwt.io/
Saņemtais drošības talons tālāk norādāms DAGR REST API pieprasījumos galvenē ar nosaukumu "Authorization".
Postman piemēru kolokcija, kas satur drošības talona izsaukuma piemēru: https://api.postman.com/collections/9631194-f5ae9d8b-e437-43bf-81e3-efa82d55e37a?access_key=PMAT-01J6HM87W4DVPV39ZBJPCHF1J3
¶ Datu augšupielāde
Strukturēti dati uz DAGR nododami, izmantojot DAGR REST API servisu:
PUT {dagr_adrese}/sandbox/{datu_devēja_reģ_nr}/update/{datu_kopas_nosaukums}
izmantojams datu kopām priekšlikumu vidē (sandbox);PUT {dagr_adrese}/update/{datu_kopas_nosaukums}
izmantojams apstiprinātām (dataset) datu kopām.
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"
}]
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 uzskatī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, 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:
curl --location --request PUT 'https://test.dagr.gov.lv/sandbox/40900031421/update/bss_person_education' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpc3MiOiJ1cm46VEVTVC1MTkI6REFHUi5TVFMiLCJzdWIiOiJCcmVuZ3XEvHUgc8SBa3Vtc2tvbGEiLCJhdWQiOlsicHJvZHVjZXIiLCJ1cm46VEVTVC1MTkI6REFHUi5TVFMvcmVzb3VyY2VzIl0sImV4cCI6MTcyNDc1NDczMiwibmJmIjoxNzI0NzUzODMyLCJpYXQiOjE3MjQ3NTM4MzIsIml6emlfaWVzdCI6ZmFsc2UsImxlZ2FsZW50aXR5IjoiNDA5MDAwMzE0MjEiLCJjbGllbnRfaWQiOiJCU1NfRERTXzAxIiwic2NvcGUiOlsicHJvZHVjZXIiXX0.vtKQaCqqwkbcUV9auBS2QnLSzZj7vGdFRkkxpa3mYpY1T53yBD_ugd4Iz8ZDDAK7TmuwdWzK1p_4CoETMbXjET1EXCOw0tjm599i0nYaiam0Mnz8ElkzpXjnEriHRFqIyfeeIRKxPPwQXYMgBNN0usOxBs3O8OauVSgLdfw759mAsztLgacI1_A0DplfY5i5Pw1Ed1EWoHGP3E5dLPrUKjvR_7jFWpMUpsph8SSF_DOwddnk0d-VVd2E0Z2uqwJZ7rM-ILBw2Cwbuc6CY04BdaZ29hpPo3XHIFwdamYLvlX-i1szwU3jAWvNSzBjrF6MVkYJR_7tSJlZqnq3hU_xrg' \
--data '[
{
"key": "32154511582/5854522",
"value": "{\n \"Id\": 5854522,\n \"PersonCode\": \"32154511582\",\n \"PersonName\": \"TIJA\",\n \"PersonOtherNames\": \"\",\n \"PersonSurname\": \"TEIVĀNE\",\n \"EducationDegreeId\": 4,\n \"EducationDegree\": \"Augstākā izglītība\",\n \"EducationTypeId\": 9,\n \"EducationType\": \"Profesionālais bakalaurs\",\n \"EducationDocumentTypeId\": 4,\n \"EducationDocumentType\": \"Diploms\",\n \"InstitutionName\": \"Rīgas Pedagoģijas un izglītības vadības akadēmija\",\n \"DocumentIssueDate\": \"2014-06-20\",\n \"EducationProgramName\": \"pirmsskolas un sākumskolas pedagoģija\",\n \"Specialities\": [],\n \"Qualifications\": [\n {\n \"Name\": \"Pirmsskolas izglītības un sākumskolas skolotāja\"\n }\n ],\n \"Series\": \"PD E\",\n \"Number\": \"3641\",\n \"MainEducationTypeId\": 2,\n \"MainEducationType\": \"Profesionālā izglītība\",\n \"ModifiedOn\": \"2024-04-04T12:22:58+03:00\"\n }"
},
{
"key": "32543115220/3741647",
"value": "{\n \"Id\": 3741647,\n \"PersonCode\": \"32543115220\",\n \"PersonName\": \"DITA\",\n \"PersonOtherNames\": \"\",\n \"PersonSurname\": \"KRŪMIŅA\",\n \"EducationDegreeId\": null,\n \"EducationDegree\": null,\n \"EducationTypeId\": 4,\n \"EducationType\": \"Arodizglītība\",\n \"EducationDocumentTypeId\": 9,\n \"EducationDocumentType\": \"Kvalifikācijas apliecība\",\n \"InstitutionName\": \"Daugavpils Tirdzniecības skola\",\n \"DocumentIssueDate\": \"2015-06-21\",\n \"EducationProgramName\": \"Ēdināšanas pakalpojumi\",\n \"Specialities\": [],\n \"Qualifications\": [\n {\n \"Name\": \"pavārs\"\n }\n ],\n \"Series\": \"KAB\",\n \"Number\": \"070414\",\n \"MainEducationTypeId\": 2,\n \"MainEducationType\": \"Profesionālā izglītība\",\n \"ModifiedOn\": \"2012-07-02T10:45:29+03:00\"\n }"
}
]'
Piemērā redzams, ka galvenē (header) tiek padots drošības talons un tālāk saturā (data) tiek padotas divas ierakstu vērtības, kas katra sastāv no atslēgas key un datiem value. Dati jeb value vērtība nododama string formātā, kas satur eskeipotu JSON vērtību.
Savukārt, lai signalizētu DAGR par ieraksta dzēšanu, ieraksta dati jānorāda kā null. Iepriekšējā piemērā iekļauto datu dzēšanas pieprasījums izskatītos šādi:
curl --location --request PUT 'https://test.dagr.gov.lv/sandbox/40900031421/update/bss_person_education' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '[
{
"key": "32154511582/5854522",
"value": null
},
{
"key": "32543115220/3741647",
"value": null
}
]'
Postman piemēru kolekcija ar augstāk aprakstītajiem piemēriem: https://api.postman.com/collections/9631194-f5ae9d8b-e437-43bf-81e3-efa82d55e37a?access_key=PMAT-01J6HM87W4DVPV39ZBJPCHF1J3
Piemēros izmantotie parauga dati: