Chiamate JSON-RPC

Questa documentazione contiene le specifiche delle chiamate JSON-RPC. Per informazioni sul formato delle richieste, si rimanda alle specifiche ufficiali del formato JSON-RPC.

Il servizio web integrato di Konga fornisce le seguenti chiamate JSON-RPC:

list_databases([tenantkey]): Restituisce una lista di N dizionari (dove N è il numero di database trovati sul server), dove il singolo dizionario include informazioni su un database presente sul server. Le chiavi utili di questo dizionario sono driver (nome del driver usato dal database, ad esempio «mysql») e name (nome del database). Il parametro opzionale tenantkey è necessario se il server è in modalità multi-tenant e serve ad identificare la corretta lista dei database per il proprietario corrispondente.

open_database(driver, dbname, username, password[, tenantkey]): Apre una nuova connessione con il database chiamato dbname usando il driver specificato. L’autenticazione sul database è effettuata contestualmente usando il nome utente username e la password forniti nella chiamata. Il parametro opzionale tenantkey è necessario se il server è in modalità multi-tenant e serve ad autenticare il proprietario del database. Questa chiamata restituisce una stringa col il SID (session ID) che identifica la connessione stabilita; questo SID potrà essere passato nella chiamate successive per effettuare operazioni sul database. Può essere inoltre usata per accedere direttamente a immagini e allegati tramite URL opportunamente formattate.

close_database(sid): Chiude il database correntemente usato dalla connessione identificata da sid. Normalmente non è necessario chiamare questo metodo, in quanto il database verrà automaticamente chiuso quando la sessione sarà scaduta.

lock_resource(sid, tablename[, row_id]): Blocca una risorsa sul server, usando la connessione con il database identificata da sid. La risorsa da bloccare è identificata dal nome della tabella corrispondente (tablename), eventualmente unita ad un ID di riga (row_id, corrispondente alla chiave primaria id della tabella tablename); se row_id non è specificato, l’intera tabella tablename è bloccata sul server. Il valore di ritorno è un dizionario con almeno la chiave answer che per un funzionamento corretto deve contenere il valore 0, altrimenti un codice errore Konga. Se la risorsa è già bloccata da un altro utente, il dizionario contiene anche la chiave owner_data, che è un sotto-dizionario contenente le chiavi NickName, NomeCompleto e TimeStamp, che rappresentano l’utente che ha già bloccato la risorsa.

unlock_resource(sid, tablename[, row_id]): Sblocca una risorsa sul server, usando la connessione con il database identificata da sid. La risorsa da sbloccare è identificata dal nome della tabella corrispondente (tablename), eventualmente unita ad un ID di riga (row_id, corrispondente alla chiave primaria id della tabella tablename); se row_id non è specificato, l’intera tabella tablename è sbloccata sul server. Il valore di ritorno è un dizionario con la chiave answer, che per un funzionamento corretto deve contenere il valore 0, altrimenti un codice errore Konga.

select_data(sid, tablename[, fieldnamelist, where_expr, order_by, order_desc, offset, limit]): Ottiene dati dalla tabella tablename mediante una SELECT SQL sul database connesso identificato da sid. La lista dei nomi dei campi fieldnamelist può contenere nomi nella forma tabella.ref[.ref...].campo per accedere a campi di tabelle collegate mediante JOIN automatici; se non specificata, select_data ritornerà tutti i campi della tabella tablename. E” possibile specificare una espressione WHERE SQL da applicare alla SELECT in where_expr, nonché l’ordinamento tramite order_by e order_desc, l”OFFSET e il LIMIT SQL tramite offset e limit. order_by può essere un nome campo o una lista JSON di nomi di campi per cui eseguire l’ordinamento; allo stesso modo order_desc può essere true (forza ordine discendente) o false (forza ordine ascendente) oppure una lista di valori booleani nel caso si stia eseguendo un ordinamento su più campi. La chiamata restituisce una lista di N+1 righe, dove N è il numero di righe del result-set corrispondente alla SELECT effettuata. La prima riga della lista è sempre la lista dei nomi dei campi restituiti, mentre le N righe successive sono ognuna la lista dei valori per la riga corrispondente.

get_record(sid, tablename[, id, code, code_azienda, num_esercizio]): Ottiene i dati di un record della tabella tablename dal database connesso identificato da sid. Il record può essere identificato in due modi: il primo è specificare l”id univoco della riga di tablename che si vuole ottenere; il secondo è specificare il codice o numero interno del record tramite code, unitamente al codice azienda code_azienda e al numero dell’esercizio num_esercizio. In questo secondo caso il valore del parametro id può essere lasciato a null. Questa chiamata restituisce un dizionario con i dati del record. Vedere la documentazione di kongalib.Client.get_record() per maggiori informazioni.

insert_record(sid, tablename, code_azienda, num_esercizio, data): Inserisce un nuovo record per la tabella tablename sul database connesso identificato da sid. code_azienda e num_esercizio sono stringhe che identificano univocamente l’azienda e l’esercizio di appartenenza del record; data deve essere un dizionario contenente i dati del record da inserire. La chiamata restituisce un dizionario con le chiavi id (ID della riga del record appena inserito) e code (codice del record). Vedere la documentazione di kongalib.Client.insert_record() per maggiori informazioni.

update_record(sid, tablename[, id, code, code_azienda, num_esercizio, data]): Aggiorna i dati di un record per la tabella tablename sul database connesso identificato da sid. Il record può essere identificato in due modi: il primo è specificare l”id univoco della riga di tablename che si vuole aggiornare; il secondo è specificare il codice o numero interno del record tramite code, unitamente al codice azienda code_azienda e al numero dell’esercizio num_esercizio. In questo secondo caso il valore del parametro id può essere lasciato a null. data deve essere un dizionario contenente i nuovi dati del record. La chiamata non ha valore di ritorno.

delete_record(sid, tablename[, id, code, code_azienda, num_esercizio]): Cancella un record dalla tabella tablename sul database connesso identificato da sid. Il record può essere identificato in due modi: il primo è specificare l”id univoco della riga di tablename che si vuole cancellare; il secondo è specificare il codice o numero interno del record tramite code, unitamente al codice azienda code_azienda e al numero dell’esercizio num_esercizio. La chiamata non ha valore di ritorno.

list_binaries(sid, tablename, id): Ottiene la lista dei dati binari allegati al record id della tabella tablename. Ritorna una lista il cui elemento è una tupla di due elementi: il tipo di allegato (0: documento generico; 1: immagine; 2: immagine web; 3 immagine miniatura) e il nome del file corrispondente.

get_binary(sid, tablename, id, type[, filename]): Ottiene il contenuto binario dell’allegato al record id della tabella tablename indentificato univocamente dal suo tipo type e dal nome file filename. E” necessario specificare il nome del file solo se si richiede un documento generico (type uguale a 0).

set_binary(sid, tablename, id, type, filename, code_azienda, num_esercizio[, data]): Imposta il contenuto binario data dell’allegato al record id della tabella tablename indentificato univocamente dal suo tipo type e dal nome file filename. E” necessario specificare il nome del file solo se si sta registrando un documento generico (type uguale a 0). data deve contenere il contenuto binario sotto forma di stringa codificata in base64; se data è null o non specificato, eventuali dati binari per il record saranno cancellati; code_azienda e num_esercizio sono necessari se i dati binari sono salvati su filesystem dal server Konga.

Esempi

Per ottenere la lista dei database si manda al servizio una richiesta del tipo:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "list_databases",
  "params": []
}

il servizio risponde con qualcosa del tipo:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    { "driver": "sqlite", "name": "demo" },
    { "driver": "mysql", "name": "Converge" },
  ]
}