Duomenų įkėlimas į Saugyklą

[sirex]

Užduoties aprašymas yra pasenęs, žiūrėti komentarus.

Šiuo metu duomenų failai yra įkeliami į metaduomenų katalogą, kaip failai. Tačiau tai reikia pakeisti, kad failai būtų keliame ne į Katalogą, o tiesiai į Saugyklą.

Duomenų šaltinio formoje:

Reikia panaikinti failo įkėlimo lauką iš formos. Šis laukas persikelia į atskirą formą, kuri pasiekiama iš duomenų šaltinio puslapio, kuriame turi būti mygtukas „Įkelti duomenis“.

Paspaudus mygtuką „Įkelti duomenis“, atsidaro duomenų įkėlimo forma, kurioje pateikiama informacija, kaip galima duomenis pateikti naudojantis Saugyklos API arba alternatyviai, nedidelės apimties duomenų failus galima įkelti tiesiogiai, per formą. Duomenų įkėlimo forma turi rodyti tiesiai į get.data.gov.lt (adresas konfigūruojamas per settings.py). Formoje rodomi tokie laukai:

• Duomenų struktūra - select list su šio rinkinio modelių sąrašu. Lauko aprašyme reikia nurodyti, kad jei sąraše nėra reikiamo duomenų modeliu, tai jis turi būti sukurtas Struktūros dalyje (pateikiant nuorodą į Struktūra).
• Duomenų failas - file tipo laukas, su data pavadinimu (žiūrėti https://github.com/atviriduomenys/spinta/issues/475).

Pateikiant formos duomenis turėtų atsidaryti naujas langas, kuriame bus rodomos duomenų įkėlimo klaidos, jei tokių bus.

Dėl anksčiau įkeltų duomenų failo į katalogą, paliekam juos taip, kaip yra, t.y. formuojam nuorodą į katalogą, tačiau nebeleidžiame įkelti naujų duomenų į katalogą, leidžiame duomenis įkelti tik į Saugyklą. O įkėlus duomenis į Saugyklą, pateikiame nuorodą į Saugyklą, kur buvo įkelti duomenys.

Epic

• https://github.com/atviriduomenys/katalogas/issues/52

Priklauso nuo

• https://github.com/atviriduomenys/katalogas/issues/342
• https://github.com/atviriduomenys/katalogas/issues/261
• https://github.com/atviriduomenys/spinta/issues/475

[sirex]

Panašu, kad tiesioginis įkėlimas per formą į Saugyklą neveiks ir failus vis tiek reikės pirmiausia įkelti į katalgo tmp katalogą, o tada katalogo serverio pusėje daryti API užklausą į saugyklą ir taip įkelti duomenis į saugyklą.

[sirex]

Kad supaprastinti šią užduotį, siūlau iš naudotojo sąsajos nieko nekeisti ir palikti dabartinį failų įkėlimą, kaip dabar įgyvendinta. Ir padaryti skriptą, kuris sukeltu į Katalogą įkeltus ir išorėje publikuojamus duomenis į Saugyklą, naudojantis spinta push komandinės eilutės komanda.

Iš naudotojo sąsajos, Duomenų šaltinio formoje reikia checkbox „Publikuoti duomenis Saugykloje“, kurį pažymėjus, skriptas sukeltų duomenis į Saugyklą. Jei duomenų šaltinio nuoroda rodo į Saugyklą, tada toks checkbox turi būti pažymėtas ir neaktyvus.

Iš naudotojo pusės daugiau niekas nesikeičia ir toliau aprašymas, kaip turėtu būti įgyvendintas duomenų publikavimas į Saugyklą naudojant spinta push komandą.

Spintos konfigūravimas

Django settings.py reikia įtraukti tokius nustatymus, keičiamus per django-environ:

• SPINTA_EXECUTABLE = "spinta" - kelias iki spinta vykdomojo failo
• SPINTA_SERVER_URL = "https://put-test.data.gov.lt" - Saugyklos serveris į kurį publikuojami duomenys, pilnas URL
• SPINTA_SERVER_NAME = "put-test.data.gov.lt" - Saugyklos serveris į kurį publikuojami duomenys, pavadinimas iš credentials.cfg failo (konfigūruojama serveryje rankiniu būdu).
• SPINTA_PATH = None - kelias iki katalogo, kuriame saugomi visi Spintos konfigūracijų ir publikavimo failai.

Kiekvienam duomenų šaltiniui, prie kurio yra pažymėta „Publikuoti duomenis Saugykloje“ sukuriamas katalogas su pilna Spintos konfigūracija. Katalogo vieta nurodoma settings.py (SPINTA_PATH).

Spintos konfigūracijų kataloge, kiekvienam šaltiniui sukuriama konfigūracija atskirame kataloge naudojant sha1(Resource.id) taip:

{SPINTA_PATH}/sha1[:2]/sha1[2:4]/sha1[4:]/

Šiame kataloge sukuriamas config.yml failas:

env: production
data_path: $BASEDIR
default_auth_client: default

keymaps:
  default:
    type: sqlalchemy
    dsn: sqlite:///$BASEDIR/keymap.db

manifest: default
manifests:
  default:
    type: csv
    path: $BASEDIR/manifest.csv
    backend: default
    keymap: default
    mode: internal

accesslog:
  type: file
  file: $BASEDIR/accesslog.json

Čia $BASEDIR yra {SPINTA_PATH}/sha1[:2]/sha1[2:4]/sha1[4:] katalogas.

Kad spinta naudotu tokią konfigūraciją, spinta komandą reikia leisti su SPINTA_CONFIG aplinkos kintamuoju, kuris rodo į $BASEDIR/config.yml.

Toliau reikia eksportuoti šaltinio struktūros aprašą į $BASEDIR/manifest.csv failą iš Katalogo. Eksportavimo funkcionalumas jau turėtu būti įgyvendintas Kataloge. Reikia atkreipti dėmesį, kad eksportuojamas ne visas duomenų rinkinio struktūros aprašas, o tik vieno konkretaus šaltinio.

Duomenų publikavimas

Turint Spintos konfigūracija konkrečiam šaltiniui toliau daromas duomenų publikavimas į Saugyklą tokios komandos pagalba:

spinta push $BASEDIR/manifest.csv --no-progress-bar -o $SPINTA_SERVER_NAME

Komandą leidžiam su python subprocess.run komandą, skaitant stdout ir stderr, su SPINTA_CONFIG envvar, kuris rodo į {SPINTA_PATH}/sha1[:2]/sha1[2:4]/sha1[4:].

Jei komanda baigėsi su klaida, tada reikėtu sukurti užduotį iš komandos išvesties nuskaitant klaidos informaciją. Aprašyme reikia taip pat įdėti ir kelią iki $BASEDIR.

Klaidos informacijai atrodo taip:

Traceback (most recent call last):
  File "..", line xx, in xx
    xx
spinta.exceptions.UnknownMethod: Unknown method 'select' with args select(null).
 Context:
   expr: select(null)
   name: select

Reikia ieškoti eilutės, kuri prasideda Traceback, tada ieškoti sekančios eilutės, kuri prasideda ne tarpu ir nuskaityti šią dalį:

spinta.exceptions.UnknownMethod: Unknown method 'select' with args select(null).
 Context:
   expr: select(null)
   name: select

Kur turėtu keliauti į užduoties aprašymą.

Ko gero, galima nuskaityti tik pirmą klaidą, nes jų gali būti daug.

Jei tokio tipo užduotis, konkrečiam šaltiniui jau yra sukurta, tada naujos užduoties kurti nereikia, užtenka tik atnaujinti užduoties aprašymą ir pakeisti užduoties statusą į atidarytą, jei ji buvo uždaryta.

Sukuriamas naujas šaltinis

Skriptas, sėkmingai išpublikavus duomenis, jei nėra, sukuria Kataloge, naują šaltinį, kur išpublikuoti duomenys, su nuoroda į Saugyklą, kur yra padėti duomenys.

Jei šaltinis jau yra sukurtas, tada tiesiog atnaujinama šaltinio paskutinio publikavimo data.

[sirex]

Dar vienas niuansas, būtų gerai, kad skriptas veiktų per Katalogo API: https://data.gov.lt/partner/api/1/

Nes greičiausiai šitą skriptą reikės leisti iš kito serverio, kuriame nebus pasiekiama duomenų bazė ir failai tiesiogiai.

[sirex]

Dar vienas niuansas apie kurį pamiršau.

Sukūrus duomenų šaltinį, kurio duomenys saugomi ne Saugykloje, reikia nuskaityti struktūros aprašą naudojant Saugyklos API:

• https://github.com/atviriduomenys/spinta/issues/477

Ir importuoti gautą struktūrą į Katalogą.

Kitu atveju, neturint struktūros, nebus įmanomas duomenų sukėlimas į Saugyklą.

Apibendrinant:

1. Sukuriamas naujas duomenų šaltinis:

   

   Nurodoma išorinio šaltinio nuoroda arba įkeliamas duomenų failas į Katalogą.

2. Išsaugoma šaltinis

3. Šaltinio peržiūros puslapyje paspaudus mygtuką „Nuskaityti struktūrą“ (mygtukas nerodomas, jei formatas yra nepalaikomas Saugykloje):

   

   Kreipiamasi į Saugyklos inspect API ir nuskaitoma šaltinio struktūra:

   • https://github.com/atviriduomenys/spinta/issues/477

4. Nuskaityta struktūra peržiūrima/pataisoma ir sukuriama nauja versija, kaip tai įgyvendinta:

   • https://github.com/atviriduomenys/katalogas/issues/37

5. Sukurta versija įkeliama į Saugyklą:

   • https://github.com/atviriduomenys/katalogas/issues/346

6. Galiausiai, paleidžiamas šios užduoties skriptas, kuris paleidžia spinta push su konkrečia Saugykloje įkelta šaltinio struktūros aprašo versija.

7. Po sėkmingi duomenų publikavimo Saugykloje, sukuria naują duomenų šaltinį, su uapi (Saugyklos API) formatu, šalia į Katalogą įkelto failo arba išorėje publikuojamų duomenų.

8. Nesėkmės atveju sukuria Užduotį, su spinta push klaidos informacija, prie šaltinio.

[sirex]

Dar vienas niuansas. Skaitomi duomenis iš Katalogo API, reikia gauti informaciją ar resursą reikia publikuoti Saugykloje ir jei reikia, tai reikia gauti informaciją iš API, koks yra duomenų publikavimo periodiškumas.

Publikuojant duomenis į Saugyklą, reikia įvertinti periodiškumą ir publikavimą atlikti tik nustatytais periodiškumo intervalais. Pavyzdžiui, jei duomenų rinkinys atnaujinamas kas metus, tai skriptas turėtu daryti atnaujinimą tik tuo atveju, jei nuo paskutinio atnaujinimo praėjo metai.

Kada žinoti, kada buvo darytas paskutinis atnaujinimas, galima BASEDIR/state.json faile išsaugoti laiką, kada buvo paskutinis atnaujinimas. Failo turinys gali atrodyti taip:

{
    "last_update": "2023-12-14T12:56:00"
}

Jei atnaujinimas baigėsi klaida, tada last_update nėra atnaujinamas. last_update atnaujinamas, tik tuo atveju, jei atnaujinimas buvo sėkmingas.

[sirex]

https://github.com/atviriduomenys/katalogas/issues/343#issuecomment-1846975335 komentare, trečiame punkte buvo nurodyta, kad struktūros nuskaitymui iš duomenų reikia naudoti Saugyklos HTTP inspect API, tačiau, kadangi duomenys jau įkelti į Katalogą, o Spinta taip pat įdiegta ir sukonfigūruota Kataloge, tai geresnis variantas tiesiog iškviesti spinta inspect -r csv path/to/data.csv -o dsa.csv komandą, o nesikreipti į išorinį API.