Agentas

Konfigūracija

Čia aprašyti Spinta nustatymai, kuriuos galima nurodyti per komandinę eilutę, per environment kintamuosius arba naudojant konfigūracinį failą.

Įvykių registravimas

log_level: Nustato įvykių registravimo žurnalo lygį standartinės išvesties (angl. stdout) žinutėms. Numatytoji reikšmė - WARNING. Galimos reikšmės: NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL.
file_log_level: Nustato įvykių registravimo žurnalo lygį žinutėms įrašomoms į failą. Numatytoji reikšmė - DEBUG. Galimos reikšmės: NOTSET, DEBUG, INFO, WARNING, ERROR, CRITICAL.
file_log_path: Nustato direktoriją, kurioje bus kuriami žurnalo failai. Numatytoji reikšmė - namų direktorijoje, .spinta_logs.

Saugumas

default_access_level: Nurodo numatytąjį duomenų prieigos lygį, jei jis nenurodytas elemento duomenų struktūros apraše. Numatytoji reikšmė – private. Reikšmių aprašas.
access: Nurodo žemiausią duomenų prieigos lygį, kurio duomenis grąžina agentas. Pvz., jei konfigūracijoje nurodytas access lygis public, bandant gauti duomenis, kurių access lygis yra žemesnis (pvz., protected arba private), grąžinama 404 ModelNotFound klaida. Numatytoji reikšmė – open. Reikšmių aprašas.

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

Agentų sąsajos registracija duomenų Kataloge

Registracija vykdoma organizacijos, kuriai priklauso naudotojas, puslapyje. Norėdami tai atlikti:

Prisijunkite prie duomenų Katalogo.
Viršutiniame dešiniajame kampe užveskite pelę ant savo naudotojo vardo.

pav. Navigacijos juosta – vartotojo skirtukas
Sąraše pasirinkite „Mano organizacijos duomenų ištekliai“.

pav. Nuoroda į organizacijos duomenų išteklius
Atverkite skirtuką „Agentai“.

pav. Agentų skirtukas
Spauskite „Pridėti Agentą“.

pav. Agento pridėjimas
Užpildykite formos laukus ir spauskite „Sukurti“.
- Agento pildymo forma ir jos laukai

Naujai atsidariusiame lange, matysite sukurtą Agentą bei galėsite sukurti agento aplinkas. Agentas gali turėti iki trijų Aplinkų. Viena aplinka atitinka viena fizinį agentą įdiegtą organizacijos infrastruktūroje.

Agento aplinkos pridėjimas

Norėdami pridėti naują aplinką, spauskite mygtuką „Pridėti aplinką“.

pav. Aplinkos pridėjimas
Užpildykite formos laukus ir spauskite „Sukurti“.
- Agento aplinkos pildymo forma ir jos laukai
Atlikus registraciją, pateikiami prisijungimo duomenys. Galimos dvi prisijungimo konfigūracijos, jos priklauso nuo pasirinktos Agento rūšies.

Duomenų publikavimo paslaugos susiejimas su Agentu

Norėdami susieti Duomenų publikavimo paslaugą su agentu, paslaugos redagavimo formoje pasirinkite norimą Agentą.

pav. Agento pasirinkimas Duomenų publikavimo paslaugoje

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ą. Tikslui pasiekti 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

Sutampa su client_id.

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

Pradinis spinta sync komandos žingsnis - įsitikinti, kad agentas buvo konfigūruotas teisingai. Paleidus komandą agentas atlieka užklausą į Katalogą, užklausa yra užregistruojama ir agento detalioje peržiūroje atvaizduojamos užklausos detalės, fiksuojama aktuali, su agentu susijusi, informacija.

Šias užklausas galima peržiūrėti užėjus į savo organizacijos puslapio skirtuką „Agentai“ ir pasirinkus konkretų agentą, kurio prieiga buvo konfigūruota agente. Apačioje matomoje užklausų istorijoje.

Todėl rekomenduojama, atlikus spinta check ten užeiti ir įsitikinti, kad agentas buvo sėkmingai prijungtas prie Katalogo.

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

Viešųjų raktų sukėlimas ir konfigūravimas

Spinta automatiškai įkelia visus galimus viešuosius raktus JWT žetonų tikrinimui. Raktai parenkami iš šių šaltinių prioritetų tvarka:

Konfigūracijoje nustatyti raktai (token_validation_key) Jei token_validation_key yra nurodytas, visi jame esantys raktai bus naudojami. Galima nurodyti vieną raktą arba kelis raktus sąraše keys.
Vietinis raktas (<config_path>/keys/public.json) Jei konfigūracijoje nėra raktų, naudojamas raktas iš lokalaus failo public.json.
URL atsisiunčiami raktai (token_validation_keys_download_url) Jei nei konfigūracijoje, nei vietiniame faile nėra raktų, galima nurodyti OAuth serverio URL, iš kurio raktai bus atsisiųsti. Atsisiųsti raktai paprastai saugomi lokaliame faile (downloaded_public_keys_file) tolimesniam naudojimui.

Konfigūracijos parametrai

token_validation_key:  > # vienas raktas arba raktų sąrašas
  {
    "keys": [
      {
        "kid": "rotation-1",
        "kty": "RSA",
        "alg": "RS512",
        "use": "sig",
        "n": "oAXjeXtZxiEUI7EcG6uITGCuUHmMQxMdTuSkQMaijmX0R1xSN-sQOgrunTqzldGWYhn4CQXmE34TgoZs2l6pZKNEyzap5IstPAUTFfHamyLka-xBwVRpCJaM_ZY9dEhzn9NUB-mx1ud9_clhmlef0SRQ1E5N_oU9wA_Hgd6hdnRzzTDJzmueF_03fEEf27fd69qzPZerOO7E9ytHJm0RpTF-50MGDL9pJaomAry_m0cw66DRd8rwqE-MiSg1xo02YWYIbaNA13K7jO33lW3iqgLdmtiBvX7qoNhEXC5H_umLvd5hgETGVemFcdFgL0Xnj85uk3puiVMsYXqmzHNxdw",
        "e": "AQAB"
      },
      {
        "kty": "RSA",
        "n": "l9oSzRInpwJLwsFEs80JQlPyf0k-AqvOef2H-1JpNeaivltEzA_hSX6SSEAm7vciOVOuxBJ0iGr7s0_wY0fKEJ4aFiYHR46zpHT_o0iZxrLwIKJugqDEE96mEPK-o5gVRqs-QJXDmaHzAkVntQRMP6GzKHy5Q6ZZQJWwKg_eTSGnGph34T7PUfSNF50G7qflqmWBiVW7qaNFKbgmB_7be-WZ9mbMVwSMMQwo_aahJqI1ZndKXgYGoEabwgSuJOQrAQbvVOyOHTj0ku-FNo8kb9dVeqi0F1qCvs6SAhCzk7qT215xalWIpX8BI1ZFnCv--6VMqIKEgTtjaaDh3V25SQ",
        "e": "AQAB"
      }
    ]
  }
token_validation_keys_download_url: https://<auth-serverio-adresas> # URL, iš kurio galima atsisiųsti viešuosius raktus
downloaded_public_keys_file: "custom-well-knows.json"         # vietinis failas atsisiųstiems raktams saugoti. Jei nenurodyta - "downloaded-well-knows.json" bus naudojamas.

token_validation_keys_download_url negali būti naudojamas kartu su token_validation_key, nes abu atlieka tą pačią funkciją. Skirtumas tas, kad token_validation_keys_download_url yra dinamiškesnis ir palaiko raktų rotaciją.

Naujus raktus galima parsisiųsti su komanda:

spinta key download

Dėmesio

Jei naudojamas token_validation_keys_download_url ir reikalingas raktų rotavimas, papildomai reikia sukonfigūruoti CRON, kuris periodiškai vykdytų komandą spinta key download (priklausomai nuo naudojamo auth serverio raktų rotacijos dažnio).

Pavyzdys CRON konfigūracijos:

# Redaguokite crontab:
crontab -e

# Pridėkite šią eilutę:
0 3 * * 1 /usr/bin/env bash -c 'cd /path/to/spinta/project && spinta key download >> /var/log/auth.log 2>&1'

Šiame pavyzdyje raktai bus atnaujinami iš auth serverio kas savaitę pirmadienį 03:00 val. Sau tinkama periodiškumą galima nustatyti pagal https://crontab.guru/

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žklausos leidimai:

Leidimas	Atributai, kuriuos galima keisti	Klientai, kuriuos galima keisti
`auth_clients`	`client_name`, `secret`, `scopes`, `backends`	Visus klientus
`client_backends_update_self`	`backends`, `secret`	Tik savo klientą
Be leidimų	`secret`	Tik savo klientą

Užklausa su pilnais duomenimis:

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

client_name:: Kliento pavadinimas, išduodamas kliento registravimo autentifikacijos servise metu.
secret:: Naujas kliento slaptažodis.
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

Ši forma naudojama Agentui sukurti arba esamam Agentui redaguoti.

Naujo Agento kūrimą inicijuokite paspaudę [Pridėti Agentą] viršutiniame dešiniajame kampe.
Norėdami redaguoti jau sukurtą Agentą, sąraše spustelėkite [Redaguoti] šalia įrašo.

pav. Agento kūrimo / redagavimo forma

Formos laukai ir jų paaiškinimai

Pavadinimas: Vartotojui matomas Agento pavadinimas, naudojamas ir kodiniam pavadinimui generuoti.

Rūšis

Nurodo, kokia paslauga naudojama Agento veikimui:

Spinta – sugeneruojamos dvi konfigūracijos:
- credentials.cfg
- config.yml
Kita – suteikiamas prieigos raktas. Likusi dalis priklauso sprendimo tiekėjui.

Agento aplinkos kūrimo / redagavimo forma

Ši forma naudojama Agento aplinkai sukurti arba esamai Agento aplinkai redaguoti.

Naujos Agento aplinkos kūrimą inicijuokite paspaudę [Pridėti aplinką] dešinėje pusėje po agento informacija.
Norėdami redaguoti jau sukurtą aplinką, sąraše spustelėkite [Redaguoti] šalia įrašo.

pav. Agento aplinkos kūrimo / redagavimo forma

Formos laukai ir jų paaiškinimai

Aplinka

Nurodo, kurioje aplinkoje bus diegiamas Agentas. Galimos reikšmės:

Vystymo – Agentas bus diegiamas vystymo aplinkoje.
Testavimo – Agentas bus diegiamas testavimo aplinkoje.
Gamybinė – Agentas bus diegiamas gamybinėje aplinkoje.

Agento adresas

Nurodo Agento pasiekimą per URL arba IP adresą. Jei yra nurodytas vartų adresas, tada agento adresas yra vidinis adresas, kurį mato API vartai. Jei API vartai nenurodyti, tada yra nurodomas išorinis agento adresas.

Autorizacijos serverio adresas

Nurodo autorizacijos serverio adresą, kuris bus naudojamas metaduomenų sinchronizacijai arba duomenų apsikeitimui.

API vartų serverio adresas

Nurodo API vartų serverio adresą, kuris bus naudojamas metaduomenų sinchronizacijai arba duomenų apsikeitimui.

Atviri duomenys publikuojami Saugykloje

Pažymėjus šį lauką, leidžiama publikuoti atvirus duomenis per Agentą.

Atvirų duomenų publikavimo nuoroda

Nurodoma tik tada, kai pažymėtas ankstesnis laukas dėl duomenų publikavimo.

Agentas įjungtas

Nurodo, ar Agentas šiuo metu aktyvus.

Pastaba

Sukūrus Agento aplinką, pateikiamos reikalingos konfigūracijos ir slaptas prisijungimo raktas. Dėl saugumo šis raktas rodomas tik vieną kartą – būtinai jį išsaugokite.

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, į kurį buvo atlikta užklausa. Užvedus pėlytę galima pamatyti pilną adresą.
Rezultatas: Atliktos užklausos rezultatas ("Sėkminga" arba "Nesėkminga").
Informacija: Papildoma informacija susijusi su atlikta užklausa, pvz.: spinta versija, iš kurios buvo vykdyta užklausa. Informacija yra apkerpama, jei jos yra per daug, pilną informaciją galima peržiūrėti detalios peržiūros puslapyje.
Klaidos pranešimas: Jei atliekant užklausą įvyko klaida, matoma nuoroda į detalesnę užklausos informaciją.

pav. Agento užklausų istorija

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

Papildoma užklausos informacija

Jei užklausa atlikta sėkmingai, išsaugoma ir papildoma informacija susijusi su užklausa:

Sudiegtos spinta aplikacijos versija, iš kurios buvo atliekama užklausa.

pav. Užklausos informacija

Klaidos atliekant užklausą

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

pav. Užklausos klaida

Duomenų gavimas

Autorizacija

Duomenų gavimui autorizacija atliekama naudojant JWT žetono leidimus (angl. scopes). Agentas vykdo du tikrinimus:

(Nebūtinas) JWT leidimai tikrinami su Agente sinchronizuotų sutarčių leidimais.
JWT leidimai tikrinami su API prieigos taško reikalaujamais leidimais.

Leidimų tikrinimas su sutartimis

Šis tikrinimas nėra privalomas. Norint įjungti šį patikrinimą, konfigūracijoje reikia pakeisti check_contract_scopes nustatymą į True.

Įspėjimas

Šis tikrinimas netaikomas atviriems duomenims, kurių prieigos lygis yra open.

Šis tikrinimas yra vykdomas kiekvienos užklausos metu. Tai Agente leidžia užtikrinti, kad JWT žetonas yra išduotas tik su leidimais, kurie yra įrašyti į sutartis, sinchronizuotas su Agentu ir susietas su klientu. Jei JWT žetonas turės leidimų, kurie nėra įrašyti į sutartį - užklausos vykdyti nebus galima.

Pastaba

Sutarčių leidimai yra tikrinami tik su tais JWT žetono leidimais, kurie atitinka Agente aprašytas vardų erdves. Todėl tą patį JWT žetoną galima naudoti kreipiantis į Agentus, kurie aprašo skirtingas vardų erdves, bet naudoja tą pačią sutartį.

Klaidos ir jų paaiškinimai

NoScopesForNamespaces:: Klaida kyla, kai JWT žetonas neturi nė vieno leidimo, kuris atitinka bent vieną Agento vardų erdvę.
InvalidExtraScopes:: Klaida kyla, kai JWT žetonas turi daugiau leidimų, atitinkančių Agento vardų erdves, negu nurodyta Agente saugomose ir su šiuo klientu susietose sutartyse.

Leidimų tikrinimas su API prieigos taško teisėmis

Kiekvienas API prieigos taškas (angl. endpoint), reikalauja vieno ar kelių leidimų (netaikoma atviriems duomenims, kurių prieigos lygis yra open). Leidimai priklauso nuo modelio į kurį kreipiamasi, nuo duomenų rinkinio, kuriame aprašytas modelis, ir nuo atliekamo veiksmo.

Jei JWT žetonas turi bent vieną leidimą, kuris sutampa su API prieigos taško reikalaujamu leidimu arba yra platesnis - užklausą galima vykdyti.

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.

Papildoma informacija

SOAP adapteriai

Kai duomenų šaltinis reikalauja unikaliai formuojamų SOAP užklausų (pvz., užklausos parašas apskaičiuojamas iš kelių laukų reikšmių), Spinta leidžia prijungti papildomus Python modulius - SOAP adapterius.

Kaip tai veikia

Kai Spinta formuoja SOAP užklausą, vykdomi trys žingsniai:

Modulio įkėlimas - nurodyti .py failai įkeliami paleidimo metu. Iš kiekvieno modulio nuskaitomos dvi funkcijos: get_deferred_prepare_names() ir get_body_resolvers().
Atidėtieji laukai - DSA aprašo prepare stulpelyje galima nurodyti atidėtą ufunc (angl. user function) išraišką (pvz., rc_signature()). Tokie laukai neišskaičiuojami iš karto - jie laukia, kol užklausos turinys bus pilnai suformuotas.
Reikšmės apskaičiavimas - kai visi kiti laukai jau yra paruošti, kiekvienas atidėtas laukas išskaičiuojamas iškviečiant atitinkamą vertimo programos (angl. resolver) funkciją. Vertimo programa gauna SoapQueryBuilder aplinkos (angl. env) objektą su env.soap_request_body, env.context ir kt., ir grąžina galutinę reikšmę.

Adapterio konfigūracija

Adapterių veikimui reikia trijų elementų, kurie dažniausiai yra pilnai kontroliuojami informacinės sistemos administratoriaus:

Pakeitimų config.yml faile: pridedama nuoroda į adapterio kodą ir adapterio konfigūracijos parametrai.
DSA aprašo pakeitimų, kad formuojant užklausą būtų naudojamas adapterio 'ufunc'.
Adapterio modulio kodo failo, paruošto pagal adapterio modulio struktūrą ir reikalavimus.

Konfigūracinis failas - `config.yml`

soap_adapter_modules:
  - /absolute/path/to/my_adapter.py

Pastaba

Nurodykite absoliučius kelius (angl. absolute paths) - taip adapteris veiks nepriklausomai nuo to, iš kurios direktorijos paleidžiamas procesas. Jei failas nerastas, jis bus praleistas ir užfiksuotas žurnale.

Adapterio nustatymai rašomi greta kitų viršutinio lygio raktų. Pavyzdžiui, RC parašo adapteris tikisi:

rc_signature:
  private_key_path: /absolute/path/to/private.pem

Pastaba

Šių konfigūracijos nustatymų reikia tik adapteriams, kurie juos naudoja; jūsų adapteris gali naudoti kitus nustatymus ir validuoti juos validate_soap_adapter_config funkcijoje.

DSA aprašas

SOAP resurso parametrai susieja DSA aprašo savybes su SOAP užklausos turiniu. prepare stulpelis aprašo, kaip kiekvienam parametrui apskaičiuojama numatytoji reikšmė prieš vykdant užklausą.

Įprasti prepare (input(), cdata().input() ir pan.) išskaičiuojami iš karto, kai formuojamas užklausos turinys.
prepare, kviečiantis atidėtą ufunc (pavadinimas registruotas per get_deferred_prepare_names()), lieka kaip Expr iki adapterio vertimo programos vykdymo.

Pavyzdys

DSA apraše (tik šablonas; stulpelių pavadinimai gali skirtis pagal jūsų aprašą) tai gali atrodyti taip:

property  | source           | prepare
signature | input/Signature  | rc_signature()

Kad rc_signature būtų atpažintas kaip atidėtas, modulyje jis turi būti grąžinamas iš get_deferred_prepare_names().

Adapterio modulio struktūra

Sukurkite įprastą Python modulį (bet koks failo pavadinimas) su šiomis funkcijomis:

Funkcija	Privaloma	Paskirtis
`get_deferred_prepare_names()`	Taip	Grąžina sąrašą ufunc pavadinimų, kuriuos reikia atidėti.
`get_body_resolvers()`	Taip	Grąžina žodyną `{pavadinimas: funkcija}`, kur funkcija priima `env` (ir pasirinktinai `expr`).
`validate_soap_adapter_config(raw_config)`	Ne	Tikrina adapterio konfigūraciją paleidimo metu. Grąžina klaidą, jei konfigūracija neteisinga.

Pastaba

Jei modulyje aprašyta validate_soap_adapter_config funkcija, ji vykdoma iš karto po modulio įkėlimo - taip konfigūracijos klaidos pastebimos paleidimo metu, o ne vykdymo metu.

Nuorodos į realizacijos pavyzdžius:

spinta/adapters/rc/signature_adapter.py - RC brokerio parašo adapterio pavyzdys.
tests/adapters/test_soap_dsa_deferred_rc_signature.py - pilnas scenarijus su SoapQueryBuilder.build().

Agentas

Konfigūracija

Įvykių registravimas

Saugumas

Sinchronizacija

Pasiruošimas

Agento registracija Kataloge

Duomenų publikavimo paslaugos susiejimas su Agentu

Agento konfigūracija

Lokalaus/Agento DSA failo nustatymas

Agento prisijungimas prie Duomenų Šaltinio

Agento prisijungimas prie Duomenų Katalogo

Procesas

Sinchronizacija: Katalogas -> Agentas

Sinchronizacija: Duomenų Šaltinis -> Agentas

Sinchronizacija: Agentas -> Katalogas

Viešųjų raktų sukėlimas ir konfigūravimas

Konfigūracijos parametrai

Dėmesio

Kliento administravimas

Kliento atnaujinimas

Formos, jų laukai ir paaiškinimai

Agento kūrimo / redagavimo forma

Formos laukai ir jų paaiškinimai

Agento aplinkos kūrimo / redagavimo forma

Formos laukai ir jų paaiškinimai

Agentų sąrašo lentelė

Rodomi laukai ir jų reikšmės

Agento peržiūros forma

Paaiškinimai apie laukų reikšmes

Konfigūracija pagal Agento rūšį

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

Užklausos peržiūros forma

Paaiškinimai apie laukų reikšmes

Papildoma užklausos informacija

Klaidos atliekant užklausą

Duomenų gavimas

Autorizacija

Leidimų tikrinimas su sutartimis

Klaidos ir jų paaiškinimai

Leidimų tikrinimas su API prieigos taško teisėmis

Duomenų gavimas

Klaidos ir jų paaiškinimai

Papildoma informacija

SOAP adapteriai

Kaip tai veikia

Adapterio konfigūracija

Konfigūracinis failas - config.yml

DSA aprašas

Adapterio modulio struktūra

Konfigūracinis failas - `config.yml`