gimsisextClient: informacije, navodila in dokumentacija

Opomba: ta dokumentacija je bila spisana za gimsisextClient verzijo 0.10.0. Zagotovite si najnovejšo dokumentacijo v primeru, da obstaja.

 Uvod

gimsisextclientje spisan v programskem jeziku PHP.

Deluje na principu Site scrapinga. Podatke prejema iz aspx in asmx strani zGimSISExt2016 spletišča, ki ga gostuje Gimnazija Bežigrad.

Samostojno gostovanje

Pogoji za delovanje

  • PHP 7.3 (deluje na vseh PHP7 verzijah, PHP5 je zastarel)
  • cURL modul za PHP
V primeru gostovanja endpointa je potrebno imeti še:
  • nginx
  • PHP 7.3 FPM
V primeru uporabe v ukazni vrstici je potrebno imeti še:
  • PHP 7.3 CLI

Obvestilo za uporabnike gimsisextClienta, ki ga gostujete sami

zGimSISExt2016 z marca 2020 ne bo več dostopen. Nadomestil ga je BežiApp. Če imate gimsisextclient že nameščen, čim prej začnite uporabljati https://zgimsis.gimb.tk/ namesto https://zgimsis.gimb.org/, neuradni dostop do zgimsisa, ki je gostovan na BežiApp strežnikih.

Inštalacija

$ sudo apt install php7.3-cli php7.3-curl -y
$ sudo apt install nginx php7.3-fpm -y # če potrebujemo endpoint
$ git clone
$ https://uporabn:geslo@github.com/sijanec/gimsisextclient
$ cd gimsisextclient

Primer uporabe

<?php
require_once "main.php"; // naloži datoteko s classom
$gsec = new gimsisextClient(); // naredi gimsisextclient objekt
$gsec->setusername("ime.priimek"); // dijaka ali starša
$gsec->setpassword("geslo"); // dijaka ali starša
var_dump($gsec->fetchurnik("21.04.2004")); // vrne array z urnikom za 21. april 2004
exit();
?>

fetchurnik lahko seveda zamenjamo s katerokoli metodo, opisano spodaj.

Endpoint

Inštalacija - samostojno gostovanje

Uredimo nginxovo konfiguracijsko datoteko (sudo nano /etc/nginx/sites-enabled/default):

server {                                                                                                                                                                            
        listen 0.0.0.0:80;                                                                                                                                                                                                                                                                                                      
        listen [::]:80;                                                                                                                                                             
        # odkomentiramo spodaj, če želimo HTTPS
# listen 0.0.0.0:443 ssl http2;
# listen [::]:443 ssl http2;
# ssl_certificate /etc/ssl/ssl.crt; # ssl_certificate_key /etc/ssl/ssl.key; # ssl_session_cache builtin:1000 shared:SSL:10m; # ssl_prefer_server_ciphers on; server_name .gimsisextclient.naša.domena; location / { include snippets/fastcgi-php.conf; fastcgi_pass unix:/run/php/php7.3-fpm.sock;
fastcgi_param SCRIPT_FILENAME /pot/do/gimsisextclient/endpoint.php;
} access_log off; # drugače bodo gesla v logih }
 

Ponovno zaženemo nginx z sudo service nginx restart

Sedaj imamo svoj gimsisextClient endpoint na http://gimsisextclient.naša.domena/.

Uporaba

Uporabljamo lahko bodisi svoj gostovan endpoint ali javni testni endpoint na https://gimb.tk/test.php.

Zahteve lahko pošiljamo bodisi z GET bodisi z POST. V vsakem primeru uporabljamo HTTP parametre ali v POST telesu ali pa v GET URIju.

Avtentikacija

Vsaka zahteva na endpoint mora vsebovati uporabniško ime in geslo. Pošljemo jih kot GET ali POST parametra u in p. Piškotkov ali drugih informacij o seji endpoint ne uporablja.

Izbira metode

Metodo (npr. fetchurnik) izberemo z HTTP parametrom m. Metoda mora biti izbrana.

Navajanje parametrov v metodo

Parametre dodajamo v HTTP zahtevo kot HTTP parametre od a do d, kjer je a prvi in d peti parameter.

Odziv

Odziv ima ne glede na odgovor kodo 200 OK. V primeru napake nima vsebine (Content-Length: 0). Content-Type bo vedno application/json ne glede na Accept header. Podatki se pošljejo kot JSON encodan array, ki ga pošlje izbrana metoda/funkcija.

Metode in njihova uporaba

V tej sekciji je opisana skoraj vsaka metoda classa gimsisextClient. nekatere metode, ki izkoriščajo varnostne luknje, so izvzete, da jih administratorji zGimSISExt2016 ne bi popravili.

Funkcije/metode so javne, razen če je drugače navedeno.

Funkcije/metode potrebujejo nastavljeno uporabniško ime in geslo, razen če je drugače navedeno.

setusername

Nastavi uporabniško ime dijaka/starša v objekt. Ne naredi nobenih HTTP zahtev na GSE.

Vhodni podatki
  1. niz: uporabniško ime
Izhodni podatki

Brez

setpassword

Nastavi geslo dijaka/starša v objekt. Ne naredi nobenih HTTP zahtev na GSE.

Vhodni podatki
  1. niz: geslo
Izhodni podatki

Brez

getversion

Pove verzijo gimsisextClienta. Ob času pisanja je to na primer 0.9.1.

Vhodni podatki

Brez

Izhodni podatki

Seznam:

  • 0: int Glavna veja programa
  • 1: int Izdaja
  • 2: int Popravek

login

Je privatna funkcija in ni klicljiva izven objekta.

Vhodni podatki

Brez

Izhodni podatki

cURL handler, pripravljen na naslednji klic (vnešeni sejni piškotki).

fetchurnik

Pridobi in vrne parsan urnik celega tedna.

Vhodni podatki
  • niz: "DD.MM.YYYY" izbere teden, za katerega pridobimo urnik (Ob nenavedbi se upošteva trenutni datum)
Izhodni podatki

Seznam:

  • int Dan v tednu (0-4 = pon-pet):
    • int Šolska ura v dnevu:
      • niz "predmet": niz Ime predmeta
      • niz "kratica": niz Kratica predmeta
      • niz "razred": niz Oznaka razreda/skupine
      • niz "profesor": niz Ime in priimek profesorja
      • niz "prostor": niz Ime učilnice
    • ...
  • ...

fetchocenjevanja

Vrne prihajajoča vpisana ocenjevanja dijaka, urejena po datumu.

Vhodni podatki

Brez.

Izhodni podatki

Seznam:

  • int Zaporedna številka ocenjevanja:
    • niz "datum": niz "DD.MM.YYYY" datum ocenjevanja
    • niz "kratica": niz Kratica predmeta
    • niz "predmet": niz Ime predmeta
    • niz "opis": niz Opis, ki ga določi profesor

fetchprofesorji

Vrne profesorje, ki jih ima ta dijak.

Vhodni podatki

Brez.

Izhodni podatki

Seznam:

  • int Zaporedna številka:
    • niz "ime": niz Ime profesorja
    • niz "predmeti":
      • int Zaporedna številka:
        • niz "ime": niz Ime predmeta
        • niz "kratica": niz Kratica predmeta
    • niz "govorilneure":
      • niz "dan": int Zaporedna številka dneva v tednu (0=pon 4=pet)
      • niz "solskaura": int Številka šolske ure
      • niz "uraod": niz Začetek govorilnih ur (HH:MM)
      • niz "urado": niz Konec govorilnih ur (HH:MM)
  • ...

fetchprofil

Vrne informacije o dijaku

Vhodni podatki

Brez.

Izhodni podatki

Seznam:

  • niz "ime": niz Ime dijaka
  • niz "priimek": niz Priimek dijaka
  • niz "spol": niz Spol dijaka (M/Ž)
  • niz "vrsta": niz Vrsta dijaka || null
  • niz "eposta": niz Naslov elektronske pošte dijaka
  • niz "obvestila": int Ali so obvestila po e-pošti vklopljena (1/0)
  • niz "telefon": niz Telefonska številka dijaka

setprofil

Nastavi profil

Vhodni podatki
  • niz Ime dijaka
  • niz Priimek dijaka
  • niz Spol dijaka (M/Ž)
  • niz Naslov elektronske pošte dijaka
  • niz Ali naj so obvestila dijaka po e-pošti vklopljena ("true"/"false")
  • niz Telefonska številka dijaka
Izhodni podatki

bool Ali je zamenjava uspela

fetchabout

Izve informacije o zGimSISExt2016 strežniku in programju.

Vhodni podatki

Brez.

Izhodni podatki

Seznam:

  • niz "ime": niz "GimSisExt"
  • niz "opis": niz "Gimnazijski in srednješolski informacijski sistem"
  • niz "ver": niz Verzija zGimSISExt2016 programa, ki teče na strežniku
  • niz "copyright": niz "Copyright © M & B 2012"
  • niz "podjetje": niz "M & B"
  • niz "konfiguracija": niz ""

fetchneprebrana

Izve in vrne število neprebranih sporočil.

Vhodni podatki

Brez.

Izhodni podatki

int Število neprebranih sporočil.

fetchsporocilaseznam

Izve in vrne seznam sporočil

Vhodni podatki

int Katera sporočila (0=prejeta 1=poslana 2=izbrisana) (Ob nenavedbi se izbere 0)

Izhodni podatki

Seznam:

  • int Zaporedna številka:
    • niz "datum":
      • niz "dan": int Dan v mesecu (1-31 / 1-30 / 1-29 / 1-28)
      • niz "mesec": int Mesec v letu (1-12)
      • niz "leto": int Leto našega štetja (1901-2038)
    • niz "cas":
      • niz "ura": int Ura v dnevu (0-23)
      • niz "minuta": int Minuta v uri (0-59)
    • niz "posiljatelj": niz Ime in priimek pošiljatelja
    • niz "zadeva": niz Zadeva sporočila
    • niz "id": niz ID Sporočila
    • niz "prebrano": bool Ali je bilo sporočilo že prebrano (true/false)
  • ...

fetchsporocilo

Izve telo in ostale podatke sporočila in jih vrne.

Vhodni podatki
  • niz ID Sporočila
Izhodni podatki

Seznam:

  • niz "telo": niz Telo sporočila
  • niz "zadeva": niz Zadeva sporočila
  • niz "posiljatelj": niz Ime in priimek pošiljatelja
  • niz "datumincas":
    • niz "opis": niz DD. MMM YYYY HH:MM
    • niz "cas":
      • niz "ura": niz HH
      • niz "minuta": niz MM
    • niz "datum":
      • niz "dan": int DD
      • niz "mesecbeseda": niz "jan"-"dec"
      • niz "leto": niz YYYY
      • niz "jsmesec": int Mesec po javascript notaciji (0-11 = jan-dec)
      • niz "mesec": niz Mesec po ne-retardirani notaciji ("1"-"12" = jan-dec)

posljisporocilo

Uporablja se za pošiljanje sporočila :mind_blown: dijakom, staršem ali profesorjem

Vhodni podatki
  • int Prejemnik (pridobiti se da edino z bruteforceom)
  • niz Zadeva
  • niz Telo (mora biti HTML encodano)
Izhodni podatki

Brez.

setgeslo

Spremeni uporabnikovo geslo

Vhodni podatki
  • niz Novo gelo
  • bool Spremeni geslo v objektu (ali naj se zgodi $this->setpassword($novogeslo))
Izhodni podatki

bool Ali se je geslo uspešno spremenilo

izbrisisporocilo

Premakne sporočilo med izbrisana sporočila.

Vhodni podatki
  • niz ID sporočila
Izhodni podatki

Brez.

 fetchizostanki

Pridobi in vrne izostanke dijaka od pouka v odbobju

Vhodni podatki
  • niz Datum začetka obdobja (DD.MM.YYYY)
  • niz Datum konca obdobja (DD.MM.YYYY)
Izhodni podatki

 

Seznam:

  • int Zaporedna številka dneva, ki vsebuje izostanke:
    • niz "datum":
      • niz "dan": int Dan v mesecu (1-31 / 1-30 / 1-29 / 1-28)
      • niz "mesec": int Mesec v letu (1-12)
      • niz "leto": int Leto našega štetja (1901-2038)
      • niz "predmeti":
    • niz "stevilo": int Število ur, ko dijak ni bil prisoten
    • niz "predmeti":
      • int Zaporedna številka (ne ponazarja številke ure v dnevu!, glej ura \/)
        • niz "ime": niz Ime predmeta
        • niz "opraviceno":
          • niz "status": int Status opravičenosti (0 = ni obdelano, 1 = opravičeno, 2 = neopravičeno, 3 = ne šteje)
          • niz "opis": niz Opis stanja neopravičenosti (ni obdelano / opravičeno / neopravičeno / ne šteje)
        • niz "ura": int Številka ure, ko dijak ni bil prisoten (uporabi to)

resetgeslo

Uporabniku pošlje e-poštno sporočilo z povezaveo za ponastavitev gesla. Ob vsakem klicu pošlje sporočilo, tudi če je sporočilo predhodno že bilo poslano! Vrne uporabnikov e-poštni naslov.

Opomba: Prijava ni potrebna

Vhodni podatki
  • niz Uporabniško ime dijaka/starša (ime.priimek)
Izhodni podatki

niz Naslov elektronske pošte dijaka/starša, ki mu je bil poslano e-poštno sporočilo

fetchocene

Vrne ocene dijaka.

Opomba: Z 0.9.3 se pojavita staraocena in starazacasna. Ti dve polji se pojavita v oceni le, kadar ima ocena novo, popravljeno oceno (npr. 2. rok) in prikazujeta prejšno oceno.

Vhodni podatki

Brez.

Izhodni podatki

Seznam (Urejen po pomembnosti predmetov?!1):

  • int Zaporedna številka vnosa ocene:
    • niz "datum": niz Datum vpisa ocene (DD.MM.YYYY)
    • niz "profesor": niz Ime in priimek profesorja, ki je dodelil oceno
    • niz "predmet": niz Ime predmeta, kjer je bila ocena dodeljena
    • niz "naslov": niz Naslov ocene, naveden s strani profesorja
    • niz "vrsta": niz Nekakšen opis ocene
    • niz "rok": niz Nekakšen globlji opis ocene
    • niz "ocena": int Najnovejša ocena, ki jo je dobil dijak (1-5 = nezadostno-odlično)
    • niz "zacasna": bool V kolikor je najnovejša ocena začasna, je to true, drugače pa false
    • niz "staraocena": int Stara ocena, če obstaja (npr. 1. rok)
    • niz "starazacasna": bool V kolikor je stara ocena začasna, je to true

fetchvsasporocila

Vrne vsa sporocila, vred z telesi. Nepriporočeno, ker traja zelo dolgo. Vsako sporočilo je pridobljeno v eni HTTP zahtevi, zGimSISExt2016 strežnik ne podpira HTTP/2 SPDY in podpira maksimalno 300 povezav. Za prenos 300+ sporočil (hitro se nabere) bi torej zablokirali strežnik. Sporočila so zato pridobljena po eni povezavi sinhronično (aasync). Če to traja dlje kot 69 sekund (vsaj kar se tiče javnega testnega endpointa) bo strežnik odgovoril z napako HTTP 504 Gateway Timeout in ne bo poslal podatkov.

Metoda/funkcija ni dokumentirana, ker je "deprecated".

Kot je razvidno iz posnetka zaslona, je ta metoda/funkcija neuporabna.
Kot je razvidno iz posnetka zaslona, je ta metoda/funkcija neuporabna.

spremenigeslo

Spremeni geslo uporabnika in mu pošlje e-poštno sporočilo, ki ga informira o tem.

Za uporabo te metode potrebujete dodatne nastavitve:

  • Uporabljati morate mapo ~/Mailbox/new za prejeto elektronsko pošto, ki ima datoteke v Outlookovem formatu (base64 encodan HTML body, primer maila)
  • Program se mora poganjati kot uporabnik, ki ne dobiva druge pošte.
  • Nastaviti morate privatno spremenljivko $adminusername v prvih vrsticah classa na vaše zGimSIS2016 uporabniško ime, ki ima e-poštni naslov nastavljen tako, da e-poštna sporočila o resetu gimsis gesla prispejo v ~/Mailbox/new na mašini, ki poganja gseC.

Opomba: Prijava ni potrebna.
Opomba: Metoda je onemogočena na javnem endpointu.
Opomba: Metode NE SMETE uporabljati, prav tako vam je itak verjetno sploh ne bom poslal, ker sprememba gesla brez privolitve uporabnika ni v skladu z zakonodajo. Namenjena je izključno za namene izobraževanja.

Vhodni podatki
  • niz Uporabniško ime uporabnika, kateremu želite spremeniti geslo
  • niz Novo geslo za tega uporabnika
Izhodni podatki

bool Ali je bilo geslo uspešno spremenjeno?

Dnevnik sprememb

  • 0.10.0 (12. februar 2020 ob 20:54, b5473ca) dodal spremenigeslo.
  • 0.9.2 (4. februar 2020 ob 20:54, a84a6d9fetchocene: pojavita se polji novaocena in novazacasna, ki nakazujeta popravljeno oceno.
  • 0.9.3 (6. februar 2020 ob 20:54, 30439d3fetchocene: pojavita se polji staraocena in starazacasna, ki nakazujeta oceno, preden je bila popravljena. Polji nova* ne obstajata več, iz legacy purposes je ocena in zacasna vedno najnovejša ocena.

Konec dokumentacije!

Ufff, hvala za pozornost!

Dokumentacijo sem spisal GimB Dijaki.

Comments