Implémenter le protocole de source de données Chart Tools (V0.6)

Cette page explique comment implémenter un service compatible avec le protocole de source de données Chart Tools afin d'exposer des données dans des graphiques à l'aide de la classe Query.

Sommaire

Audience

Cette page est principalement destinée aux développeurs qui créent leur propre source de données sans l'aide de la bibliothèque de sources de données de Chart Tools. Si vous utilisez cette bibliothèque ou toute autre bibliothèque d'aide, commencez par lire la documentation de votre bibliothèque.

Cette page s'adresse également aux lecteurs qui souhaitent comprendre le protocole de communication utilisé pour la communication entre une visualisation client et une source de données.

Si vous créez ou utilisez une visualisation, vous n'avez pas besoin de lire cette page.

Pour lire ce document, vous devez comprendre la syntaxe des requêtes de base JSON et HTTP. Vous devez également comprendre le fonctionnement des graphiques du point de vue de l'utilisateur.

Remarque : Google ne cautionne ni n'accepte officiellement aucune source de données non compatible avec le protocole de source de données Chart Tools.

Présentation

Vous pouvez mettre en œuvre le protocole de source de données Chart Tools afin de devenir un fournisseur de sources de données pour vos propres graphiques ou d'autres graphiques. Une source de données Chart Tools expose une URL, appelée URL de source de données, à laquelle un graphique peut envoyer des requêtes HTTP GET. En réponse, la source de données renvoie des données correctement formatées que le graphique peut utiliser pour afficher le graphique sur la page. Ce protocole de requête-réponse est appelé protocole filaire de l'API Google Visualization.

Les données diffusées par une source de données peuvent être extraites de diverses ressources, telles qu'un fichier ou une base de données. La seule restriction est que vous pouvez formater les données sous la forme d'une table bidimensionnelle avec des colonnes saisies.

En tant que source de données de graphique d'outils, vous devez analyser une requête dans un format spécifique et renvoyer une réponse dans un format spécifique. Vous pouvez procéder de deux manières:

  • Utilisez l'une des bibliothèques d'aide suivantes pour gérer la requête et la réponse, puis construisez la table DataTable à renvoyer. Si vous utilisez l'une de ces bibliothèques, il vous suffit d'écrire le code nécessaire pour mettre vos données à la disposition de la bibliothèque sous la forme d'une table.
  • Écrivez entièrement votre source de données en gérant la requête, en créant une table de données et en envoyant la réponse.

Fonctionnement :

  1. La source de données expose une URL, appelée URL de la source de données, vers laquelle les graphiques envoient une requête HTTP GET.
  2. Le client effectue une requête HTTP GET avec des paramètres décrivant le format à utiliser pour les données renvoyées, une chaîne de requête facultative et des paramètres personnalisés facultatifs.
  3. La source de données reçoit et analyse la requête, comme décrit dans la section Format de requête.
  4. La source de données prépare les données au format demandé. Il s'agit généralement d'une table JSON. Les formats de réponse sont traités dans la section Format de réponse. La source de données peut éventuellement accepter le langage de requête de l'API de visualisation qui spécifie le filtrage, le tri et d'autres manipulations de données.
  5. La source de données crée une réponse HTTP qui inclut les données sérialisées et d'autres paramètres de réponse, puis la renvoie au client comme décrit dans la section Format de réponse.

Remarque : Tous les paramètres et valeurs de constante de chaîne répertoriés dans ce document pour les requêtes et les réponses (telles que responseHandler et "ok") sont en minuscules et sensibles à la casse.

Configuration minimale requise

Voici les conditions minimales requises pour servir de source de données de graphique:

  • La source de données doit accepter les requêtes HTTP GET et être disponible pour vos clients.
  • Le protocole peut changer et est compatible avec un schéma de version (la version actuelle est 0.6). Votre source de données doit donc accepter les requêtes utilisant les versions précédentes et actuelles. Vous devez essayer de prendre en charge les nouvelles versions dès leur publication pour éviter de forcer les clients qui effectuent rapidement la mise à niveau vers la dernière version.
  • N'échouez pas si des propriétés inconnues sont envoyées dans le cadre de la requête. En effet, les nouvelles versions peuvent introduire de nouvelles propriétés que vous ne connaissez pas.
  • Analysez uniquement les propriétés attendues. Bien que de nouvelles versions puissent introduire de nouvelles propriétés, n'acceptez pas et n'utilisez pas la chaîne de requête dans son intégralité. Pour vous protéger contre les attaques malveillantes, analysez et utilisez uniquement les propriétés attendues.
  • Documentez soigneusement les exigences relatives à votre source de données si vous ne codez pas les graphiques clients vous-même. Cela inclut la documentation des informations suivantes :
    • Les paramètres personnalisés que vous acceptez,
    • L'analyse ou non du langage de requête de l'API Google Visualization
    • Le type de données que vous renvoyez et la structure de ces données (ce que les lignes et colonnes représentent, et tout étiquetage)
  • Prenez toutes les précautions de sécurité standards pour un site qui accepte les requêtes de clients inconnus. Vous pouvez raisonnablement accepter le protocole MD5, le hachage et d'autres mécanismes de sécurité dans vos paramètres afin d'authentifier les requêtes ou de vous protéger contre les attaques malveillantes, et de vous assurer que les clients sont au courant de vos exigences et y répondent. Toutefois, veillez à bien documenter toutes vos exigences si vous ne codez pas les graphiques vous-même. Consultez la section Considérations de sécurité ci-dessous.
  • Toutes les chaînes de requête et de réponse doivent être encodées au format UTF-8.
  • Le format de réponse le plus important est JSON. Assurez-vous d'abord d'implémenter le format JSON, car il s'agit du format utilisé par la plupart des graphiques. Ajoutez d'autres types de réponses ultérieurement.
  • Vous n'êtes pas obligatoire pour accepter le langage de requête de l'API de visualisation, mais il rend votre source de données plus utile pour les clients.
  • Vous n'êtes pas obligatoire pour accepter les requêtes de tous les types de graphiques, et vous pouvez accepter des paramètres personnalisés pour les graphiques personnalisés. Toutefois, vous devez renvoyer les réponses au format standard décrit ci-dessous.

Considérations de sécurité

Lorsque vous concevez votre source de données, vous devez évaluer le niveau de sécurité de vos données. Vous pouvez utiliser différents mécanismes de sécurité pour votre site, de l'accès simple à un mot de passe à l'authentification sécurisée des cookies.

Les attaques XSSI (inclusion de scripts intersites) représentent un risque avec les graphiques. Un utilisateur peut accéder à une page contenant un script malveillant qui tente ensuite d'envoyer des requêtes aux URL de la source de données à l'aide des identifiants de l'utilisateur actuel. Si l'utilisateur ne s'est pas déconnecté d'un site, le script sera authentifié en tant qu'utilisateur actuel et disposera d'autorisations sur ce site. À l'aide d'un tag <script src>, le script malveillant peut inclure la source de données, comme pour JSONP.

Pour renforcer la sécurité, vous pouvez envisager de limiter les requêtes à celles provenant du même domaine que votre source de données. Cela limitera considérablement la visibilité de votre source de données. Toutefois, si des données très sensibles ne doivent pas être accessibles depuis l'extérieur de votre domaine, nous vous conseillons de les prendre en compte. Une source de données qui n'autorise que les requêtes provenant du même domaine est appelée source de données restreinte, par opposition à une source de données sans restriction qui accepte les requêtes de n'importe quel domaine. Voici quelques informations sur la mise en œuvre d'une source de données restreinte:

Pour vous assurer qu'une requête provient bien de votre domaine et non d'un domaine extérieur (ou d'un navigateur interne au domaine soumis à une attaque XSRF), procédez comme suit :

  • Vérifiez la présence de l'en-tête "X-DataSource-Auth" dans la requête. Cet en-tête est défini par l'API Google Visualization. Vous n'avez pas besoin d'en examiner le contenu, mais seulement de vérifier qu'il est présent. Si vous utilisez la bibliothèque de sources de données des outils de graphique Google, laissez-la s'en charger pour vous.
  • Utilisez l'authentification par cookie pour authentifier le client. Il n'existe aucun moyen connu d'injecter des en-têtes personnalisés dans une requête interdomaine tout en conservant les cookies d'authentification.
  • Rendre le code JavaScript peu susceptible de s'exécuter lorsqu'il est inclus avec une balise <script src> Pour cela, ajoutez le préfixe ")]}", suivi d'un saut de ligne. Dans votre client, supprimez le préfixe de la réponse. Pour XmlHttpRequest, cela n'est possible que lorsque la requête provient du même domaine.

Format de demande

Un client envoie une requête HTTP GET avec plusieurs paramètres, y compris des éléments personnalisés, une chaîne de requête facultative, une signature et d'autres éléments. Vous êtes seulement responsable de l'analyse des paramètres décrits dans cette section, et veillez à ne pas gérer d'autres utilisateurs afin d'éviter les attaques malveillantes.

Assurez-vous d'avoir des valeurs par défaut pour les paramètres facultatifs (standards et personnalisés), et documentez toutes les valeurs par défaut dans la documentation de votre site.

Voici quelques exemples de requêtes (voir Exemples à la fin de ce document):

Remarque: Les chaînes de requête suivantes, ainsi que celles présentées dans la section Exemples, doivent être précédées d'un caractère d'échappement avant l'envoi.

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

Voici la liste de tous les paramètres standards de la chaîne de requête. Notez que les noms des paramètres (tels que "version") et les valeurs de chaîne constantes (telles que "ok", "warning" et "not_modified) sont sensibles à la casse. Le tableau indique également si le paramètre doit être envoyé et, le cas échéant, si vous devez le gérer.

Paramètre
Obligatoire dans le champ "Demande" ?
La source de données doit-elle traiter ?
Description
tq
Non
Non

Requête écrite en langage de requête de l'API Google Visualization, qui spécifie comment filtrer, trier ou manipuler les données renvoyées. Il n'est pas nécessaire de mettre la chaîne entre guillemets.

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

tqx
Non
Oui

Ensemble de paires clé/valeur séparées par des deux-points pour les paramètres standards ou personnalisés. Les paires sont séparées par des points-virgules. Voici la liste des paramètres standards définis par le protocole de visualisation:

  • reqId : [obligatoire dans la requête. La source de données doit gérer] Un identifiant numérique pour cette requête. Ainsi, si un client envoie plusieurs requêtes avant de recevoir une réponse, la source de données peut identifier la réponse avec la requête appropriée. Renvoyez cette valeur dans la réponse.
  • version - [Optional in request; Data source must handle] : numéro de version du protocole de visualisation Google. La version actuelle est 0.6. Si vous ne l'envoyez pas, supposons que vous ayez installé la dernière version.
  • sig : [facultatif dans la requête ; facultatif pour la source de données à gérer] Hachage de DataTable envoyé à ce client dans toutes les requêtes précédentes adressées à cette source de données. Il s'agit d'une optimisation pour éviter d'envoyer deux fois des données identiques à un client. Consultez la section Optimiser votre requête ci-dessous pour savoir comment l'utiliser.
  • out : [facultatif dans la requête ; la source de données doit gérer] une chaîne décrivant le format des données renvoyées. Il peut s'agir de l'une des valeurs suivantes :
    • json - [Valeur par défaut] Chaîne de réponse JSON (décrite ci-dessous).
    • html : table HTML de base comportant des lignes et des colonnes. Si vous utilisez cette méthode, la seule chose à renvoyer est une table HTML contenant les données. C'est utile pour le débogage, comme décrit dans la section Format de réponse ci-dessous.
    • csv : valeurs séparées par une virgule. Si cette option est utilisée, la seule chose renvoyée est une chaîne de données CSV. Vous pouvez demander un nom personnalisé pour le fichier dans les en-têtes de réponse en spécifiant un paramètre outFileName.
    • tsv-excel : semblable à csv, mais utilise des tabulations au lieu de virgules, et toutes les données sont encodées en utf-16.
    Notez que le seul type de données qu'un graphique créé sur l'API Google Visualization demandera sera JSON. Pour en savoir plus sur chaque type, consultez la section Format des réponses ci-dessous.
  • responseHandler - [Facultatif dans la requête ; la source de données doit gérer] Nom de chaîne de la fonction de gestion JavaScript sur la page client qui sera appelée avec la réponse. Si elle n'est pas incluse dans la requête, la valeur est "google.visualization.Query.setResponse". Il sera renvoyé dans le cadre de la réponse. Pour en savoir plus, consultez la section Format de réponse ci-dessous.
  • outFileName - [Facultatif dans la requête ; facultatif pour la source de données à gérer] Si vous spécifiez out:csv ou out:tsv-excel, vous pouvez éventuellement demander le nom de fichier spécifié ici. Exemple:outFileName=results.csv.

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

tqrt
Non
Non

Réservé: ignorez ce paramètre. Méthode utilisée pour envoyer la requête.

Format de réponse

Le format de la réponse dépend du paramètre out de la requête, qui spécifie le type de réponse attendu. Consultez les sections suivantes pour savoir comment répondre à chaque type de requête:

  • JSON : renvoie une réponse JSON qui inclut les données d'un objet JavaScript qui peuvent être transmises directement à un constructeur DataTable pour les insérer. Il s'agit du type de demande de loin le plus courant et le plus important à mettre en œuvre correctement.
  • CSV : renvoie une liste plate de valeurs séparées par une virgule, qui doit être gérée par le navigateur.
  • TSV : renvoie une liste de valeurs séparées par des tabulations, qui doit être gérée par le navigateur.
  • HTML : renvoie une table HTML à afficher par le navigateur.

Vous pouvez utiliser la bibliothèque de sources de données de visualisation Google (java) ou la bibliothèque Python de visualisation pour générer ces formats de sortie.

Format de réponse JSON

Le format de réponse par défaut est JSON si la requête inclut un en-tête "X-DataSource-Auth", et dans le cas contraire, JSONP. Notez que le client de graphique Google est en réalité compatible avec une version modifiée des formats JSON et JSONP. Si vous utilisez les bibliothèques d'aide Java ou Python, celles-ci afficheront le code approprié. Si vous analysez les réponses manuellement, consultez Modifications JSON ci-dessous.

Si vous appliquez des requêtes sur le même domaine, vous devez vérifier la présence de l'en-tête "X-DataSource-Auth" dans la requête et utiliser des cookies d'autorisation.

Il s'agit du seul format de réponse spécifié par la méthode API Google Visualization google.visualization.Query.send(). Vous trouverez des exemples de requêtes et de réponses JSON au bas de cette page sur la page Exemples. Vous pouvez utiliser les bibliothèques d'aide Java ou Python pour créer cette chaîne de réponse à votre place.

Ce format de réponse est un objet JSON encodé au format UTF-8 (un objet entouré d'accolades : { } avec chaque propriété séparée par une virgule). Cette valeur inclut les propriétés du tableau ci-dessous (les données sont attribuées à la propriété table). Cet objet JSON doit être encapsulé dans la valeur du paramètre responseHandler de la requête. Ainsi, si la valeur responseHandler de la requête était "myHandler", vous devez renvoyer une chaîne semblable à celle-ci (une seule propriété affichée par souci de concision):

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

Si la requête n'inclut pas de valeur responseHandler, la valeur par défaut est "google.visualization.Query.setResponse". Vous devez donc renvoyer une chaîne comme celle-ci (une seule propriété affichée par souci de concision):

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

Voici les membres d'objet de réponse disponibles:

Propriété
Obligatoire ?
Description
version
Non

Numéro de chaîne indiquant le numéro de version du protocole filaire de la visualisation Google. S'il n'est pas spécifié, le client suppose la dernière version.

Exemple : version=0.6

ID de requête
Oui*
Numéro de chaîne indiquant l'ID de cette requête pour ce client. S'il s'agissait de la requête, renvoyez la même valeur. Pour en savoir plus, consultez la description de reqId dans la section dédiée aux requêtes.

* Si ce paramètre n'a pas été spécifié dans la requête, vous n'avez pas besoin de le définir dans la réponse.
état
Oui

Chaîne décrivant le succès ou l'échec de cette opération. Doit être l'une des seules valeurs suivantes:

  • ok : requête réussie. Une table doit être incluse dans la propriété table.
  • warning - Opération réussie, mais avec des problèmes. Une table doit être incluse dans la propriété table.
  • error : un problème est survenu. Si vous renvoyez ce résultat, vous ne devez pas renvoyer table et renvoyer errors.

Exemple : status:'warning'

 avertissements
Seulement si status=warning

Tableau d'un ou de plusieurs objets, chacun décrivant un problème non fatal. Obligatoire si status=warning, non autorisé dans le cas contraire. Chaque objet possède les propriétés de chaîne suivantes (une seule valeur est renvoyée pour chaque propriété):

  • reason : [obligatoire] : chaîne de description composée d'un mot de l'avertissement. Le protocole définit les valeurs suivantes, mais vous pouvez définir vos propres valeurs si vous le souhaitez (cependant, le client ne traite pas les valeurs personnalisées de quelque manière que ce soit). Vous ne pouvez avoir qu'une seule valeur reason :
    • data_truncated : des lignes ont été supprimées du DataTable renvoyé, soit parce que l'utilisateur a inclus une chaîne de requête qui a raccourci la liste des résultats, soit parce que la source de données ne souhaitait pas renvoyer de résultats complets pour une raison quelconque.
    • other : avertissement générique non spécifié.
  • message : [facultatif] chaîne courte entre guillemets décrivant le problème, éventuellement utilisée comme titre pour une zone d'alerte. L'utilisateur peut voir ces informations. Le code HTML n'est pas accepté.
  • detailed_message : [facultatif] message de chaîne détaillé entre guillemets expliquant le problème et les solutions possibles. Le seul code HTML accepté est l'élément <a> avec un seul attribut href. L'encodage Unicode est compatible. L'utilisateur peut voir ces informations.

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

erreurs
Obligatoire si status=error

Tableau d'un ou de plusieurs objets, chacun décrivant une erreur. Obligatoire si status=error, sinon autorisé. Cette valeur est semblable à la valeur warnings. Notez que l'erreur not_modified, bien qu'elle ne soit pas une erreur pour le client.

Le tableau contient les membres de chaîne suivants (une seule valeur est renvoyée pour chaque membre):

  • reason - [Obligatoire] Identique à warnings.reason, mais les valeurs suivantes sont définies :
    • not_modified : les données n'ont pas été modifiées depuis la dernière requête. Si c'est la raison de l'erreur, vous ne devez pas avoir de valeur pour table.
    • user_not_authenticated : si la source de données nécessite une authentification et que ce n'est pas le cas, spécifiez cette valeur. Le client affiche ensuite une alerte avec la valeur message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other : erreur générique non spécifiée.
  • message - [Facultatif] Identique à warnings.message. Remarque : Il est possible qu'un utilisateur malveillant utilise une chaîne de données détaillée pour accéder à des données non autorisées, ou même pour attaquer vos données ou votre site. Si vous stockez des données qui doivent être sécurisées ou que vous traitez directement les requêtes des utilisateurs, n'envisagez pas de renvoyer un message d'erreur détaillé pouvant fournir des informations à un pirate informatique. Fournissez plutôt un message générique, tel que "Chaîne de requête incorrecte".
  • detailed_message - [Facultatif] Identique à warnings.detailed_message. Consultez l'avertissement pour obtenir des informations message trop détaillées.

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

Sig
Non

Valeur hachée de l'objet de table. Utile pour optimiser le transfert de données entre le client et la source de données. Vous pouvez choisir n'importe quel algorithme de hachage. Si cette propriété est acceptée, vous devez renvoyer la valeur transmise par le client si aucune donnée n'est renvoyée, ou renvoyer un nouveau hachage si de nouvelles données sont renvoyées.

Exemple : sig:'5982206968295329967'

table
Non

Un objet DataTable en notation littérale JavaScript, avec vos données. Consultez la section de référence liée pour en savoir plus sur le format de cet objet. Voici un exemple de table de données simple:

{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 propriété table ne doit être présente que si status=ok ou status=warning. Si vous ne renvoyez pas de données, n'incluez pas cette propriété (c'est-à-dire, ne renvoyez pas la propriété avec une valeur de chaîne vide).

Exemple : consultez les exemples ci-dessous.

 

JSON strict requis

Les bibliothèques d'aide de Google et toutes les requêtes envoyées à Google renvoient un code JSON/JSONP strict. Si vous n'analysez pas vous-même le code renvoyé, cela n'a pas d'importance. Si c'est le cas, vous pouvez utiliser JSON.parse() pour convertir la chaîne JSON en objet JavaScript. La manière dont l'API traite le format JSON est la suivante : bien que le format JSON ne soit pas compatible avec les valeurs de date JavaScript (par exemple, "new Date(2008,1,28,0,31,26)", l'API accepte une représentation JSON valide des dates sous forme de chaîne au format suivant : Date(year, month, day[,hour, minute, second[, millisecond]]), où tous les éléments après le jour sont facultatifs et les mois sont basés sur zéro.)

 

Optimiser les réponses JSON

Si un client envoie deux requêtes et que les données n'ont pas changé entre les requêtes, il est judicieux de ne pas renvoyer les données. Cela entraînerait un gaspillage de la bande passante. Pour rendre les requêtes plus efficaces, le protocole prend en charge la mise en cache des données sur le client et envoie un signal dans la réponse si les données n'ont pas changé depuis la dernière requête. Voici comment cela fonctionne :

  1. Le client envoie une requête à la source de données.
  2. La source de données génère un DataTable ainsi qu'un hachage de l'objet DataTable, puis renvoie les deux dans sa réponse (le hachage est renvoyé dans le paramètre tqx.sig). Le client API Google Visualisation met en cache les valeurs DataTable et sig.
  3. Le client envoie une autre requête de données, y compris la valeur tqx.sig mise en cache.
  4. La source de données peut répondre de deux manières :
    • Si les données ont changé depuis la requête précédente, la source de données renvoie le nouveau hachage de valeur DataTable et la nouvelle valeur sig.
    • Si les données n'ont pas été modifiées par rapport à la requête précédente, la source renvoie status=error, reason=not_modified ou sig=old_sig_value.
  5. Dans les deux cas, la page qui héberge le graphique reçoit une réponse positive et peut récupérer le DataTable en appelant QueryResponse.getDataTable(). Si les données sont identiques, il s'agit simplement de la version en cache de la table.

Notez que cela ne fonctionne que pour les requêtes JSON provenant de graphiques créés sur l'API Google Visualization.

Format de réponse CSV

Si la requête spécifie out:csv, la réponse n'inclut pas de métadonnées, mais simplement une représentation des données au format CSV. Une table CSV est généralement une liste de valeurs séparées par une virgule, où chaque ligne de données correspond à une liste de valeurs séparées par une virgule, se terminant par un caractère de retour à la ligne UNIX (\n). Les valeurs des cellules doivent avoir le même type pour chaque colonne. La première ligne contient les libellés des colonnes. Voici un exemple de table à trois lignes, sur trois colonnes:

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

Le format CSV n'est pas spécifié par ce protocole. La source de données est chargée de définir son format CSV. Cependant, un format courant est un ensemble de valeurs séparées par une virgule (sans espaces intermédiaires) et une nouvelle ligne (\n) à la fin de chaque ligne. Lorsqu'un navigateur reçoit une réponse de chaîne CSV, il peut demander à l'utilisateur quelle application utiliser pour ouvrir la chaîne, ou simplement l'afficher à l'écran. Les bibliothèques Open Source Java et Python fournissent une méthode de conversion d'une table de données en une chaîne CSV.

Si la requête inclut un membre outFileName du paramètre tqx , vous devez essayer d'inclure le nom de fichier spécifié dans les en-têtes de réponse.

L'objet google.visualization.Query n'accepte pas de requête de réponse CSV. Si un client souhaite demander un fichier CSV, vous pouvez intégrer un gadget de visualisation de la barre d'outils sur votre page, utiliser un code personnalisé pour créer cette demande ou fournir un lien qui définit explicitement la propriété out:csv de tqx, comme indiqué dans l'URL de requête suivante:

Requête

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

Response (Réponse)

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

Format de réponse TSV

Si la requête spécifie out:tsv-excel, la réponse n'inclut pas de métadonnées, mais simplement une représentation des données séparées par des tabulations (utf-16 encodée). Si la requête inclut un membre outFileName du paramètre tqx , vous devez essayer d'inclure le nom de fichier spécifié dans les en-têtes de réponse.

Format de réponse HTML

Si la requête spécifie out:html, la réponse doit être une page HTML définissant une table HTML avec les données. Cela s'avère utile pour déboguer votre code, car le navigateur peut afficher directement votre résultat dans un format lisible. Vous ne pouvez pas envoyer de requête pour une réponse HTML à l'aide de l'objet google.visualization.Query. Vous devez envoyer une requête pour obtenir une réponse HTML à l'aide d'un code personnalisé ou en saisissant une URL semblable à celle-ci dans votre navigateur:

Requête

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

Response (Réponse)

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

Exemples

Voici quelques exemples de requêtes et de réponses. Notez que les requêtes ne font pas l'objet d'un échappement, ce qui est généralement effectué par le navigateur ou par l'objet google.visualization.Query.

Requête simple : renvoie les informations de base avec une table à trois colonnes sur quatre lignes.

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'}]}]}});

Requête simple avec un gestionnaire de réponses : renvoie une table à trois colonnes et trois lignes avec différents types de données.

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'}]}]}});

Requête avec une simple chaîne de requête:requête sur une seule colonne et affiche une seule colonne avec quatre lignes.

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'}]}]}});

Erreur "Données non modifiées":exemple d'erreur 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'}]});

Avertissement de données tronquées : Exemple d'avertissement data_truncated. Notez que la requête renvoie toujours des données.

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'}]}]}});

Erreur d'accès refusé:exemple d'erreur 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'}]});

Chaîne de requête non valide : exemple de requête avec une chaîne de requête non valide. Notez que le message détaillé est un message générique plutôt que le message d'erreur réel.

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.'}]});

Outils de développement

  • Bibliothèque de données sources Java (de Google) : gère la requête et la réponse, crée la table de réponse à partir des données que vous lui fournissez, et implémente le langage de requête SQL de Google Tools.
  • Bibliothèque de sources de données Python (de Google) : crée une table de réponse qui génère la syntaxe de la réponse. Il ne gère pas l'analyse de la requête ni la mise en œuvre du langage de requête SQL Google Chart Tools.
  • MC-Google_Visualization (tierce) : cette bibliothèque PHP côté serveur vous permet d'implémenter une source de données de graphique d'outils pour MySQL, SQLite et PostgreSQL à l'aide de PDO.
  • bortosky-google-visualization (tierce) : bibliothèque d'aide permettant de créer une table de données de l'API Google Visualization pour les utilisateurs .NET
  • GV Streamer (tierce) : GV Streamer est un outil côté serveur qui peut convertir des données de différentes sources en réponses de requête valides pour la création de graphiques Google. GV Streamer est compatible avec plusieurs langages (par exemple, PHP, Java et .NET) et plusieurs sources de données brutes (par exemple, MySql).
  • TracGViz (tierce) : TracGViz est un outil Open Source offert qui fournit des composants permettant à Trac d'utiliser des gadgets de graphique, ainsi que de mettre en œuvre des données gérées par Trac en tant que source de données de Google Chart Tools.
  • vis-table (tierce) : bibliothèque qui met en œuvre une source de données Google Chart Tools en PHP. Il est composé de trois parties principales. L'implémentation de table de données elle-même, l'analyseur du langage de requête et les outils de mise en forme.
  • Implémentation de sources de données Google dans Oracle PL/SQL (tiers) : package PL/SQL Oracle qui permet à Oracle de traiter les sources de données directement à partir de la base de données. Vous pouvez donc utiliser n'importe quelle requête Oracle en tant que source de données des outils de graphique Google (le package renverra un fichier JSON contenant les données). Le langage de requête Google est quasiment entièrement compatible.