DAGR ir izmantojams ne tikai strukturētu datu, bet arī failu izplatīšanai.
Failu izplatīšanas gadījumā datu kopas ieraksta strukturētie dati uzskatāmi par faila meta datiem, savukārt faili par ieraksta pielikumiem.
Šajā lapā aprakstīti ar failu izplatīšanu un saņemšanu saistītie jautājumi.
Lai izplatītu failus datu kopas datu struktūrā ir jāparedz faila tipa datu lauks un jārealizē failu augšupielāde vai nu ar DAGR REST API vai izmantojot datu devēja savienotāju.
Datu kopas datu struktūras definēšana vispārīgā formā ir aprakstīta datu izplatīšanas wiki sadaļā. Lai izplatītu failus datu kopas datu struktūras definīcija ir jāpapildina ar datu lauku, kuram uzstādīts lauka tips filename.
Ja par piemēra pamatu ņemsism datu nodošanas ar JSON sadaļā aprakstīto datu kopas datu struktūru un tai pievienosim jaunu datu lauku Attachment, kas norādīs uz faila atrašanās vietu DAGR, tad DAGR portālā pievienojamā datu struktūras definīcija izskatīsies šādi:
name: bss_health_institutions
key: Code
data_description: Ārstniecības iestādes, labās prakses piemērs (ar faila pielikumu)
fields:
- Code : Ārstniecības iestādes kods
- Title : Iestādes nosaukums
- Address : Adrese
- Phone : Telefona numurs
- Name : Iestādes vadītāja/kontaktpersonas vārds
- Surname : Iestādes vadītāja/kontaktpersonas uzvārds
- Registered : Reģistrācijas datums Ārstniecības iestāžu reģistrā
- Profile : Iestādes darbības profils
- Subordination : Pakļautības veids
- Type : Uzņēmējdarbības veids
- Attachment filename : Fails
- Branches * :
comments: Filiāļu saraksts
fields:
- Address
Ja datu nodošana uz DAGR tiek organizēta izmantojot DAGR REST API, tad arī failu augšupielāde veicama izmantojot DAGR REST API.
Šajā gadījumā uz DAGR nododot strukturētos ierakstu datus ar servisa PUT {dagr_adrese}/update/{datu_kopas_nosaukums} palīdzību filename tipa datu laukā ir jāieraksta faila nosaukums kā string tipa vērtība.
Pēc tam izmantojot servisu PUT {dagr_adrese}/file/{namespace}/{path_and_filename} ir jāaugšupielādē pats fails kā {namespace} norādot datu kopas nosaukumu, savukārt kā {path_and_filename} norādot ieraksta atslēgu un faila nosaukumu atdalītus ar slīpsvītru - šādā formā: {key}/{filename}. Piebilde: Ja datu kopai piekļuves tiesības netiek kontrolētas ierakstu līmenī (VIRSIS atļaujas nesatur filtrus), tad {path_and_filename} var arī saturēt tikai faila nosakumu bez ieraksta atslēgas.
Šeit ir piemērs kā izskatās faila augšupielādes piemērs datu kopai ar nosaukumu "bss_person_education", ierakstam ar atslēgu "300184-10702" un failam ar nosaukumu "diploms_2002.pdf":
curl -X 'PUT' \
'https://test.dagr.gov.lv/file/bss_person_education/300184-10702%2Fdiploms_2002.pdf' \
-H 'accept: text/plain' \
-H 'Content-Type: application/octet-stream' \
-H 'Authorization: Bearer {JWT drošības talona saturs}' \
--data-binary '@diploms_2002.pdf'
Izmēģinājumu vidē (sanbdox): Failu augšupielādes serviss strukturēts šādi PUT {dagr_adrese}/sandbox/{datu_devēja_reg_numurs}/file/{namespace}/{path_and_filename}.
BŪTISKI: DAGR neuztur integritāti starp meta datiem un pievienotajiem failiem - šī rūpe paliek datu devēju ziņā. Tamdēļ, ja saistītais ieraksts tiek dzēsts, tad jādzēš arī fails izmantojot metodi DELETE /file/{namespace}/{path_and_filename}. Arī gadījumos, kur mainās ierakstam pievienotais fails, ne tikai jāpievieno jaunais fails, bet ar DELETE metodi jādzēš vecais.
Failu augšupielādi var automatizēt ar datu devēja savienotāju. Šajā gadījumā ja datu kartējuma failā (connector.yaml) lauka tipu uzstāda filename, tad lauka vērtība tiek uzskatīta par norādi uz failu mērķa sistēmā. Tā var sastāvēt no neobligātas relatīvās takas un faila nosaukuma. Lai nokonfigurētu faila atrašanās vietu avota sistēmā, savienotāja struktūras definīcijā pie lauka papildus jānorāda pazīme file-location. Tās vērtībai jābūt faila URI šablonam. Šablons var iekļaut atsauces uz laukiem no tekošās struktūras, kā arī no augstāk esošām struktūrām. Piemēram:
name: fh_test
table:
key: id
fields:
- id
- name
- surname
- address * :
table:
fields:
- city
- street
- details filename:
file-location: file:///./src/test/resources/ds-tests/file-handler/files/{{^.name}}/{{details}}
Atsauces uz lauku vērtībām šablonā ir jāiekļauj dubultajās figūriekavās {{...}}. Lai atsauktos uz tekošās struktūras vērtību, dubultajās figūriekavās ir jānorāda tekošās struktūras lauka nosaukums, piemēram, {{details}}. Lai atsauktos uz vērtībām no augstākesošas struktūras, pirms lauka nosaukuma ir jāliek jumtiņš un punkts. Piemēram, {{^.name}}. Ja jāatsaucas uz lauka vērtību no vēl augstākas struktūras, tad pirms lauka nosaukuma jāliek divi jumtiņi un punkts, u.t.t. Piemēram, {{^^.grandparent}}.
Bez tam, lai aizsargātu sensitīvus datus, ir iespēja logfailos lauka vērtības vietā iekļaut tās hash. Tad aiz lauka atsauces ir jāpievieno |hash Piemēram, {{^.personas_kods|hash}}
Savienotājs tipiski sūta ierakstu uz DAGR tikai tad, ja kaut kas ierakstā ir mainījies. Failu saturs sinhronizācijas laikā salīdzināts netiek. Tāpēc, ja ir mainījies failu saturs, jāmaina ieraksta vērtība. Ja ir paredzams, ka faila saturs var mainīties, ir ieteicams konstruēt attiecīgā faila nosaukumu vai taku, iekļaujot tajā, piemēram:
2025-03-31_1559/fails.pdffails-v1.pdf699c1bd828/fails.pdfTiek atbalstītas šādas URI un pseido-uri shēmas:
Papildus iespējas un īpatnības konkrētām shēmām:
ContentType tiek atvasināts no faila paplašinājuma.sql:select data from clob_test where id = {{id}}. Ja vaicājums atgriež vismaz 2 kolonas, un otrā kolona ir teksts, tad otrās kolonas vērtība tiek uzskatīta par faila ContentType. Citādi ContentType tiek piešķirts automātiski, atkarībā no faila nosaukuma un/vai kolonas datu tipa. Sql shēmas pieprasījums tiek nevis konkatenēts no lauku vērtībām, bet gan lauku vērtības tiek padotas kā pieprasījuma parametri.
Lai lejupielādētu failu vispirms ir jāizgūst datu kopas ieraksta strukturētos datus kā tas aprakstīts sadaļā par datu izgūšanu pēc ieraksta ID vai sadaļā par izmaiņu atlasi. Pieņemsim, ka ieraksts satur šādus datu laukus:
[
{
"key": "10060302",
"offset": 4,
"timestamp": "2025-04-28T12:32:53.152Z",
"value": {
"Code": "10060302",
"Title": "Testa dati",
"Attachment": "busstops.csv"
}
}
]
Tālāk ar servisa GET /file/{namespace}/{path_and_filename} palīdzību var izgūt failu. Kā namespace jānorāda datu kopas nosaukums, savukārt kā {path_and_filename} jānorāda ieraksta atslēgu (šajā gadījumā "10060302") un faila nosaukumu (šajā gadījumā "busstops.csv") atdalītus ar slīpsvītru - šajā gadījumā 10060302%2Fbusstops.csv, kur %2F ir URL enkodēta slīpsvītra "/". Tāpat kā pie strukturēto datu izgūšanas galvenē Bearer jānorāda izgūtais datu saņēmēja drošības talons un galvenē 'X-DAGR-Permission' jānorāda VIRSIS atļaujas numurs.
Faila izgūšanas piemērs:
curl -X 'GET' \
'https://test.dagr.gov.lv/file/piemera_datu_kopa/10060302%2Fbusstops.csv' \
-H 'Authorization: Bearer {JWT drošības talona saturs}' \
-H 'X-DAGR-Permission: {VIRSIS atļaujas numurs} \
-H 'accept: application/json'