Implementazione del protocollo Datasource per gli strumenti del grafico (V0.6)

In questa pagina viene descritto come implementare un servizio che supporti il protocollo origine dati di Chart Tools per esporre i dati ai grafici utilizzando la classe Query.

Contenuti

Pubblico

Questa pagina è destinata principalmente agli sviluppatori che creeranno la propria origine dati senza l'aiuto della libreria delle origini dati degli strumenti del grafico. Se utilizzi quella o qualsiasi altra libreria helper, leggi prima la documentazione della libreria.

Questa pagina è rivolta anche ai lettori interessati a comprendere il protocollo di Wi-Fi utilizzato per la comunicazione tra una visualizzazione client e un'origine dati.

Se stai creando o utilizzando una visualizzazione, non è necessario leggere questa pagina.

Per leggere questo documento, devi comprendere la sintassi di base delle richieste JSON e HTTP. Dovresti anche capire come funzionano i grafici dal punto di vista dell'utente.

Nota: Google non approva né supporta ufficialmente le origini dati non Google che supportano il protocollo dell'origine dati degli strumenti di Chart.

Panoramica

Puoi implementare il protocollo Datasource di Chart Tools per diventare un provider di origine dati per i tuoi grafici o altri grafici. Un'origine dati di Chart Tools espone un URL, denominato URL origine dati, a cui un grafico può inviare richieste GET HTTP. In risposta, l'origine dati restituisce dati formattati correttamente che il grafico può utilizzare per visualizzare l'immagine sulla pagina. Questo protocollo di richiesta-risposta è noto come protocollo cavo dell'API Google Visualization.

I dati forniti da un'origine dati possono essere estratti da varie risorse, ad esempio un file o un database. L'unica limitazione è che puoi formattare i dati come tabella bidimensionale con colonne digitate.

In qualità di origine dati degli strumenti grafici, devi analizzare una richiesta in un formato specifico e restituire una risposta in un formato specifico. In generale, puoi farlo in due modi:

  • Utilizza una delle seguenti librerie helper per gestire la richiesta e la risposta e creare la DataTable da restituire. Se utilizzi una di queste librerie, devi scrivere solo il codice necessario per rendere i tuoi dati disponibili alla libreria sotto forma di tabella.
    • Libreria Datasource Java: gestisce la richiesta e la risposta, crea la tabella di risposta a partire dai dati forniti e implementa il linguaggio di query SQL di Google Chart Tools.
    • Libreria di origine dati Python: crea una tabella di risposta che genera la sintassi della risposta. Non gestisce l'analisi della richiesta o l'implementazione del linguaggio di query SQL di Google Chart Tools.

      OPPURE

  • Scrivi la tua origine dati da zero gestendo la richiesta, creando una tabella di dati e inviando la risposta.

Come funziona:

  1. L'origine dati espone un URL, chiamato URL dell'origine dati, a cui i grafici inviano una richiesta GET HTTP.
  2. Il client effettua una richiesta GET HTTP con parametri che descrivono il formato da utilizzare per i dati restituiti, una stringa di query facoltativa e parametri personalizzati facoltativi.
  3. L'origine dati riceve e analizza la richiesta, come descritto in Formato della richiesta.
  4. L'origine dati prepara i dati nel formato richiesto. In genere, si tratta di una tabella JSON. I formati di risposta sono trattati nella sezione Formato di risposta. L'origine dati può supportare facoltativamente il linguaggio di query dell'API di visualizzazione, che specifica filtri, ordinamento e altre manipolazioni dei dati.
  5. L'origine dati crea una risposta HTTP che include i dati serializzati e altri parametri di risposta e la invia al client come descritto in Formato di risposta

Nota: tutti i parametri e i valori delle costanti stringa elencati in questo documento per richieste e risposte (ad esempio responseHandler e "ok") sono in minuscolo e sono sensibili alle maiuscole.

Requisiti minimi

Di seguito sono riportati i requisiti minimi per fungere da origine dati per gli strumenti dei grafici:

  • L'origine dati deve accettare le richieste HTTP GET e deve essere disponibile per i clienti.
  • Il protocollo può cambiare e supporta uno schema di versione (la versione attuale è 0.6), pertanto l'origine dati deve supportare le richieste che utilizzano le versioni precedenti e quella corrente. Ti consigliamo di provare a supportare le nuove versioni non appena vengono rilasciate, per evitare di danneggiare i client che eseguono rapidamente l'upgrade alla versione più recente.
  • Non fallire se nella richiesta vengono inviate proprietà sconosciute. Questo perché le nuove versioni possono introdurre nuove proprietà di cui non sei a conoscenza.
  • Analizza solo le proprietà previste. Anche se le nuove versioni potrebbero introdurre nuove proprietà, non accettare ciecamente e utilizzare l'intera stringa di richiesta. Per proteggerti da attacchi dannosi, analizza e utilizza con attenzione solo le proprietà previste.
  • Documenta attentamente i requisiti delle origini dati se non codifichi personalmente i grafici client. Ciò include la documentazione delle seguenti informazioni:
    • Eventuali parametri personalizzati che accetti
    • Indica se sei in grado di analizzare il linguaggio di query dell'API Google Visualization e
    • Il tipo di dati restituiti e la struttura di tali dati (cosa rappresentano le righe e le colonne ed eventuali etichette).
  • Prendi tutte le precauzioni di sicurezza standard per un sito che accetta richieste da client sconosciuti. Puoi supportare ragionevolmente MD5, hashing e altri meccanismi di sicurezza nei tuoi parametri per autenticare le richieste o contribuire a proteggerti da attacchi dannosi e aspettarti che i client conoscano i tuoi requisiti e li rispondano. Tuttavia, assicurati di documentare bene tutti i requisiti, se non codifichi personalmente i grafici. Vedi Considerazioni sulla sicurezza di seguito.
  • Tutte le stringhe di richiesta e risposta devono avere codifica UTF-8.
  • Il formato di risposta più importante è JSON. Assicurati di implementare prima JSON, poiché questo è il formato utilizzato dalla maggior parte dei grafici. Aggiungi altri tipi di risposta in seguito.
  • Non è necessario supportare il linguaggio di query dell'API di visualizzazione, ma rende l'origine dati più utile per i clienti.
  • Non devi supportare le richieste di tutti i tipi di grafici e puoi supportare parametri personalizzati per i grafici personalizzati. Tuttavia, devi restituire le risposte nel formato standard descritto di seguito.

Considerazioni sulla sicurezza

Quando progetti l'origine dati, devi considerare il livello di sicurezza dei tuoi dati. Puoi utilizzare una serie di schemi di sicurezza per il sito, dal semplice accesso tramite password all'autenticazione sicura dei cookie.

Gli attacchi XSSI (cross-site script inclusione) sono un rischio con i grafici. Un utente potrebbe aprire una pagina contenente uno script dannoso che poi inizia a tentare di eseguire query sugli URL dell'origine dati, utilizzando le credenziali dell'utente corrente. Se l'utente non si è disconnesso da un sito, lo script verrà autenticato come utente corrente e avrà le autorizzazioni su quel sito. Con un tag <script src> lo script dannoso può essere in grado di includere l'origine dati, in modo simile a JSONP.

Come ulteriore livello di sicurezza, potresti valutare la possibilità di limitare le richieste a quelle provenienti dallo stesso dominio dell'origine dati. Ciò limiterà notevolmente la visibilità dell'origine dati, ma ti consigliamo di prendere in considerazione l'eventuale presenza di dati molto sensibili a cui non si dovrebbe accedere dall'esterno del dominio. Un'origine dati che consente solo le richieste dallo stesso dominio è detta origine dati con restrizioni, diversamente da un'origine dati senza restrizioni, che accetta query da qualsiasi dominio. Ecco alcuni dettagli su come implementare un'origine dati limitata:

Per garantire che una richiesta provenga effettivamente dall'interno del tuo dominio e non da un dominio esterno (o da un browser all'interno del dominio oggetto dell'attacco XSRF):

  • Verifica la presenza di un'intestazione "X-DataSource-Auth" nella richiesta. Questa intestazione viene definita dall'API di visualizzazione di Google. Non è necessario esaminare i contenuti dell'intestazione, ma solo verificare che sia presente. Se utilizzi la libreria dell'origine dati di Google Chart Tools, puoi fare in modo che sia la libreria a occuparsene per te.
  • Utilizza l'autenticazione dei cookie per autenticare il client. Non esiste un modo noto per inserire intestazioni personalizzate in una richiesta interdominio, mantenendo i cookie di autenticazione attivi.
  • Rendi meno probabile l'esecuzione del codice JavaScript se incluso con un tag <script src>. A questo scopo, anteponi alla risposta JSON )]}" seguito da una nuova riga. Nel client, rimuovi il prefisso dalla risposta. Per XmlHttpRequest ciò è possibile solo se la richiesta ha avuto origine dallo stesso dominio.

Formato della richiesta

Un client invia una richiesta GET HTTP con diversi parametri, inclusi elementi personalizzati, una stringa di query facoltativa, firma e altri elementi. Sei responsabile esclusivamente dell'analisi dei parametri descritti in questa sezione e devi fare attenzione a non gestire altri parametri per evitare attacchi dannosi.

Assicurati di avere valori predefiniti per i parametri facoltativi (standard e personalizzati) e documenta tutti i valori predefiniti nella documentazione del sito.

Ecco alcuni esempi di richieste (puoi vedere altri esempi di richieste e risposte alla fine di questo documento nella sezione Esempi):

Nota: le seguenti stringhe di richiesta e quelle indicate nella sezione Esempi devono contenere i caratteri di escape url prima dell'invio.

Basic request, no parameters:
http://www.example.com/mydatasource

Request with the tqx parameter that contains two properties:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Request with a query string:
http://www.example.com/mydatasource?tq=limit 1

Di seguito è riportato l'elenco di tutti i parametri standard nella stringa di richiesta. Tieni presente che entrambi i nomi dei parametri (come "version") e i valori di stringhe costanti (come "ok", "warning" e "not_modified") sono sensibili alle maiuscole. La tabella descrive inoltre se il parametro deve essere inviato e, in caso di invio, se devi gestirlo.

Parametro
Obbligatoria nella richiesta?
L'origine dati deve essere gestita?
Descrizione
tq
No
No

Una query scritta nel linguaggio di query dell'API Google Visualization, che specifica come filtrare, ordinare o manipolare in altro modo i dati restituiti. Non è necessario che la stringa sia racchiusa tra virgolette.

Esempio: http://www.example.com/mydatasource?tq=select Col1

tqx
No

Un insieme di coppie chiave/valore delimitato da due punti per parametri standard o personalizzati. Le coppie sono separate da un punto e virgola. Di seguito è riportato un elenco dei parametri standard definiti dal protocollo di visualizzazione:

  • reqId - [Obbligatorio nella richiesta; l'origine dati deve gestire] Un identificatore numerico per questa richiesta. In questo modo, se un client invia più richieste prima di ricevere una risposta, l'origine dati può identificare la risposta con la richiesta corretta. Invia nuovamente questo valore nella risposta.
  • version - [Facoltativo nella richiesta; l'origine dati deve gestire] Il numero di versione del protocollo di visualizzazione Google. La versione attuale è la 0.6. Se non viene inviata, utilizza la versione più recente.
  • sig - [Facoltativo nella richiesta; facoltativo per la gestione dell'origine dati] Un hash di DataTable inviato a questo client in eventuali richieste precedenti a questa origine dati. Questa è un'ottimizzazione per evitare di inviare due volte dati identici a un client. Per informazioni su come utilizzare questa opzione, consulta la sezione Ottimizzare la richiesta di seguito.
  • out - [Facoltativo nella richiesta; l'origine dati deve gestire] Una stringa che descrive il formato per i dati restituiti. Può essere uno qualsiasi dei seguenti valori:
    • json: [valore predefinito] una stringa di risposta JSON (descritta di seguito).
    • html - Una tabella HTML di base con righe e colonne. Se viene utilizzato questo metodo, l'unica cosa che dovrebbe essere restituita è una tabella HTML con i dati; è utile per il debug, come descritto nella sezione Formato di risposta di seguito.
    • csv - Valori separati da virgola. Se viene utilizzato, l'unica cosa restituita è una stringa di dati CSV. Puoi richiedere un nome personalizzato per il file nelle intestazioni della risposta specificando un parametro outFileName.
    • tsv-excel - Simile a csv, ma con tabulazioni al posto delle virgole e tutti i dati hanno la codifica utf-16.
    Tieni presente che l'unico tipo di dati che verrà richiesto da un grafico creato nell'API di visualizzazione di Google è json. Per informazioni dettagliate su ciascun tipo, consulta la sezione Formato di risposta di seguito.
  • responseHandler - [Facoltativo nella richiesta; l'origine dati deve gestire] Il nome della stringa della funzione di gestione JavaScript nella pagina client che verrà chiamata con la risposta. Se non è incluso nella richiesta, il valore è "google.visualization.Query.setResponse". Questo verrà rispedito come parte della risposta; consulta la sezione Formato di risposta di seguito per scoprire come.
  • outFileName - [Facoltativo nella richiesta; facoltativo per la gestione dell'origine dati] Se specifichi out:csv o out:tsv-excel, puoi facoltativamente richiedere il nome file specificato qui. Esempio: outFileName=results.csv.

Esempio: tqx=version:0.6;reqId:1;sig:5277771;out:json; responseHandler:myQueryHandler

tqrt
No
No

Prenotato: ignora questo parametro. Il metodo utilizzato per inviare la query.

Formato della risposta

Il formato della risposta dipende dal parametro out della richiesta, che specifica il tipo di risposta previsto. Per scoprire come rispondere a ogni tipo di richiesta, consulta le sezioni seguenti:

  • JSON: restituisce una risposta JSON che include i dati in un oggetto JavaScript che possono essere passati direttamente a un costruttore DataTable per compilarlo. Questo è senza dubbio il tipo di richiesta più comune e il più importante da implementare correttamente.
  • CSV: restituisce un elenco semplice di valori separati da virgole, che il browser dovrà gestire.
  • TSV: restituisce un elenco di valori separati da tabulazioni, che dovranno essere gestiti dal browser.
  • HTML: restituisce una tabella HTML che il browser deve visualizzare.

Puoi utilizzare la libreria di origine dei dati di visualizzazione di Google (java) o la libreria Python di visualizzazione per generare questi formati di output per te.

Formato della risposta JSON

Il formato predefinito della risposta è JSON se la richiesta include un'intestazione "X-DataSource-Auth", altrimenti JSONP. Tieni presente che il client di grafici di Google supporta in realtà una versione modificata di JSON e JSONP; se utilizzi le librerie helper Java o Python, verranno generati automaticamente il codice corretto; se stai analizzando le risposte manualmente, consulta Modifiche JSON di seguito.

Se applichi richieste per lo stesso dominio, devi verificare la presenza dell'intestazione "X-DataSource-Auth" nella richiesta e utilizzare i cookie di autorizzazione.

Questo è l'unico formato di risposta specificato dal metodo dell'API Google Visualization google.visualization.Query.send() . Puoi vedere alcuni esempi di richieste e risposte JSON alla fine di questa pagina in Esempi. Puoi utilizzare le librerie helper Java o Python per creare automaticamente questa stringa di risposta.

Questo formato di risposta è un oggetto JSON codificato UTF-8 (un oggetto aggregato tra parentesi graffe { } con ogni proprietà separata da una virgola) che include le proprietà nella tabella seguente (i dati sono assegnati alla proprietà table). Questo oggetto JSON deve essere aggregato all'interno del valore del parametro responseHandler della richiesta. Quindi, se il valore responseHandler della richiesta era "myGestori", devi restituire una stringa come questa (solo una proprietà mostrata per brevità):

"myHandler({status:ok, ...})"

Se la richiesta non includeva un valore responseHandler, il valore predefinito è "google.visualization.Query.setResponse", quindi dovresti restituire una stringa come questa (viene mostrata solo una proprietà per brevità):

"google.visualization.Query.setResponse({status:ok, ...})"

Ecco i membri disponibili dell'oggetto risposta:

Proprietà
Obbligatoria?
Descrizione
versione
No

Un numero di stringa che corrisponde al numero di versione del protocollo di visualizzazione di Google. Se non specificata, il client presume la versione più recente.

Esempio: version=0.6

reqId
Sì*
Un numero di stringa che indica l'ID della richiesta per il client. Se questo era presente nella richiesta, restituisci lo stesso valore. Per ulteriori dettagli, consulta la descrizione di reqId nella sezione della richiesta.

* Se questo parametro non è stato specificato nella richiesta, non è necessario impostarlo nella risposta.
status

Una stringa che descrive l'esito positivo o negativo di questa operazione. Deve essere uno solo dei seguenti valori:

  • ok - Richiesta riuscita. Una tabella deve essere inclusa nella proprietà table.
  • warning - Operazione riuscita, ma con problemi. Una tabella deve essere inclusa nella proprietà table.
  • error: si è verificato un problema. Se restituisci questo valore, non devi restituire table e devi restituire errors.

Esempio: status:'warning'

avvisi
Solo se status=warning

Un array di uno o più oggetti, ognuno dei quali descrive un problema non irreversibile. Obbligatorio se status=warning, non consentito negli altri casi. Ogni oggetto ha le seguenti proprietà di stringa (restituisce un solo valore per ogni proprietà):

  • reason - [Obbligatorio] Una descrizione stringa di una sola parola dell'avviso. Il protocollo definisce i seguenti valori, ma puoi definire i tuoi valori, se necessario (tuttavia, il client non elaborerà i valori personalizzati in alcun modo speciale). Puoi avere un solo valore reason:
    • data_truncated: per l'elemento DataTable restituito sono state rimosse alcune righe, perché l'utente ha incluso una stringa di query che ha tagliato l'elenco dei risultati o perché l'origine dati non voleva restituire risultati completi per qualche motivo.
    • other: un avviso generico non specificato.
  • message - [Facoltativo] Una breve stringa tra virgolette che spiega il problema, eventualmente utilizzata come titolo per una casella di avviso. Questa informazione potrebbe essere mostrata all'utente. HTML non supportato.
  • detailed_message - [Facoltativo] Un messaggio stringa tra virgolette dettagliato che spiega il problema ed eventuali soluzioni possibili. L'unico codice HTML supportato è l'elemento <a> con un singolo attributo href. La codifica Unicode è supportata. Questa informazione potrebbe essere mostrata all'utente.

Esempio: warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}]

errori
Obbligatorio se status=error

Un array di uno o più oggetti, ognuno dei quali descrive un errore. Obbligatorio se status=error, non consentito negli altri casi. È simile al valore warnings. Tieni presente che l'errore not_modified, sebbene sia un errore, non è in realtà un errore per il client.

L'array ha i seguenti membri di stringa (restituisce un solo valore per ogni membro):

  • reason - [Obbligatorio] Uguale a warnings.reason, ma sono definiti i seguenti valori:
    • not_modified - I dati non sono stati modificati dall'ultima richiesta. Se questa è la causa dell'errore, non dovresti avere un valore per table.
    • user_not_authenticated - Se l'origine dati richiede l'autenticazione e non è stata eseguita, specifica questo valore. Il client mostrerà un avviso con il valore message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other - Un errore generico non specificato.
  • message - [Facoltativo] Come warnings.message. Nota: è possibile che un utente malintenzionato possa usare una stringa di dati dettagliata per accedere a dati non autorizzati o persino utilizzarla per attaccare i tuoi dati o il tuo sito. Se archivi dati che dovrebbero essere sicuri o elabori direttamente le query degli utenti, valuta la possibilità di non restituire un messaggio di errore dettagliato che potrebbe fornire informazioni a un utente malintenzionato, ma di fornire un messaggio generico, ad esempio "Stringa di query non valida".
  • detailed_message - [Facoltativo] Come warnings.detailed_message. Vedi l'avviso per informazioni troppo dettagliate su message.

Esempio: status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]

sig
No

Un valore hash dell'oggetto tabella. Utile per ottimizzare il trasferimento di dati tra il client e l'origine dati. Puoi scegliere qualsiasi algoritmo hash desiderato. Se supporti questa proprietà, devi restituire il valore trasmesso dal client se non vengono restituiti dati oppure un nuovo hash se vengono restituiti nuovi dati.

Esempio: sig:'5982206968295329967'

tavolo
No

Un oggetto DataTable in notazione letterale JavaScript, con i tuoi dati. Per informazioni dettagliate sul formato di questo oggetto, consulta la sezione di riferimento collegata. Ecco un esempio di tabella di dati semplice:

{cols:[{id:'Col1',label:'',type:'number'}],
 rows:[{c:[{v:1.0,f:'1'}]},
       {c:[{v:2.0,f:'2'}]},
       {c:[{v:3.0,f:'3'}]},
       {c:[{v:1.0,f:'1'}]}
      ]
} 

La proprietà table deve essere presente solo se status=ok o status=warning. Se non restituisci dati, non includere questa proprietà (ovvero, non trasmettere la proprietà con un valore di stringa vuoto).

Esempio: consulta gli esempi riportati di seguito.

 

È richiesto un file JSON rigido

Le librerie helper di Google e tutte le query inviate a Google restituiscono il codice JSON/JSONP rigoroso. Se non stai analizzando personalmente il codice restituito, questo non dovrebbe essere importante per te. In caso affermativo, puoi utilizzare JSON.parse() per convertire la stringa JSON in un oggetto JavaScript. Una differenza nel modo in cui JSON viene elaborato dall'API è che, sebbene JSON non supporti i valori JavaScript Date (ad esempio, "new Date(2008,1,28,0,31,26)"), l'API supporta una rappresentazione JSON valida delle date come stringa nel seguente formato: Date(year, month, day[,hour, minute, second[, millisecond]]), dove tutto il giorno dopo il giorno è facoltativo e i mesi sono in base zero.

 

Ottimizzare le risposte JSON

Se un client effettua due richieste e i dati non sono cambiati da una richiesta all'altra, ha senso non inviarli di nuovo, altrimenti sprecherebbe larghezza di banda. Per rendere le richieste più efficienti, il protocollo supporta la memorizzazione nella cache dei dati sul client e l'invio di un indicatore nella risposta se i dati non sono stati modificati dall'ultima richiesta. Ecco come fare i calcoli:

  1. Il client invia una richiesta all'origine dati.
  2. L'origine dati genera un DataTable e un hash dell'oggetto DataTable e restituisce entrambi nella sua risposta (l'hash viene restituito nel parametro tqx.sig). Il client dell'API Google Visualization memorizza nella cache i valori DataTable e sig.
  3. Il client invia un'altra richiesta di dati, incluso il valore tqx.sig memorizzato nella cache.
  4. L'origine dati può rispondere in uno dei due seguenti modi:
    • Se i dati sono cambiati rispetto alla richiesta precedente, l'origine dati restituisce il nuovo hash del valore DataTable e il nuovo valore di sig.
    • Se i dati non sono stati modificati rispetto alla richiesta precedente, l'origine dati restituisce status=error, reason=not_modified, sig=old_sig_value.
  5. In entrambi i casi, la pagina che ospita il grafico riceve una risposta corretta e può recuperare DataTable chiamando QueryResponse.getDataTable(). Se i dati sono gli stessi, si tratta semplicemente della versione memorizzata nella cache della tabella.

Tieni presente che questo funziona solo per le richieste JSON dai grafici creati nell'API Google Visualization.

Formato di risposta CSV

Se la richiesta specifica out:csv, la risposta non include metadati, ma semplicemente una rappresentazione CSV dei dati. Una tabella CSV è in genere un elenco separato da virgole, in cui ogni riga di dati è un elenco di valori separati da virgole, che termina con un carattere di nuova riga UNIX (\n). I valori delle celle devono essere dello stesso tipo per ogni colonna. La prima riga contiene le etichette delle colonne. Ecco un esempio di tabella a tre righe e tre colonne:

A, B, C
1.0, "yes", true
2.0, "no", false
3.0, "maybe", true

Il formato CSV non è specificato da questo protocollo. L'origine dati è responsabile della definizione del proprio formato CSV. Tuttavia, un formato comune è un insieme di valori separati da virgole (senza spazi) e una nuova riga (\n) alla fine di ogni riga. Quando un browser riceve una risposta alla stringa CSV, potrebbe chiedere all'utente quale applicazione utilizzare per aprire la stringa o semplicemente visualizzarla sullo schermo. Le librerie open source Java e Python forniscono un metodo per convertire una tabella di dati in una stringa CSV.

Se la richiesta include un membro outFileName del parametro tqx , devi provare a includere il nome del file specificato nelle intestazioni della risposta.

L'oggetto google.visualization.Query non supporta una richiesta di risposta CSV. Se un cliente vuole richiedere un file CSV, puoi incorporare nella tua pagina un widget della barra degli strumenti di visualizzazione o utilizzare un codice personalizzato per creare la richiesta oppure puoi fornire un link che imposti esplicitamente la proprietà out:csv di tqx, come mostrato nel seguente URL di richiesta:

Richiedi

http://www.example.com/mydatasource?tqx=reqId:1;out:csv

Risposta

Label 1,Label2\n1,a\n2,b\n3,c\n4,d

Formato di risposta del TSV

Se la richiesta specifica out:tsv-excel, la risposta non include metadati, ma semplicemente una rappresentazione dei dati separata da tabulazioni, codificata in utf-16. Se la richiesta include un membro outFileName del parametro tqx , devi provare a includere il nome del file specificato nelle intestazioni della risposta.

Formato di risposta HTML

Se la richiesta specifica out:html, la risposta deve essere una pagina HTML che definisce una tabella HTML con i dati. Questo è utile per eseguire il debug del codice, perché il browser può visualizzare direttamente il risultato in un formato leggibile. Non puoi inviare una query per una risposta HTML utilizzando l'oggetto google.visualization.Query. Devi creare una query per una risposta HTML utilizzando un codice personalizzato oppure digitando nel browser un URL simile a questo:

Richiedi

http://www.example.com/mydatasource?tqx=reqId:1;out:html

Risposta

<html><body><table border='1' cellpadding='2' cellspacing='0'><tr style='font-weight: bold; background-color: #aaa;'><td>label 1</td><td>label 2</td></tr><tr bgcolor='#f0f0f0'><td align='right'>1</td><td>a</td></tr><tr bgcolor='#ffffff'><td align='right'>2</td><td>b</td></tr><tr bgcolor='#f0f0f0'><td align='right'>3</td><td>c</td></tr><tr bgcolor='#ffffff'><td align='right'>4</td><td>d</td></tr></table></body></html>

Esempi

Ecco alcuni esempi di richieste e risposte. Tieni presente che le richieste non presentano caratteri di escape nell'URL; in genere questa operazione viene eseguita dal browser o dall'oggetto google.visualization.Query.

Richiesta semplice: restituisce le informazioni di base con una tabella con tre colonne e quattro righe.

Request:
http://www.example.com/mydatasource

Response
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'5982206968295329967',table:{cols:[{id:'Col1',label:'',type:'number'},{id:'Col2',label:'',type:'number'},{id:'Col3',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]},{c:[{v:2.0,f:'2'},{v:3.0,f:'3'},{v:4.0,f:'4'}]},{c:[{v:3.0,f:'3'},{v:4.0,f:'4'},{v:5.0,f:'5'}]},{c:[{v:1.0,f:'1'},{v:2.0,f:'2'},{v:3.0,f:'3'}]}]}});

Richiesta semplice con un gestore di risposte: restituisce una tabella a tre colonne e tre righe con tipi di dati diversi.

Request:
http://www.example.com/mydatasource?tqx=responseHandler:myHandlerFunction

Response
myHandlerFunction({version:'0.6',reqId:'0',status:'ok',sig:'4641982796834063168',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]},{c:[{v:'b'},{v:2.0,f:'2'},{v:new Date(2008,2,30,0,31,26),f:'3/30/08 12:31 AM'}]},{c:[{v:'c'},{v:3.0,f:'3'},{v:new Date(2008,3,30,0,31,26),f:'4/30/08 12:31 AM'}]}]}});

Query con una semplice stringa di query: la richiesta di una singola colonna restituisce una singola colonna con quattro righe.

Request:
http://www.example.com/mydatasource?tq=select Col1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'ok',sig:'6099996038638149313',table:{cols:[{id:'Col1',label:'',type:'number'}],rows:[{c:[{v:1.0,f:'1'}]},{c:[{v:2.0,f:'2'}]},{c:[{v:3.0,f:'3'}]},{c:[{v:1.0,f:'1'}]}]}});

Errore relativo ai dati non modificati: esempio di errore not_modified.

Request:
http://www.example.com/mydatasource?tqx=reqId:0;sig:4641982796834063168

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'not_modified',message:'Data not modified'}]});

Avviso di troncamento dei dati:esempio di avviso data_truncated. Nota che la richiesta restituisce ancora dati.

Request:
http://www.example.com/mydatasource?tq=limit 1

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'warning',warnings:[{reason:'data_truncated',message:'Retrieved data was truncated'}],sig:'1928724788649668508',table:{cols:[{id:'A',label:'NEW A',type:'string'},{id:'B',label:'B-label',type:'number'},{id:'C',label:'C-label',type:'datetime'}],rows:[{c:[{v:'a'},{v:1.0,f:'1'},{v:new Date(2008,1,28,0,31,26),f:'2/28/08 12:31 AM'}]}]}});

Errore di accesso negato:esempio di errore access_denied.

Request:
http://www.example.com/mydatasource

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'access_denied',message:'Access denied',detailed_message:'Access Denied'}]});

Stringa di query non valida:esempio di richiesta con una stringa di query non valida. Tieni presente che il messaggio dettagliato è un messaggio generico, anziché il messaggio di errore effettivo.

Request:
http://www.example.com/mydatasource?tq=select A

Response:
google.visualization.Query.setResponse({version:'0.6',reqId:'0',status:'error',errors:[{reason:'invalid_query',message:'Invalid query',detailed_message:'Bad query string.'}]});

Strumenti di sviluppo

  • Java Datasource Library (di Google): gestisce la richiesta e la risposta, crea la tabella di risposta in base ai dati che le fornisci e implementa il linguaggio di query SQL di Google Chart Tools.
  • Libreria Datasource Python (di Google): crea una tabella di risposta che genera la sintassi della risposta. Non gestisce l'analisi della richiesta o l'implementazione del linguaggio di query SQL di Google Chart Tools.
  • MC-Google_Visualization (di terze parti): si tratta di una libreria lato server PHP che puoi utilizzare per implementare un'origine dati Chart Tools Datasource per i motori di database MySQL, SQLite e PostgreSQL utilizzando PDO.
  • bortosky-google-visualization (di terze parti): questa è una libreria di supporto per creare una tabella dati dell'API Google Visualization per gli utenti .NET.
  • GV Streamer (di terze parti): GV Streamer è uno strumento lato server che può convertire i dati provenienti da diverse origini in risposte a query valide nei grafici di Google. GV Streamer supporta diversi linguaggi (ad esempio PHP, Java, .NET) e diverse origini dati non elaborate (ad esempio MySql).
  • TracGViz (Di terze parti): TracGViz è uno strumento open source senza costi che fornisce componenti in modo che Trac possa utilizzare i gadget dei grafici e implementare i dati gestiti da Trac come origine dati di Google Chart Tools.
  • vis-table (di terze parti) - Una libreria che implementa un'origine dati di Google Chart Tools in PHP. È composta da tre parti principali. L'implementazione della tabella dati stessa, l'analizzatore sintattico del linguaggio di query e i formatter.
  • Implementazione di Google Datasource in Oracle PL/SQL (di terze parti): - Un pacchetto Oracle PL/SQL che consente a Oracle di eseguire il server delle origini dati direttamente dal database. In sostanza, puoi utilizzare qualsiasi query Oracle come origine dati di Google Chart Tools (il pacchetto restituirà un file JSON con i dati). Supporta quasi completamente il linguaggio di query di Google.