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: .. function:: 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. .. _json_rpc_open_database: .. function:: 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 :ref:`accedere direttamente a immagini e allegati ` tramite URL opportunamente formattate. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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. .. function:: 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``). .. function:: 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" }, ] }