Chiamate JSON-RPC

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

list_databases()

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)

open_database(driver, dbname, username, password)

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. 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.

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. 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.

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" },
  ]
}