Implementa il protocollo dell'origine dati degli strumenti per i grafici (V0.6)

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

Contenuti

Pubblico

Questa pagina è rivolta principalmente agli sviluppatori che creano la propria origine dati senza l'aiuto della libreria delle origini dati di Grafici. Se utilizzi quella o altre librerie di supporto, leggi prima la documentazione della libreria.

Questa pagina è destinata anche ai lettori interessati a comprendere il protocollo via cavo utilizzato per la comunicazione tra una visualizzazione client e un'origine dati.

Se crei o utilizzi una visualizzazione, non è necessario leggere questa pagina.

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

Nota: Google non approva né supporta ufficialmente nessuna origine dati non Google che supporti il protocollo dell'origine dati di Chart Tools.

Panoramica

Puoi implementare il protocollo dell'origine dati di Chart Tools per diventare un fornitore di origini dati per i tuoi grafici o per altri grafici. Un'origine dati degli strumenti di grafico espone un URL, chiamato URL dell'origine dati, a cui un grafico può inviare richieste GET HTTP. Di conseguenza, l'origine dati restituisce dati formattati correttamente che il grafico può utilizzare per visualizzare l'immagine nella pagina. Questo protocollo di richiesta-risposta è noto come protocollo bancario del componente API di visualizzazione Google.

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 una tabella bidimensionale con colonne digitate.

Come origine dati degli strumenti del grafico, devi analizzare una richiesta in un formato specifico e restituire una risposta in un formato specifico. Puoi farlo in due modi:

  • Utilizza una delle seguenti librerie di supporto per gestire la richiesta e la risposta, quindi costruisci la DataTable per restituirla. Se utilizzi una di queste librerie, devi scrivere solo il codice necessario per rendere disponibili i dati alla libreria sotto forma di tabella.
  • Scrivi la tua origine dati da zero gestendo la richiesta, costruendo una DataTable e inviando la risposta.

Come funziona:

  1. L'origine dati espone un URL, chiamato URL origine dati, a cui i grafici inviano una richiesta HTTP GET.
  2. Il client effettua una richiesta GET HTTP con i 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 delle risposte sono illustrati nella sezione Formato della risposta. Origine dati può supportare facoltativamente il linguaggio di query dell'API di visualizzazione, che specifica filtri, ordinamento e altra manipolazione 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 costanti di stringa elencati in questo documento per le richieste e le risposte (come responseHandler e "ok") sono in lettere minuscole e sono sensibili alle maiuscole.

Requisiti minimi

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

  • L'origine dati deve accettare le richieste GET HTTP e deve essere disponibile per i client.
  • Il protocollo può modificare e supporta uno schema di versioni (la versione corrente è 0.6), pertanto l'origine dati deve supportare le richieste sia con la versione precedente sia con la versione corrente. Dovresti provare a supportare le nuove versioni non appena vengono rilasciate per evitare di danneggiare rapidamente i client che eseguono l'upgrade alla versione più recente.
  • Da non perdere se le proprietà sconosciute vengono inviate nell'ambito della richiesta. perché le nuove versioni possono introdurre nuove proprietà di cui non siete a conoscenza.
  • Analizza solo le proprietà che ti aspetti. Anche se le nuove versioni potrebbero introdurre nuove proprietà, non accettare alla cieca e utilizzare l'intera stringa di richiesta. Per proteggerti da attacchi dannosi, analizza e usa con attenzione solo le proprietà che ti aspetti.
  • Documenta attentamente i requisiti dell'origine dati se non stai programmare personalmente i grafici client. Ciò include la documentazione delle seguenti informazioni:
    • Eventuali parametri personalizzati accettati
    • Consente di indicare se puoi analizzare o meno il linguaggio delle query dell'API Google Optimization e
    • 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 parametri per autenticare le richieste o contribuire a proteggerti da attacchi dannosi e aspettarti che i client siano a conoscenza dei tuoi requisiti e che rispondano a tali requisiti. Tuttavia, se non hai eseguito personalmente la programmazione dei grafici, assicurati di documentare bene tutti i tuoi requisiti. Vedi Considerazioni sulla sicurezza di seguito.
  • Tutte le stringhe di richiesta e risposta devono essere codificate in UTF-8.
  • Il formato di risposta più importante è JSON. Innanzitutto, assicurati di implementare JSON, dato che è il formato utilizzato dalla maggior parte dei grafici. Aggiungi altri tipi di risposte in un secondo momento.
  • Non è obbligatorio supportare il linguaggio di query dell'API di visualizzazione, ma l'origine dati risulta più utile per i clienti.
  • Non è obbligatorio per supportare le richieste di tutti i tipi di grafici e puoi supportare i parametri personalizzati per i grafici personalizzati. Tuttavia, dovresti restituire le risposte nel formato standard descritto di seguito.

Considerazioni sulla sicurezza

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

Gli attacchi di tipo XSSI (cross-site script) sono a rischio nei grafici. Un utente potrebbe raggiungere una pagina contenente uno script dannoso che inizierà a tentare di eseguire query agli 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 attuale e avrà le autorizzazioni su quel sito. L'utilizzo di un tag <script src> allo script dannoso può includere l'origine dati in modo analogo a JSONP.

Come ulteriore livello di sicurezza, potresti prendere in considerazione la possibilità di limitare le richieste a chi proviene dallo stesso dominio della tua origine dati. Questo limiterà notevolmente la visibilità dell'origine dati, ma se avete dati molto sensibili a cui non è necessario accedere dall'esterno del dominio, dovete valutarli. Un'origine dati che consente solo le richieste dallo stesso dominio è denominata origine dati limitata, anziché origine dati senza restrizioni, che accetta query da qualsiasi dominio. Di seguito sono riportati alcuni dettagli su come implementare un'origine dati limitata:

Per assicurarti che una richiesta provenga effettivamente dal tuo dominio e non da un dominio esterno (o da un browser all'interno del dominio soggetto ad attacco XSRF):

  • Verifica la presenza di un'intestazione "X-DataSource-Auth" nella richiesta. Questa intestazione è definita dall'API di visualizzazione Google; non è necessario esaminare i contenuti di questa intestazione, ma solo che è presente. Se utilizzi la libreria degli strumenti di origine di Google Chart Tools, puoi fare in modo che sia la libreria a gestirla per te.
  • Utilizza l'autenticazione cookie per autenticare il client. Non esiste un modo noto per inserire intestazioni personalizzate in una richiesta interdominio, mantenendo al contempo i cookie di autenticazione.
  • Fai in modo che JavaScript non venga eseguito quando è incluso con un tag <script src>. Per farlo, aggiungi il prefisso )]}" seguito da una nuova riga. Nel client rimuovi il prefisso dalla risposta. Per XmlHttpRequest è possibile solo quando la richiesta proviene dallo stesso dominio.

Formato della richiesta

Un client invia una richiesta GET HTTP con diversi parametri, tra cui elementi personalizzati, una stringa di query facoltativa, la firma e altri elementi. È tua esclusiva responsabilità analizzare i parametri descritti in questa sezione e devi fare attenzione a non gestirli per evitare attacchi dannosi.

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

Di seguito sono riportati alcuni esempi di richieste (puoi vedere altri esempi di richieste e risposte alla fine di questo documento in Esempi):

Nota: le seguenti stringhe di richiesta e quelle mostrate nella sezione Esempi devono essere precedute dal carattere 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 della richiesta. Tieni presente che sia i nomi dei parametri (come "version") sia i valori delle stringhe costanti (come "ok", "warning" e "not_modified") sono sensibili alle maiuscole. La tabella descrive anche se il parametro deve essere inviato e, se necessario, se deve essere gestito.

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

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

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

tqx
No

Un insieme di coppie chiave/valore delimitate da due punti per i parametri standard o personalizzati. Le coppie sono separate da punto e virgola. Ecco 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. Questo viene utilizzato in modo che se un client invia più richieste prima di ricevere una risposta, l'origine dati può identificare la risposta con la richiesta corretta. Invia questo valore nella risposta.
  • version - [Facoltativo nella richiesta; l'origine dati deve gestire] il numero di versione del protocollo di visualizzazione Google. La versione corrente è 0.6. Se non viene inviata, scegli la versione più recente.
  • sig - [Facoltativo nella richiesta; Facoltativo per la gestione dell'origine dati] Un hash del DataTable inviato a questo client in qualsiasi richiesta precedente a questa origine dati. Si tratta di un'ottimizzazione per evitare di inviare due volte dati identici a un client. Per informazioni su come utilizzare questa funzionalità, consulta la sezione Ottimizzare la richiesta di seguito.
  • out - [Facoltativo nella richiesta; l'origine dati deve gestire] Una stringa che descrive il formato dei dati restituiti. Può essere uno dei seguenti valori:
    • json - [Default value] Una stringa di risposta JSON (descritta di seguito).
    • html: una tabella HTML di base con righe e colonne. Se viene utilizzata, l'unica cosa da restituire è una tabella HTML con i dati; questa operazione è utile per il debug, come descritto nella sezione Formato della risposta di seguito.
    • csv: valori separati da virgole. Se viene utilizzato, l'unico elemento restituito è 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 utilizzando le schede anziché le virgole e tutti i dati sono codificati in utf-16.
    Tieni presente che l'unico tipo di dati richiesto da un grafico basato sull'API di visualizzazione Google è JSON. Consulta la sezione Formato di risposta di seguito per i dettagli su ciascun tipo.
  • responseHandler - [Facoltativo nella richiesta; l'origine dati deve gestire] Il nome della stringa della funzione di gestione di JavaScript nella pagina client che verrà richiamato con la risposta. Se non incluso nella richiesta, il valore è "google.visualization.Query.setResponse". Verrà restituito come parte della risposta; consulta la sezione Formato della risposta di seguito per scoprire come.
  • outFileName - [Facoltativo nella richiesta; Facoltativo per l'origine dati da gestire] Se specifichi out:csv o out:tsv-excel, puoi facoltativamente richiedere il nome del 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. Consulta le sezioni seguenti per scoprire come rispondere a ogni tipo di richiesta:

  • JSON: restituisce una risposta JSON che include i dati in un oggetto JavaScript che possono essere passati direttamente in un costruttore DataTable per completarli. Questo è di gran lunga il tipo di richiesta più comune e più importante da implementare correttamente.
  • CSV: restituisce un elenco di valori separati da virgole che devono essere gestiti dal browser.
  • TSV: restituisce un elenco di valori separati da tabulazioni, che devono essere gestiti dal browser.
  • HTML: restituisce una tabella HTML da visualizzare nel browser.

Puoi utilizzare la libreria delle origini dati di visualizzazione Google (java) o la libreria Python di visualizzazione per generare automaticamente questi formati di output.

Formato di risposta JSON

Il formato di risposta predefinito è JSON se la richiesta include un'intestazione "X-DataSource-Auth" e JSONP in caso contrario. Tieni presente che il client del grafico di Google supporta effettivamente una versione modificata di JSON e JSONP; se utilizzi le librerie di supporto Java o Python, ti verranno forniti il codice corretto. Se stai analizzando le risposte manualmente, consulta la sezione Modifiche JSON di seguito.

Se stai applicando richieste dello 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 Preview google.visualization.Query.send() . Puoi trovare alcune richieste e risposte JSON di esempio alla fine di questa pagina in Esempi. Puoi utilizzare le librerie di supporto Java o Python per creare automaticamente questa stringa di risposta.

Questo formato di risposta è un oggetto JSON codificato in UTF-8 (un oggetto racchiuso 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 inserito all'interno del valore del parametro responseHandler dalla richiesta. Pertanto, se il valore responseHandler della richiesta era "myHandler", dovresti restituire una stringa simile alla seguente (per una brevità viene mostrata solo una proprietà):

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

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

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

Ecco i membri disponibili per l'oggetto di risposta:

Proprietà
Obbligatoria?
Descrizione
versione
No

Un numero di stringa che fornisce il numero di versione del protocollo di visualizzazione di Google. Se non specificato, il client presuppone la versione più recente.

Esempio: version=0.6

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

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

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

  • ok: richiesta andata a buon fine. 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 compito, non devi restituire table e devi restituire errors.

Esempio: status:'warning'

avvisi
Solo se status=warning

Un array di uno o più oggetti, ognuno che descrive un problema non irreversibile. Obbligatorio se status=warning non è consentito in caso contrario. Ogni oggetto ha le seguenti proprietà stringa (restituisce un solo valore per ogni proprietà):

  • reason - [Obbligatorio] Una descrizione di una parola della stringa 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 - È stata rimossa DataTable alcune righe rimosse, perché l'utente ha incluso una stringa di query che ha tagliato l'elenco dei risultati oppure perché per qualche motivo l'origine dati non voleva restituire risultati completi.
    • other: un avviso generico non specificato.
  • message - [Facoltativo] Breve stringa tra virgolette che spiega il problema, eventualmente utilizzata come titolo per una casella di avviso. Questo potrebbe essere mostrato all'utente. Il codice HTML non è supportato.
  • detailed_message - [Facoltativo] Un messaggio stringa dettagliato con descrizione del problema ed eventuali soluzioni. L'unico codice HTML supportato è l'elemento <a> con un singolo attributo href. La codifica Unicode è supportata. 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 in altro modo. È simile al valore warnings. Tieni presente che l'errore not_modified, anche se non è un errore per il client.

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

  • reason - [Obbligatorio] Come warnings.reason, vengono definiti i seguenti valori:
    • not_modified: i dati non sono cambiati dall'ultima richiesta. Se è questo il motivo dell'errore, non devi 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à quindi 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 utilizzare una stringa di dati dettagliata come mezzo per accedere a dati non autorizzati o persino per attaccare i tuoi dati o il tuo sito. Se memorizzi dati che devono essere sicuri o elabora direttamente le query degli utenti, valuta la possibilità di non restituire un messaggio di errore dettagliato che potrebbe fornire informazioni a un utente malintenzionato; usa piuttosto un messaggio generico, ad esempio "Stringa di query errata".
  • detailed_message - [Facoltativo] Come warnings.detailed_message. Consulta l'avviso per informazioni message troppo dettagliate.

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 l'algoritmo hash che preferisci. Se supporti questa proprietà, devi restituire il valore trasmesso dal client se non vengono restituiti dati oppure restituire un nuovo hash se vengono restituiti nuovi dati.

Esempio: sig:'5982206968295329967'

tabella
No

Un oggetto DataTable in notazione letterale JavaScript con i tuoi dati. Consulta la sezione dei riferimenti collegati per i dettagli sul formato di questo oggetto. Ecco un esempio di una semplice tabella di dati:

{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 stringa vuoto.

Esempio:vedi Esempi di seguito.

 

È necessario un JSON rigoroso

Le librerie di supporto di Google e tutte le query inviate a Google restituiscono un JSON/JSONP rigoroso. Se non stai analizzando il codice restituito, questo non deve essere pertinente. In questo caso, 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 di data JavaScript (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 è facoltativo e i mesi sono basati su zero.

 

Ottimizzazione delle risposte JSON

Se un client effettua due richieste e i dati non sono cambiati tra le richieste, ha senso non inviare di nuovo i dati, altrimenti si perderebbe la 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 segnale nella risposta se i dati non sono cambiati dall'ultima richiesta. Ecco come fare i calcoli:

  1. Il client invia una richiesta all'origine dati.
  2. L'origine dati genera sia un DataTable sia un hash dell'oggetto DataTable e restituisce entrambi nella risposta (l'hash viene restituito nel parametro tqx.sig). Il client API Visualizzazione Google 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 di questi due modi:
    • Se i dati sono cambiati rispetto alla richiesta precedente, l'origine dati restituisce il nuovo hash del valore DataTable e quello nuovo di sig.
    • Se i dati non sono cambiati 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, sarà semplicemente la versione memorizzata nella cache della tabella.

Tieni presente che questo funziona solo per le richieste JSON dai grafici creati sull'API di visualizzazione Google.

Formato di risposta CSV

Se la richiesta specifica out:csv, la risposta non include metadati, ma semplicemente una rappresentazione CSV dei dati. In genere, una tabella CSV è un elenco separato da virgole, dove ogni riga di dati è un elenco di valori separato da virgole e termina con un carattere di nuova riga UNIX (\n). I valori delle celle devono avere lo 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; è responsabilità dell'origine dati definirne il formato CSV. Tuttavia, un formato comune è un insieme di valori separati da virgole (senza spazi intermedi) e da una nuova riga (\n) alla fine di ogni riga. Quando un browser riceve una risposta di stringa CSV, potrebbe chiedere all'utente quale applicazione utilizzare per aprire la stringa oppure mostrarla semplicemente sullo schermo. Le librerie open source Java e Python forniscono un metodo per convertire una DataTable in una stringa CSV.

Se la richiesta include un membro outFileName del parametro tqx , dovresti 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 un gadget Visualizzazione barra degli strumenti nella tua pagina oppure potresti utilizzare codice personalizzato per creare la richiesta oppure puoi fornire un link che imposta in modo esplicito 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 TSV

Se la richiesta specifica out:tsv-excel, la risposta non include i metadati, ma semplicemente una rappresentazione dei dati separata da tabulazioni, con utf-16 codificato. Se la richiesta include un membro outFileName del parametro tqx , dovresti 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 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 codice personalizzato o digitando un URL simile a questo nel browser:

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 hanno caratteri di escape, ossia in genere eseguite dal browser o dall'oggetto google.visualization.Query.

Richiesta semplice: restituisce le informazioni di base con una tabella di tre righe 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 delle risposte: restituisce una tabella di 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'}]}]}});

Esegui una query con una semplice stringa di query: la richiesta per 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 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 troncato dati: esempio di avviso data_truncated. Tieni presente che la richiesta restituisce comunque 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 una 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

  • Libreria Origine dati Java (di Google): gestisce la richiesta e la risposta, crea la tabella di risposta dai dati che gli fornisci e implementa il linguaggio di query SQL di Google Chart Tools.
  • Libreria origine dati Python (da Google): crea una tabella di risposta che genera la sintassi delle risposte. Non gestisce l'analisi della richiesta o l'implementazione del linguaggio SQL delle query di Google Chart Tools.
  • MC-Google_Visualization (di terze parti): questa è una libreria lato server PHP che puoi utilizzare per implementare un'origine dati degli strumenti di grafico per motori di database MySQL, SQLite e PostgreSQL utilizzando PDO.
  • bortosky-google-visualization (di terze parti): questa è una libreria di supporto per la creazione di una tabella dati dell'API di visualizzazione Google per gli utenti .NET.
  • Streamer GV (di terze parti): l'autore dello streaming GV è uno strumento lato server che può convertire i dati da diverse origini in risposte valide alle query su grafici 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 senza costi e open source che fornisce componenti in modo che Trac possa utilizzare i gadget dei grafici e implementare i dati gestiti da Trac come origine dell'origine dati di Google Chart Tools.
  • vis-table (di terze parti): una libreria che implementa un'origine dati di Google Chart Tools in PHP. Sono composte da tre elementi principali. L'implementazione della tabella di dati, l'analizzatore sintattico del linguaggio di query e i formati.
  • Implementazione delle origini dati Google in Oracle PL/SQL (di terze parti): un pacchetto PL/SQL Oracle che consente a Oracle di eseguire il server delle origini dati direttamente dal database. Fondamentalmente, puoi utilizzare qualsiasi query Oracle come origine dati di Google Chart Tools (il pacchetto restituirà un file JSON con i dati). Offre un supporto quasi completo per Google Query Language.