¶ Veicamie soļi
| Nr. | Darbība | Apraksts |
|---|---|---|
| 0 | Iepazīties ar pieejamajiem datiem un servisiem. | Pirms uzsākt integrācijas darbus, rekomendējams iepazīties ar DAGR publicēto datu struktūrām un pieejamajiem datu izgūšanas servisiem. |
| 1 | Aizpildīt un iesniegt DAGR pieteikuma veidlapu. | Lai iegūtu piekļuvi DAGR pašapkalpošanās portālam un DAGR REST API saskarnei, ir jāaizpilda pieteikuma veidlapa. |
| 2 | Aizpildīt un iesniegt VIRSIS pieteikuma veidlapu. | Lai iegūtu piekļuvi VIRSIS sistēmai, kas ļauj pieprasīt piekļuvi DAGR publicētajām datu kopām, ir jāaizpilda pieteikuma veidlapa. |
| 3 | Pieteikties VIRSIS informācijas pakalpojumam. | Lai iegūtu piekļuvi datu kopai, VIRSIS sistēmā ir jāatrod datu devēja informācijas pakalpojums un uz to jāpiesakās. |
| 4 | Reģistrēt DAGR pašapkalpošanās portālā savienojumu. | DAGR pašapkalpošanās portālā ir jāreģistrē viens vai vairāki tehniskie pieslēgumi jeb savienojumi. |
| 5 | Izgūt datus izmantojot DAGR REST API. | Izmantojot reģistrēto savienojumu un VIRSIS atļaujas numuru, iespējams izgūt datus. |
¶ 0. Iepazīšanās ar pieejamajiem datiem
DAGR API ir aprakstīts OpenAPI (https://www.openapis.org/) standartam atbilstošā formātā un pieejams adresē: https://test.dagr.gov.lv/api
Datu izgūšanas servisu apraksti pieejami https://test.dagr.gov.lv/api sadaļā “Datu servisi”.
Savukārt saraksts ar visām datu kopām, kas tiek izplatītas caur DAGR, pieejams izmantojot servisu: https://test.dagr.gov.lv/service_list, kur katrai datu kopai ir norādīts:
- Datu kopas tehniskais un pilnais nosaukums;
- Datu devēja (īpašnieka) reģistrācijas numurs un nosaukums.
Katrai no datu kopām ir pieejams serviss, kas ļauj izgūt datu kopas ierakstus pēc objekta identifikatora, un serviss, kas ļauj izgūt sarakstu ar izmainītajiem ierakstiem. Izmainīto ierakstu servisu var izmantot gan pirmreizējai visu datu kopas ierakstu atklāšanai, gan jaunāko izmaiņu monitoringam. Atsevišķām datu kopām ir pieejami arī papildus izmaiņu saraksti, kas satur tikai noteiktus biznesa notikumus.
¶ 1. DAGR pieteikuma veidlapa
Lai iegūtu piekļuvi DAGR, ir jāaizpilda DAGR pieteikuma veidlapa. Vairāk informācijas: https://www.vraa.gov.lv/lv/datu-izplatisanas-un-parvaldibas-platforma
Kad ir saņemta atbilde par pieteikuma apstrādi, iesniegumā norādītās personas varēs pieslēgties DAGR pašapkalpošanās portālam.
¶ 2. VIRSIS pieteikuma veidlapa
Lai iegūtu piekļuvi VIRSIS, ir jāaizpilda veidlapa VIRSIS sistēmas iestādes lietotāja administratora izveidei un jānosūta uz VDAA e-adresi. Vairāk informācijas: https://www.vraa.gov.lv/lv/valsts-informacijas-resursu-sistemu-un-sadarbspejas-informacijas-sistema
Kad piekļuve saņemta, VIRSIS sistēmas iestādes lietotājs var izveidot lietotāju kontus pārējiem iestādes darbiniekiem, kam tas nepieciešams.
¶ 3. Pieteikšanās VIRSIS informācijas pakalpojumam
VIRSIS informācijas sistēmā ir jāatrod un jāizvēlas datu devēja informācijas pakalpojums, kas satur datu ņēmējam nepieciešamos datus.
Kad informācijas pakalpojums ir izvēlēts, uz to jāpiesakās. Pieteikšanās procesā būs jānoslēdz un jāparaksta vienošanās par pakalpojuma izmantošanu.
Parakstītās vienošanās numurs tālāk izmantojams kā datu piekļuves atļaujas numurs DAGR sistēmā.
¶ 4. Savienojuma reģistrēšana DAGR portālā
Pēc tam, kad ir apstiprināts datu ņēmēja pieteikums, ir jāreģistrē datu ņēmēja savienojums. Ja datu ņēmējam ir vairākas informācijas sistēmas, kas izgūst datus no DAGR, katrai rekomendējams reģistrēt savu savienojumu.
Datu ņēmēja savienojumus iespējams reģistrēt pašapkalpošanās portāla sadaļas “Piekļuve DAGR” apakšsadaļā “Savienotāji”. Šajā sadaļā ir pieejams saraksts ar visiem savienotājiem / savienojumiem:
Lai reģistrētu jaunu savienotāju, jāaizpilda forma:
Šajā formā jānorāda portālā savienotāja nosaukums (informatīva nozīme), identifikators (tiek izmantots REST API), pazīme, vai savienojums aktīvs, drošības talona dzīves cikla ilgums sekundēs un opcionāls apraksts.
Kad savienojums ir saglabāts, tam iespējams pievienot X.509 standarta drošības sertifikātu:
¶ Informācija par sertifikātu
DAGR pievienotos sertifikātus izmantoto, lai validētu drošības talonu pieprasījums. 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. MS Windows vidē to var izdarīt, uzinstalējot OpenSSL komandrīku un izpildot komandas:
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 patērētāja un tās aizsargāšana ir datu patērētā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.
¶ 5. Datu izgūšana
¶ Autentifikācija (drošības talona pieprasīšana)
Datu patērētāja savienotāji tiek autentificēti un autorizēti saskaņā ar OAuth 2.0 OpenId Connect standarta Client Credentials Flow plūsmu.
Lai izgūtu datus no DAGR, vispirms ir jāiegūst JWT drošības talons. Drošības talona pieprasīšanas adrese (testa vidē): https://test.dagr.gov.lv/jwt/connect/token
Drošības talona izsaukuma piemērs:
curl --location 'https://parvaldiba-test.dagr.gov.lv/Identities.STS/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.eyJzdWIiOiJWQVJBTV90ZXN0X2Nvbm5lY3Rvcl8xIiwianRpIjoiMmFiYWIyOTctNDViNC00ZjdkLTg5NWYtOTMxM2JlN2Q0ZTE1IiwiaXNzIjoiVkFSQU1fdGVzdF9jb25uZWN0b3JfMSIsImF1ZCI6InVybjpURVNULUxOQjpEQUdSLlNUUy9jb25uZWN0L3Rva2VuIiwiZXhwIjoiMTY4MTgyNDkzOSIsIm5iZiI6IjE2ODE4MjEzMzkifQ.cDurogXmRZljUQ7WHrF9A_pV26WSeljBZCKPx3QSDs4lA_c2oxSRVdn_laqSpNydlmGAEpD9o0dgvP7efwq-w7jldf_4lY8TJyrju_niPaE3krIVIlA_Auwv7q66k_TW6jjWUd2jGuqgDLYGuRMgIGTMYVv9qVN70ctEBRAJzLyVFZAK3Z72EOzv_YkKGxb4NnVf4CAbXl6qQSU5dAYz0DPbMvdHGH2AsMNsXeGTuSf7SVQvIl5CShMm1Kwr2D0B6tsruuAGcdj92Z8tupy2InDB-rti6cpTorTdNPQcClcegGbQDSt1SK9k7XsVJf4_Youe3EBCXIcCGindtxc2AQ' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=VARAM_test_connector_1' \
--data-urlencode 'scope=consumer' `
Šajā izsaukumā client_id ir jānorāda datu patērētāja savienotāja 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 datu patērētāja savienotāja 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": {datu patērētāja savienotāja id},
"jti": {uuid},
"iss": {datu patērētāja savienotāja id},
"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": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIxMEZCQkFCNzE3NzFCRTcyOTIyNTk0NTBBMjhDMjcyNzc5NTZFNkVSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IklRLTdxM0YzRy1jcElsbEZDaWpDY25lVmJtNCJ9.eyJuYmYiOjE2Nzk1MDYwODYsImV4cCI6MTY3OTUwOTY4NiwiaXNzIjoidXJuOlRFU1QtTE5COkRBR1IuU1RTIiwiYXVkIjoidXJuOlRFU1QtTE5COmRhZ3IuY29yZS5hcGkiLCJjbGllbnRfaWQiOiJVTklTT190ZXN0X2Nvbm5lY3Rvcl8xIiwibGVnYWxlbnRpdHkiOiI0MDAwMzU2Mjg2MyIsImp0aSI6IjA5OERGMTYyQ0Y2OEY0Mjk4OTJENTk3Qjk3RjlCNTBBIiwiaWF0IjoxNjc5NTA2MDg2LCJzY29wZSI6WyJkYWdyX2NvcmVfYXBpIl19.Cm0kgNBKfNR0Mo63ZLkCYMzPZ9v8XbfHWE1Lgvz907k1Ama2SqiWE68oMcBlAXJEUyYJ8ipQCY7aCmjVEN3AZ6qV1lcRPtURQ53EUKXs5B8S3aQfxOu2ne3rnDKhaZXi0rHRMTAUcTJWmeXWFA5m-FcvFrhZgTYuM2zq-L5VY-mgJ1VOzOXj9_5eUALBLHBLJF9lLPZQckao4VAn-Zwvly_sn1iojFK6409AJVzC5pVdAL4AqaMrQ6QtrrxIkOEa8c6qxOMKGiXTMncc_uwjtEES3HhVsrJuZkQdDW0zCMKIoKXj8UGkD6PskJdP3b28aHAlogGcoZkL5m80sXvfhQ",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "consumer"
}
Izsniegtais drošības talons atbilst RFC 7519 standartam un drošības talona satura pārlūkošanai ērti izmantot: https://jwt.io/
Postman piemērs drošības talona izsaukumam un datu izguves izsaukumiem pieejams: https://api.postman.com/collections/9631194-e7289644-5aa8-4639-8d4f-80c8591f2a49?access_key=PMAT-01GPE6A92NR3T5PNH5MTB9KMWD
Lai Postman programmā ielādētu kolekciju, jāizvēlas darbība “File” -> “Import” un jāiekopē augstākminētajā adresē pieejamais teksts. Lai varētu izpildīt drošības talona pieprasīšanas piemēru, Postman programmā ir jāpievieno un jāaktivizē mainīgo vide (environment). Instrukcija, kā izveidot un pārvaldīt mainīgo vides pieejama Postman ražotāja mājas lapā: https://learning.postman.com/docs/sending-requests/variables/managing-environments
¶ Atļauju noskaidrošana
Lai izgūtu datus, pieprasījumā ir jānorāda VIRSIS izsniegtās atļaujas numurs. Datu patērētājam pieejamās atļaujas var izgūt arī no DAGR. Ar katru datu kopu var būt saistīta viena vai vairākas aktīvas datu piekļuves atļaujas. DAGR atļauju sarakstu regulāri aktualizē no VIRSIS.
Datu piekļuves atļaujas apskatāmas DAGR pašapkalpošanās portāla sadaļā “Patērēšana” -> “VIRSIS atļaujas”.
Alternatīvi, atļauju sarakstu var izgūt arī ar metodi: https://test.dagr.gov.lv/current_user_permissions
Metodes izsaukuma piemērs:
curl --location --request GET 'https://test.dagr.gov.lv/current_user_permissions' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}'
Atbildes piemērs (servisa nosaukums un atļaujas numurs iekrāsoti spilgti sarkanā):
{
"service_name": "fpr_person",
"permission_number": "32423536",
"purpose_of_use": "testēšanai, pilnas tiesības uz personas datiem",
"use_count": 0,
"use_count_quota": 0,
"valid_from": null,
"valid_to": null,
"access_control_tree": {
"name": "fpr_person",
"read_access": "full"
}
},
{
"service_name": "fpr_person",
"permission_number": "23532235",
"purpose_of_use": "testēšanai, daļējas tiesības uz personas datiem",
"use_count": 0,
"use_count_quota": 0,
"valid_from": null,
"valid_to": null,
"access_control_tree": {
"name": "fpr_person",
"read_access": "partial",
"properties": [
{
"name": "PersonCode",
"read_access": "full"
},
{
"name": "ActualPersonCode",
"read_access": "full"
},
{
"name": "PersonsCode",
"read_access": "none"
},
{
"name": "PersonsName",
"read_access": "partial",
"properties": [
{
"name": "ReasonCode",
"read_access": "none"
},
{
"name": "ReasonName",
"read_access": "none"
},
{
"name": "ValidFrom",
"read_access": "none"
},
{
"name": "FirstName",
"read_access": "full"
},
{
"name": "LastName",
"read_access": "full"
},
{
"name": "OtherNames",
"read_access": "full"
}
]
},
{
"name": "PersonsBirth",
"read_access": "none"
},
{
"name": "PersonsDocument",
"read_access": "none"
},
{
"name": "PersonsResidence",
"read_access": "none"
},
{
"name": "PersonsDeath",
"read_access": "none"
}
]
}
}
]
¶ Datu objekta izgūšana pēc objekta identifikatora
Visām DAGR izplatāmajām datu kopām ir nodrošināta datu izgūšana pēc objekta identifikatora.
Katrai datu kopai ir savs datu izgūšanas serviss. Katram datu izgūšanas servisam ir savs noteikts objekta identifikators, pēc kā ieraksts tiek meklēts. Šis identifikators ir norādīts servisa aprakstā. Par objektu identifikatoriem tiek izmantotas faktiskas biznesa vērtības, piemēram – personas kods, reģistrācijas numurs, dokumenta numurs, adreses kods. Dažos gadījumos tiek izmantoti salikti kodi, kas sastāv no vairākām vērtībām, piemēram, uzņēmumu gada pārskatiem tiek izmantots gads un uzņēmuma reģistrācijas numurs.
Datu izgūšanas pēc objekta identifikatora servisi veidoti kā GET RESTful tipa pakalpes ar adresi šādā formā: https://test.dagr.gov.lv/{datu_kopa}/{objekta_identifikators}
Servisa galvenē “X-DAGR-Permission” ir jānorāda VIRSIS atļaujas numurs.
Servisa izsaukuma piemērs – Valsts adrešu reģistra adrese pēc adreses koda:
curl --location --request GET 'https://test.dagr.gov.lv/vzd_address/112022722' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}' \
--header 'X-DAGR-Permission: {VIRSIS atļaujas numurs}'
Atbilde būs pilni objekta dati JSON formātā.
Atbildes piemērs – adreses dati JSON formātā:
{
"ielCode": 100300132,
"novName": null,
"zipCode": "LV-1057",
"dzvName": "18",
"nltCode": 101848550,
"code": 112022722,
"cieName": null,
"pagAtvk": null,
"typ": 109,
"address": "Aglonas iela 31 - 18\nRīga",
"lksCoordLat": 307682.939,
"pilAtvk": "0001000",
"pagName": null,
"pagCode": null,
"adr_code": "112022722",
"dzvCode": 112022722,
"novAtvk": null,
"ielName": "Aglonas iela",
"novCode": null,
"nltName": "31",
"irAdrese": true,
"history": [
{
"adrese": "Aglonas iela 31, dz. 18, Rīga"
}
],
"lksCoordLong": 511254.388,
"pilCode": 100003003,
"cieCode": null,
"pilName": "Rīga"
}
Papildus servisa izsaukuma piemērs – UR juridiskā persona pēc reģistrācijas numura:
curl --location --request GET 'https://test.dagr.gov.lv/ur_legal_entity/40001016757' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}' \
--header 'X-DAGR-Permission: {VIRSIS atļaujas numurs}'
Atbilde būs pilni objekta dati JSON formātā.
¶ Datu izmaiņu izgūšana un pilnas datu kopas pārlasīšana
Visām DAGR izplatāmajām datu kopām ir nodrošināta iespēja izgūt datu izmaiņas.
Izmaiņu izgūšanas servisi veidoti kā GET RESTful tipa pakalpes ar adresi šādā formā: https://test.dagr.gov.lv/{datu_kopa}_changes
Servisa galvenē “X-DAGR-Permission” ir jānorāda VIRSIS atļaujas numurs.
Šiem servisiem ir trīs opcionāli parametri:
- offset – izmaiņu ieraksta kārtas numurs, no kura sākt izmaiņu atlasi. Var izmantot arī negatīvus skaitļus, tādā gadījumā serviss atgriezīs norādītā skaita pēdējos ierakstus. Piemēram, norādot -2, tiks atgriezti divi pēdējie ieraksti;
- timestamp – datums un laiks, no kura sākt izmaiņu atlasi;
- limit – atbildē atgriežamo ierakstu skaits. Noklusētā vērtība ir 100.
Ja netiek norādīts ne offset, ne timestamp parametrs, tad serviss atgriezīs vienu pēdējo izmaiņu ierakstu.
Izmaiņu servisa atbilde satur izmaiņu ierakstus JSON formātā, kur katram ierakstam ir šāda struktūra:
{
"offset": izmaiņu_kārtas_numurs,
"key": "ieraksta_identifikators",
"timestamp": "izmaiņu_pievienošanas_datums_un_laiks",
"value": { ieraksta_dati_kā_JSON_objekts
},
}
BŪTISKI: Datu kopas izmaiņu rinda satur tikai informāciju par pēdējo reizi, kad konkrētais ieraksts ir mainīts. Līdz ar to, izmaiņu servisu var izmantot visu datu kopas ierakstu atklāšanai un aktuālo izmaiņu monitoringam, bet to nevar izmantot vēstures datu atlasei. Gadījumos, kur datu kopa satur vēsturisku izmaiņu datus, tās ir iekļautas ierakstu datu struktūrā. Kā blakus efekts, izmaiņu kārtas numuri var izkrist, bet, izgūstot izmaiņu datus, tie vienmēr tiks atgriezti augošā secībā.
Datu izmaiņu izgūšanas pielietojumi:
- Ierakstu atklāšana. Lai atklātu visus datu kopas datu ierakstus, ir vispirms jāizsauc izmaiņu serviss bez offset vai timestamp parametriem. Tad jānolasa atbilde un jāpiefiksē offset vērtība pēdējam saņemtajam izmaiņu ierakstam. Tālāk jāveido nākamais pieprasījums, offset parametrā norādot piefiksēto pēdējo nolasīto izmaiņu kārtas numuru. Šādā veidā iterējot cauri visiem izmaiņu ierakstiem, līdz tiek saņemta tukša atbilde, var atklāt visus datu kopas ierakstus.
- Izmaiņu monitorings. Lai sekotu aktīvajām izmaiņām, var izmantot izmaiņu offset vai timestamp vērtības. Sistēmā, kas monitorē datu kopu, ir jāizveido process, kas ar noteiktu regularitāti pieprasa datus atbilstošajam DAGR izmaiņu servisam. Pēc datu nolasīšanas sistēmā, kas monitorē datu kopu, ir jāpiefiksē pēdējo nolasīto izmaiņu offset vai timestamp, lai pie nākamās datu nolasīšanas reizes tiktu saņemtas tikai jaunākās izmaiņas.
Izmaiņu servisa izsaukuma piemērs:
curl --location 'https://test.dagr.gov.lv/ur_legal_entity_changes?offset=0&limit=100' \
--header 'Authorization: Bearer {autentifikācijas ietvaros saņemtais drošības talons}' \
--header 'X-DAGR-Permission: {VIRSIS atļaujas numurs}'
Izmaiņu servisa atbildes piemērs:
[{
"key": "40900000031",
"offset": 0,
"timestamp": "2023-03-20T09:53:03.031",
"value": {
"address": {
"addressComplete": "\"Striķu skola\", Zvārdes pag., Saldus nov., LV-3883",
"addressRegisterCode": 106245206,
"county": "Saldus nov.",
"houseName": "Striķu skola",
"parish": "Zvārdes pag.",
"postalCode": "LV-3883"
},
"cleanedShortName": "STRIKU SAKUMSKOLA",
"isAnnulled": false,
"lastModifiedAt": "2022-03-24T09:14:53.615Z",
"links": {
"self": "/legal-entity/40900000031"
},
"liquidations": [],
"name": "Striķu sākumskola",
"officers": [
{
"appointedOn": "2001-07-05",
"id": 100010293,
"isAnnulled": false,
"lastModifiedAt": "2019-10-31T14:12:00.114Z",
"naturalPerson": {
"forename": "Daina",
"latvianIdentityNumber": "071063-12857",
"surname": "Zandberga"
},
"position": "GENERAL_MANAGER",
"positionDetails": "Iestādes direktore",
"registeredOn": "2019-10-31"
}
],
"publicAuthorityDetails": {
"contactDetails": {
"email": "striku.sakumskola@saldus.lv",
"phone": "+37163846132",
"website": "http://strikuskola.saldus.lv/"
},
"delegatedEntities": [],
"establishingAct": {
"date": "2016-01-28",
"legislatorName": "Saldus novada dome",
"legislatorNumber": "90009114646",
"number": "1.7.",
"title": "Saldus novada domes lēmums",
"type": "DECISION"
},
"registrationDetails": {
"authorityType": "INSTITUTION_OF_INDIRECT_ADMINISTRATION",
"establishedOn": "2016-01-28",
"higherAuthorityCurrentName": "Saldus novada pašvaldība",
"higherAuthorityNumber": "90009114646",
"isIndependentTaxpayer": false,
"isInstitutionOfHigherEducation": false,
"subordinationType": "CONTROL",
"taxpayerUnitNumber": "90009189123"
},
"schoolBranches": []
},
"register": "PUBLIC_PERSONS_INSTITUTIONS",
"registeredOn": "2018-03-08",
"registrationNumber": "40900000031",
"registrationNumberAssignedOn": "2018-03-08",
"reorganizations": [],
"status": "REGISTERED",
"type": "PUBLIC_BODY"
}
}
]
¶ Datu izmaiņu monitorings (pilnveidošanā)
Datu izmaiņu monitorings ļauj sekot līdzi izmaiņām datos datu patērētāja noteiktiem datu kopas ierakstiem.
Lai uzsāktu datu izmaiņu monitoringu, ir jādefinē izmaiņu monitoringa kopa jeb jānosaka, kura datu kopa un kādas VIRSIS atļaujas ietvaros tiks monitorēta. Kad izmaiņu monitoringa kopa ir definēta, tai jāpievieno saraksts ar identifikatoriem ierakstiem, kuri tiks monitorēti. Identifikatoru saraksta izmēram nav ierobežojumu.
Tālāk datu patērētājam ir iespēja atlasīt izmaiņu datus, kuros parādīsies informācija par tiem datu kopas ierakstiem, kam dati mainījušies kopš brīža, kad ieraksta identifikators tika pievienots monitoringa kopai. Gadījumā, ja ieraksta identifikatoru pēc tam no izmaiņu monitoringa kopas noņem, tad dati par ieraksta izmaiņām pieejami tikai līdz brīdim, kad šis identifikators tika no datu izmaiņu kopas noņemts.
¶ Izmaiņu monitoringa kopas definēšana
Izmaiņu monitoringa kopu iespējams definēt DAGR pašapkalpošanās portālā.
Vispirms, automātiskās uzmeklēšanas logā ir jāizvēlas datu patērētājs, kura vārdā lietotājs darbojas, no datu patērētājiem, kuru pieteikumos lietotājs norādīts kā kontaktpersona.
Tālāk parādās saraksts ar visām definētajām izmaiņu monitoringa kopām, kur par katru izmaiņu monitoringa kopu parādās izmaiņu monitoringa kopas nosaukums, datu kopas nosaukums un VIRSIS atļaujas numurs.
No saraksta iespējams atvērt apskatei eksistējošu izmaiņu monitoringa kopu vai definēt jaunu izmaiņu monitoringa kopu. Definējot jaunu izmaiņu monitoringa kopu, ir jānorāda izmaiņu monitoringa kopas nosaukums, tad jāizvēlas monitorējamā datu kopa no datu kopu saraksta un, visbeidzot, jāizvēlas VIRSIS atļaujas no datu patērējām esošajām atļaujām uz izvēlēto datu kopu.
¶ Monitorējamo ierakstu pārvaldība
Kad izmaiņu monitoringa kopa ir definēta, tad tai var pievienot, pārbaudīt, dzēst monitorējamo ierakstu identifikatorus. Identifikatoriem ir jābūt tieši tādiem, kādi tie tiek izmantoti monitorējamā datu kopā.
Darbības ar monitorējamo ierakstu identifikatoriem var izdarīt gan DAGR pašapkalpošanās portālā, gan izmantojot DAGR REST API. DAGR pašapkalpošanās portālā tas ir izdarāms izmaiņu monitoringa kopas kartiņā. Ņemot vērā, ka monitorējamo identifikatoru var būt ļoti daudz, kartiņā tiek attēloti tikai pēdējie 20. Kartiņā var ievadīt monitorējamā ieraksta identifikatoru un, izmantojot spiedpogas, to var pievienot, dzēst vai pārbaudīt tā esamību izmaiņu monitoringa kopā.
Pēc noklusējuma, monitorēt var tikai tādus ierakstus, kas ir pamata datu kopā. Piemēram, fizisko personu reģistram varētu monitorēt tikai tādas personas, kas faktiski ir šajā reģistrā. Taču datu kopām konfigurācijā var norādīt, ka monitorējami ir arī ieraksti, kas vēl nav pamata datu kopā.
Izmaiņu monitoringa automatizācijas vajadzībām, visas ar izmaiņu monitoringa kopām veicamās darbības ir pieejamas arī DAGR REST API servisu formā. Servisu pilns apraksts pieejams: https://dev.dagr.gov.lv/api-docs/portal
Servisus var izsaukt, izmantojot datu patērētāja drošības talonu.
Izmaiņu monitoringa vajadzībām pieejami šādi DAGR REST API servisi:
GET /monitoring_setIzgūst sarakstu ar datu patērētāja izmaiņu monitoringa kopāmPUT /monitor/{monitoring_set_name}/{registration_number}/{dataset}/{key}Pievieno jaunu identifikatoru izmaiņu monitoringa kopai. Viens un tas pats identifikators var tikt pievienots vairākas reizes. DAGR darbību tas negatīvi neietekmē, bet pašam datu patērētājam tad zūd iespēja noteikt pirmreizējo identifikatora pievienošanas datumu un laiku.DELETE /monitor/{monitoring_set_name}/{registration_number}/{dataset}/{key}Dzēs izmaiņu monitoringa kopai pievienotu identifikatoruGET /monitoring_is_on/{monitoring_set_name}/{registration_number}/{dataset}/{key}Pārbauda, vai identifikators tiek monitorētsGET /monitored_keys_changes/{monitoring_set_name}/{registration_number}/{dataset}Ļauj izgūt sarakstu ar visiem monitorējamajiem identifikatoriem. Piebilde, identifikatoru saraksts tiek glabāts rindas formā un vienādu identifikatoru gadījumā aktuāla ir saraksta pēdējā vērtība. Neaktuālās identifikatoru vērtības pēc laika no rindas tiek dzēstas.
Augstākminēto servisu kontekstā {registration_number} ir datu patērētāja reģistrācijas numurs, {dataset} ir datu kopas nosaukums un {monitoring_set_name} ir izmaiņu monitoringa kopas nosaukums.
¶ Izmaiņu monitoringa kopas nolasīšana
Izmaiņu monitoringa kopas dati ir nolasāmi tāpat kā izmaiņu dati (Datu izmaiņu izgūšana) ar divām atšķirībām:
- Izsaukumam jāpievieno parametrs “monitoring_set”, kurā tiek norādīts monitoringa kopas nosaukums;
- Izsaukuma galvenē “'X-DAGR-Permission” jānorāda tā pati atļauja, kas izmantota monitoringa kopas definēšanai.
Vispārīgā formā izmaiņu monitoringa dati nolasāmi, izsaucot šādu servisu:
https://{dagr_vides_adrese}/{datu_kopas_nosaukums}_changes/?monitoring_set={izmaiņu_monitoringa_kopas_nosaukums}
Piebilde: PMLP datu kopas fpr_person gadījumā ir atkāpe no formas {datu_kopas_nosaukums}_changes. Šajā gadījumā "fpr_person_changes" vietā jānorāda "fpr_person_all_changes".
Izsaukuma piemērs:
curl --location 'https://dev.dagr.gov.lv/vbtai_orphan_certificate_changes/?offset=0&limit=100&monitoring_set=VBTAI_demo_1' \
--header 'X-DAGR-Permission: 40003562863/vbtai' \
--header 'Authorization: ••••••'
Šim izsaukumam ir trīs opcionāli parametri:
- offset – izmaiņu ieraksta kārtas numurs, no kura sākt izmaiņu atlasi. Var izmantot arī negatīvus skaitļus, tādā gadījumā serviss atgriezīs norādītā skaita pēdējos ierakstus. Piemēram, norādot -2, tiks atgriezti divi pēdējie ieraksti;
- timestamp – datums un laiks, no kura sākt izmaiņu atlasi;
- limit – atbildē atgriežamo ierakstu skaits. Noklusētā vērtība ir 100.
Piebilde par sekošanu līdzi izmaiņu datiem: DAGR neatzīmē, kuri izmaiņu monitoringa dati jau ir nolasīti. Sekot līdzi izmaiņu nolasīšanas stāvoklim ir datu patērētāja uzdevums. Tas ir viegli izdarāms, izmantojot parametru offset vai timestamp. Ja datu patērētājam savā informācijas sistēmā ir process, kas ar noteiktu regularitāti pieprasa izmaiņu monitoringa datus, tad pēc datu nolasīšanas ir jāsaglabā pēdējā nolasītā ieraksta timestamp vai offset vērtība. Šo saglabāto vērtību nākošajā procesa izpildes ciklā jāpadod izmaiņu monitoringa datu izgūšanas servisam kā ieejas parametru un tas garantēs, ka nolasītas tiek tikai jaunpienākušās izmaiņas.
Piebilde par datu dzēšanu: DAGR izmaiņu monitoringa kopā katram ierakstam ilglaicīgi uzglabā tikai pēdējās izmaiņas.