Agentas

Sinchronizacija

Sinchronizacija – tai procesas, kurio metu sulyginama tiek duomenų struktūra, tiek patys duomenys tarp duomenų šaltinio ir duomenų Kataloge saugomos informacijos.

Pasiruošimas

Prieš pradedant sinchronizaciją, reikia:

Užregistruoti Agentą Kataloge

Sukonfigūruoti Agentą

Agento registracija Kataloge

Agento registracija Kataloge aprašyta čia

Agento konfigūracija

Agentą reikia konfigūruoti, kad būtų galima pasiekti:

Duomenų Šaltinį

Duomenų Katalogą

Lokalaus/Agento DSA failo nustatymas

Norint vykdyti sinchronizaciją, Agentui reikia nurodyti vietą, kur bus saugomas DSA failas. Pagal šį failą, lyginant jį su duomenų šaltiniu ir katalogu (atskiri proceso etapai), bus atliekami duomenų atnaujinimai arba siunčiami pranešimai apie pasikeitusią duomenų struktūrą (į Katalogą).

Šio failo vietą failinėje sistemoje galima nustatyti config.yml faile.

Pastaba

Vietinio failo nustatymo config.yml konfigūracijoje pavyzdys:

manifest: default
manifests:
  default:
    type: csv
    path: /Users/john_doe/manifest.csv
    backend: default
    keymap: default
    mode: external

Pavyzdyje:

manifests.default.path — nurodoma vietinio failo vieta failinėje sistemoje, kur įdiegtas Agentas (Spinta).

Agento prisijungimas prie Duomenų Šaltinio

Norint prijungti agentą prie duomenų šaltinio, reikia papildomai sukonfigūruoti config.yml failą. Tam reikia nustatyti:

Duomenų šaltinio tipą

Duomenų šaltinio nuorodą (pvz.: duomenų bazės prisijungimo URL)

Pastaba

Failo config.yml pavyzdys konfigūruojant prisijungimą į PostgreSQL duomenų bazę:

backends:
  default:
    type: sql
    dsn: postgresql://django:django@localhost:9432/django

Pavyzdyje:

backends.default.type nurodomas duomenų šaltinio tipas.

backends.default.dsn nurodoma duomenų šaltinio nuoroda.

Agento prisijungimas prie Duomenų Katalogo

Ši konfigūracija sugeneruojama automatiškai ir vartotojui reikia tik ją perkelti į credentials.cfg failą.

Pastaba

Failo credentials.cfg pavyzdys:

[default]
server = https://example-server.com
resource_server = https://example-resource-server.com
organization = <kliento-organizacija>
organization_type = <kliento-organizacijos-tipas>
client_id = <kliento-identifikatorius>
client = <klientas>
secret = <kliento-paslaptis>
scopes =
    uapi:/datasets/gov/vssa/dcat/Dataset/:getall
    uapi:/datasets/gov/vssa/dcat/Dataset/:create
    uapi:/datasets/gov/vssa/dcat/Dsa/:getone
    uapi:/datasets/gov/vssa/dcat/Dsa/:create
    uapi:/datasets/gov/vssa/dcat/Dsa/:patch
    uapi:/datasets/gov/vssa/dcat/Distribution/:getall
    uapi:/datasets/gov/vssa/dcat/Distribution/:create
    uapi:/datasets/gov/vssa/dcat/Agreement/:patch

server

Autorizacijos serverio adresas (URL), kuris išduoda prieigos žetoną (angl. access token) ir valdo OAuth 2.0 klientus.

resource_server

Nurodomas duomenų Katalogo adresas (URL), su kuriuo vyks sinchronizacija.

organization

Organizacijos, kuriai priklauso klientas, pavadinimas.

organization_type

Organizacijos, kuriai priklauso klientas, tipas (Valstybinė įstaiga, Verslo organizacija, Nepelno ir nevalstybinė organizacija).

client_id

Nurodomas OAuth 2.0 kliento identifikatorius.

client

Nurodomas OAuth 2.0 kliento pavadinimas, automatiškai sukuriamas pagal Kataloge nurodytą pavadinimą ir naudojamas autorizacijos procese.

secret

Pagrindinis slaptasis raktas naudojamas OAuth 2.0 klientui. Naudojamas gauti prieigos žetoną iš autorizacijos serverio. Galioja neribotą laiką.

scopes

Prašomi leidimai, kurie yra siunčiami į autorizacijos serverį. Jei šie leidimai nesutampa su leidimais, suteiktais OAuth 2.0 klientui, prieigos žetonas neveiks ir pokyčių atlikti nepavyks. Todėl konfigūracijoje palikite tik būtinus leidimus. Papildomų ar nenumatytų leidimų įtraukti nereikėtų. Esant poreikiui, galite palikti tik dalį jų.

Procesas

Sinchronizacija yra procesas, kurio metu norima įsitikinti, kad duomenų struktūra tarp trijų skirtingų vietų, kuriose ji saugoma, yra nepakitusi.

Struktūra yra saugoma:

Duomenų šaltinyje (pvz.: Duomenų bazė)

Agente, lokaliame faile

Duomenų Kataloge (dažniausiu atveju — https://data.gov.lt/)

Procesas vykdomas trimis etapais. Išsamesnė informacija apie kiekvieną etapą pateikta atitinkamuose skyriuose:

Katalogas -> Agentas

Duomenų Šaltinis -> Agentas

Agentas -> Katalogas

Dėmesio

Norint pradėti sinchronizaciją, Agentui reikia įvykdyti komandą: spinta sync

Sinchronizacija: Katalogas -> Agentas

Šio etapo metu yra atsisiunčiami duomenų rinkiniai iš Katalogo, susieti su pasirinktu Agentu.

Šie duomenų rinkiniai apjungiami į vieną struktūros aprašą, ir pradedamas kiekvienos eilutės palyginimas tarp atsisiųsto failo iš Katalogo ir Agento vietinėje failinėje sistemoje esančio duomenų struktūros failo.

Pakeitimai atliekami pagal tokią atvejų matricą:

Atvejų apžvalga
Atvejo Nr.	Katalogas	Agentas	Veiksmas
1	Sutampa	Sutampa	Niekas neatliekama
2	Nesutampa	Nesutampa	Agento ŠDSA perrašomas iš Katalogo
3	Yra	Nėra	Agento ŠDSA papildomas Katalogo informacija
4	Nėra	Yra	Niekas neatliekama

Pavyzdys

Kataloge turint tokį duomenų struktūros aprašą:

id                                   | dataset | resource   | base | model   | property | type      | ref     | source                                                   | source.type | prepare | origin | count | level | status    | visibility | access | uri  | eli | title             | description
b67a8e27-106c-47a6-a85e-a355c8bd9761 | vssa    |            |      |         |          |           |         | https://example.com                                      |             |         |        |       |       | open      |            |        |      |     | VSSA              | vssa
e23139cb-3c6b-40fd-8fba-1d68e5701733 |         | geography  |      |         |          | dask/csv  |         | https://get.data.gov.lt/datasets/org/vssa/geography/:ns  |             |         |        |       | 4     |           |            |        |      |     | Geography         | geography
                                     |         |            |      |         |          |           |         |                                                          |             |         |        |       |       |           |            |        |      |     |                   |
25568d69-1456-485c-9fca-8124d41a5295 |         |            |      | Country |          |           |         |                                                          |             |         |        |       | 4     | completed | package    | open   |      |     | Country           | country
6faa42c1-7ad6-43be-a266-ccab35dd0bc9 |         |            |      |         |          | id        | integer | property_id                                              |             |         |        |       | 4     |           |            |        |      |     | Identifier        | identifier
407270ca-f9bd-4c81-8c64-108b24bfafbe |         |            |      |         |          | size      | integer | property_size                                            |             |         |        |       | 4     |           |            |        |      |     | Size              | size

O Agente turint tokį duomenų struktūros aprašą:

id                                   | dataset | resource   | base | model   | property | type      | ref     | source                                                   | source.type | prepare | origin | count | level | status    | visibility | access | uri  | eli | title             | description
b67a8e27-106c-47a6-a85e-a355c8bd9761 | lrs     |            |      |         |          |           |         | https://example.com                                      |             |         |        |       |       | open      |            |        |      |     | LRS               | lrs
e23139cb-3c6b-40fd-8fba-1d68e5701733 |         | law        |      |         |          | dask/csv  |         | https://get.data.gov.lt/datasets/org/vssa/geography/:ns  |             |         |        |       | 4     |           |            |        |      |     | Law               | example
                                     |         |            |      |         |          |           |         |                                                          |             |         |        |       |       |           |            |        |      |     |                   |
25568d69-1456-485c-9fca-8124d41a5295 |         |            |      | Person  |          |           |         |                                                          |             |         |        |       | 4     | completed | package    | open   |      |     | Person            | person
6faa42c1-7ad6-43be-a266-ccab35dd0bc9 |         |            |      |         |          | uuid      | string  | property_id                                              |             |         |        |       | 4     |           |            |        |      |     | Unique Identifier | unique identifier

Galutinis struktūros aprašo rezultatas (Agente) atrodys taip:

id                                   | dataset | resource   | base | model   | property | type      | ref     | source                                                   | source.type | prepare | origin | count | level | status    | visibility | access | uri  | eli | title             | description
b67a8e27-106c-47a6-a85e-a355c8bd9761 | vssa    |            |      |         |          |           |         | https://example.com                                      |             |         |        |       |       | open      |            |        |      |     | VSSA              | vssa
e23139cb-3c6b-40fd-8fba-1d68e5701733 |         | geography  |      |         |          | dask/csv  |         | https://get.data.gov.lt/datasets/org/vssa/geography/:ns  |             |         |        |       | 4     |           |            |        |      |     | Geography         | geography
                                     |         |            |      |         |          |           |         |                                                          |             |         |        |       |       |           |            |        |      |     |                   |
25568d69-1456-485c-9fca-8124d41a5295 |         |            |      | Country |          |           |         |                                                          |             |         |        |       | 4     | completed | package    | open   |      |     | Country           | country
6faa42c1-7ad6-43be-a266-ccab35dd0bc9 |         |            |      |         |          | id        | integer | property_id                                              |             |         |        |       | 4     |           |            |        |      |     | Identifier        | identifier
407270ca-f9bd-4c81-8c64-108b24bfafbe |         |            |      |         |          | size      | integer | property_size                                            |             |         |        |       | 4     |           |            |        |      |     | Size              | size

Sinchronizacija: Duomenų Šaltinis -> Agentas

Įspėjimas

Funkcionalumas vystomas

Sinchronizacija: Agentas -> Katalogas

Įspėjimas

Funkcionalumas vystomas

Kliento administravimas

Kliento administravimas yra OAuth kliento kūrimas, peržiūra, keitimas ir trynimas.

Kliento atnaujinimas

Kliento atnaujinimas atliekamas PATCH užklausa adresu spinta_url/auth/clients/{client_id}, siunčiant vieną ar kelis atributus, kuriuos norima pakeisti.

Užklausai reikalingas auth_clients leidimas (scope). Be jo, galima keisti tik kliento, su kuriuo atliekama užklausa, slaptažodį.

Užklausa su pilnais duomenimis:

{
    "client_name": "New Client Name",
    "scopes": [
        "spinta_getone",
    ],
    "backends": {
        "new_resource_name": {
            "new_key": "new_value"
        }
    }
}

client_name:: Kliento pavadinimas, išduodamas kliento registravimo autentifikacijos servise metu.
scopes:: Leidimai.
backends:: Atributas, kuriame saugoma papildomi autentifikacijos duomenys, kurie gali būti naudojami prisijungimui prie duomenų šaltinio. Autentifikacijos duomenys saugomi kiekvienam DSA resursui atskirai.

Užklausoje nenurodyti atributai nebus pakeisti. Sėkmingos užklausos atveju bus grąžinamas atsakymas:

{
    "client_id": "791cdc66-bed8-4c9f-9d92-0e49a061c3d0",
    "client_name": "New Client Name",
    "scopes": [
        "spinta_getone",
    ],
    "backends": {
        "new_resource_name": {
            "new_key": "new_value"
        }
    }
}

Formos, jų laukai ir paaiškinimai

Agento kūrimo / redagavimo forma

Agento kūsimo/redagavimo formos aprašymą rasite čia

Agentų sąrašo lentelė

Ši lentelė atvaizduoja visus registruotus Agentus ir jų pagrindinę informaciją.

pav. Agentų sąrašo lentelė

Rodomi laukai ir jų reikšmės

Būsena

Būsena apima du indikatoriai:

Spalvotas rutuliukas, žymintis paskutinės sinchronizacijos rezultatą:
- Žalia – sinchronizacija pavyko.
- Raudona – sinchronizacija nepavyko.
- Juoda – sinchronizacija dar nevykdyta.
Indikatorius, ar Agentas yra įjungtas.

Kodinis pavadinimas

Unikalus pavadinimas, generuojamas sistemoje organizacijos mastu.

Pavadinimas

Vartotojui matomas pavadinimas. Naudojamas kodiniam pavadinimui generuoti.

Aplinka

Nurodo, kurioje aplinkoje Agentas bus diegiamas.

Sukurtas

Agento sukūrimo data.

Užklausa

Paskutinės sinchronizacijos arba bandymo data.

Duomenų paslauga

Kiekvienam Agentui automatiškai sukuriama susijusi duomenų paslauga arba nurodyta kuriant/redaguojant Agentą.

Veiksmai

Prie kiekvieno Agento pateikiami šie veiksmai:

Žurnalas – detali Agento informacija.
Redaguoti – Agento redagavimo forma.
Pašalinti – Agento pašalinimas iš sistemos.

Agento peržiūros forma

Ši forma naudojama peržiūrėti sukurto Agento informaciją ir būseną.

pav. Agento peržiūros forma

Paaiškinimai apie laukų reikšmes

Sukurtas

Agento sukūrimo data.

Pavadinimas

Vartotojui matomas pavadinimas.

Duomenų paslauga

Duomenų paslauga, automatiškai sukuriama ir susiejama su Agentu arba nurodyta kuriant/redaguojant Agentą.

Kodinis pavadinimas

Unikalus identifikatorius, generuojamas sistemoje.

Aplinka

Aplinka, kurioje Agentas bus diegiamas.

Būsena

Nurodoma, ar Agentas įjungtas.

Rūšis

Naudojama implementacija:

Spinta – naudojama „Spintos“ sinchronizavimo logika.
Kita – nestandartinė implementacija, įgyvendinta sprendimo tiekėjo.

Agento adresas

Agento pasiekimas per URL arba IP adresą.

Paskutinės sinchronizacijos rezultatas

Žalia – sinchronizacija pavyko.

Raudona – sinchronizacija nepavyko.

Juoda – sinchronizacija dar nevykdyta.

Paskutinės sinchronizacijos data: Data ir laikas, kada paskutinė sinchronizacija įvyko.
Publikuojami atviri duomenys: Ar leidžiama publikuoti atvirus duomenis per šį Agentą.
Atvirų duomenų servisas: Nuoroda, kur atviri duomenys bus publikuojami. Numatytas adresas: https://get.data.gov.lt

Konfigūracija pagal Agento rūšį

Papildomai, priklausomai nuo pasirinktos rūšies, rodoma specifinė Agento konfigūracija:

Spinta
Rodoma dvi konfigūracijos dalys:
- Prisijungimui prie Katalogo.
  
  pav. Konfigūracija pasirinkus „Spinta“: Agentas -> Katalogas
- Prisijungimui prie duomenų šaltinio.
  
  pav. Konfigūracija pasirinkus „Spinta“: Agentas -> Duomenų Šaltinis
Kita

Rodoma tik prieigos rakto informacija. Likusi konfigūracija – sprendimo tiekėjo atsakomybė.

pav. Konfigūracija pasirinkus „Kita“

Užklausų vykdomų per Agentą lentelė

Dar žemiau galima rasti visų užklausų, kurios į Katalogą yra vykdomos per Agentą, lentelę. Lentelėje matoma:

Data ir laikas: Užklausos atlikimo data ir laikas. Data ir laikas taip pat yra nuoroda į detalesnę užklausos informaciją.
Tipas: Atliktos užklausos tipas ("GET", "POST", "PUT", "DELETE", "PATCH").
Adresas: Adresas, i kurį buvo atlikta užklausa.
Rezultatas: Atliktos užklausos rezultatas ("Sėkminga" arba "Nesėkminga").
Klaidos pranešimas: Jei atliekant užklausą įvyko klaida, matoma nuoroda į detalesnę užklausos informaciją.

pav. Užklausų istorijos lentelė

Užklausos peržiūros forma

Ši forma naudojama norint peržiūrėti detalią informaciją apie užklausą, atliktą per Agentą.

Paaiškinimai apie laukų reikšmes

Data ir laikas: Užklausos atlikimo data ir laikas.
Agentas: Agentas, per kurį buvo atlikta užklausa į katalogą.
Užklausos API adresas: Adresas, į kurį buvo atlikta užklausa.
HTTP metodas: HTTP metodas, kuris buvo naudojamas atliekant užklausą ("GET", "POST", "PUT", "DELETE", "PATCH").
Rezultatas: Atliktos užklausos rezultatas ("Sėkminga" arba "Nesėkminga").
Statusas (HTTP): Būsena kuri buvo pasiekta atliekant užklausą. Išsamiau paaiškina, kodėl rezultatas sėkmingas arba nesėkmingas.

pav. Užklausos peržiūros forma

Klaidos atliekant užklausą

Jei atliekant užklausą buvo susidurta su klaida, klaidą galima matyti žemiau.

pav. Užklausos klaida

Duomenų gavimas

Klaidos ir jų paaiškinimai

InvalidClientBackend:

Klaida kyla, kai turimas DSA aprašas su bent vienu resursu su creds(key) prepare funkcija, bet tarp kliento duomenų, backends atribute, nėra išsaugotas atributas su resurso pavadinimu. Būtent šiame kintamąjame creds(key) funkcija ieškos key reikšmės.

Norint pataisyti klaidą, prie kliento duomenų backends atributo reikia pridėti atributą su resurso pavadinimu. Skaityti Kliento atnaujinimas.

InvalidClientBackendCredentials:

Klaida kyla, kai turimas DSA aprašas su bent vienu resursu su creds(key) prepare funkcija, backends atribute yra išsaugotas atributas su resurso pavadinimu, bet atribute nėra išsaugota key reikšmė.

Norint pataisyti klaidą, prie kliento duomenų backends atribute esančio atributo resurso pavadinimu reikia pridėti trūkstamą key reikšmę. Skaityti Kliento atnaujinimas.