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

Cette page explique comment mettre en œuvre un service compatible avec le protocole Chart Tools Datasource pour exposer des données à 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 des outils de graphique. Si vous utilisez cette bibliothèque ou toute autre bibliothèque d'assistance, commencez par lire la documentation de votre bibliothèque.

Cette page s'adresse également aux lecteurs qui souhaitent comprendre le protocole filaire 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 connaître la syntaxe de base des requêtes JSON et HTTP. Vous devez également comprendre comment les graphiques fonctionnent du point de vue d'un utilisateur.

Présentation

Vous pouvez mettre en œuvre le protocole de source de données des outils de graphique afin de devenir un fournisseur de source de données pour vos propres graphiques ou d'autres graphiques. Une source de données d'outils de graphique expose une URL, appelée URL de la 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 requête-réponse est connu sous le nom de protocole filaire de l'API Google Visualization.

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

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

• Utilisez l'une des bibliothèques d'aide suivantes pour gérer la requête et la réponse, puis créez la table de données à renvoyer. Si vous utilisez l'une de ces bibliothèques, vous n'avez besoin d'écrire que le code nécessaire pour mettre les données à la disposition de la bibliothèque sous la forme d'une table.
  • Bibliothèque de sources de données Java : gère la requête et la réponse, crée la table de réponses à partir des données que vous lui fournissez et implémente le langage de requête SQL des outils de graphique Google.
  • Bibliothèque de sources de données Python : crée une table de réponses qui génère la syntaxe de la réponse. Ne gère pas l'analyse de la requête ni la mise en œuvre du langage de requête SQL de Google Chart Tools.
    
    OU
    
    
• Écrivez votre propre source de données à partir de zéro 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, à laquelle les graphiques envoient une requête HTTP GET.
2. Le client effectue une requête HTTP GET avec des paramètres qui décrivent le format à utiliser pour les données renvoyées, ainsi qu'une chaîne de requête 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 abordés dans la section Format de réponse. La source de données peut éventuellement accepter le langage de requête de l'API Visualization, 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 les valeurs constantes de chaîne répertoriés dans ce document pour les requêtes et les réponses (telles que responseHandler et "ok") sont minuscules et sensibles à la casse.

Configuration requise

Voici la configuration minimale requise pour pouvoir servir de source de données d'outils graphiques:

• 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 ainsi que la version actuelle. Essayez de prendre en charge les nouvelles versions dès leur publication afin d'éviter de perturber les clients qui effectuent rapidement une mise à niveau vers la version la plus récente.
• N'échouez pas si des propriétés inconnues sont envoyées dans la requête. En effet, les nouvelles versions peuvent introduire de nouvelles propriétés que vous ignorez.
• Analysez uniquement les propriétés attendues. Bien que les nouvelles versions puissent introduire de nouvelles propriétés, n'acceptez pas et n'utilisez pas aveuglément la chaîne de requête dans son intégralité. Pour vous protéger contre les attaques malveillantes, analysez et utilisez soigneusement les propriétés attendues.
• Documentez attentivement les exigences concernant votre source de données si vous ne codez pas vous-même les graphiques clients. Cela inclut la documentation des informations suivantes :
  • Tous les paramètres personnalisés que vous acceptez,
  • Indique si vous pouvez analyser le langage de requête de l'API Google Visualization.
  • Le type de données que vous renvoyez et leur structure (ce que représentent les lignes et les colonnes, et les libellés éventuels).
• 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 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. Attendez-vous également à ce que les clients connaissent vos besoins et y répondent. Toutefois, si vous ne codez pas vous-même les graphiques, assurez-vous de bien documenter toutes vos exigences. Consultez la section Considérations relatives à la sécurité ci-dessous.
• Toutes les chaînes de requêtes et de réponses 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 JSON, car il s'agit du format utilisé par la plupart des graphiques. Ajoutez d'autres types de réponses par la suite.
• Vous n'êtes pas obligatoire de prendre en charge le langage de requête de l'API Visualization, mais cela rend votre source de données plus utile pour les clients.
• Vous n'êtes pas obligé de prendre en charge les requêtes provenant de tous les types de graphiques. De plus, vous pouvez accepter les paramètres personnalisés pour les graphiques personnalisés. Toutefois, vous devez renvoyer des réponses au format standard décrit ci-dessous.

Remarques concernant la sécurité

Lors de la conception de votre source de données, vous devez prendre en compte le niveau de sécurité de vos données. Vous pouvez utiliser différents schémas de sécurité pour votre site, du simple accès par mot de passe à l'authentification sécurisée par cookie.

Les attaques XSSI (cross-site script inclusion) présentent un risque avec les graphiques. Un utilisateur peut accéder à une page contenant un script malveillant qui commence alors à tenter d'interroger les URL de sources 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. En utilisant une balise <script src>, le script malveillant peut inclure la source de données, comme au format 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 vous disposez de données très sensibles auxquelles il ne faut pas accéder depuis l'extérieur de votre domaine, pensez à les utiliser. 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 illimitée qui accepte les requêtes provenant 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 externe (ou d'un navigateur à l'intérieur du domaine qui fait l'objet d'une attaque XSRF):

• Vérifiez la présence d'un 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'examiner son contenu. Vérifiez simplement qu'il s'y trouve. Si vous utilisez la bibliothèque de sources de données Google Chart Tools, vous pouvez demander à celle-ci de gérer cela pour vous.
• Utilisez l'authentification des cookies 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.
• Empêche l'exécution du code JavaScript lorsqu'il est inclus avec une balise <script src>. Pour ce faire, ajoutez le préfixe )]}' à votre réponse JSON, suivi d'un retour à la 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 requête

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 ainsi que d'autres éléments. Vous êtes uniquement responsable de l'analyse des paramètres décrits dans cette section. Veillez à ne pas gérer les autres afin d'éviter les attaques malveillantes.

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

Voici quelques exemples de requêtes (vous trouverez d'autres exemples de requêtes et de réponses à la fin de ce document, dans la section Exemples):

Remarque: Les chaînes de requête suivantes, ainsi que celles affichées dans la section Exemples, doivent être échappées au format URL avant leur 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 de paramètres (tels que "version") et les valeurs de chaîne constante (telles que "ok", "warning" et "not_modify") 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.

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 dans un objet JavaScript pouvant être transmis directement à un constructeur DataTable pour les renseigner. Il s'agit de loin du type de requête le plus courant, et le plus important à mettre en œuvre correctement.
• CSV : renvoie une liste plate de valeurs séparées par des virgules, qui doit être gérée par le navigateur.
• TSV : renvoie une liste de valeurs séparées par des tabulations à gérer 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 JSONP dans le cas contraire. Notez que le client de graphique Google est compatible avec une version modifiée de JSON et JSONP. Si vous utilisez les bibliothèques d'aide Java ou Python, elles génèrent le code approprié. Si vous analysez les réponses à la main, consultez la section Modifications JSON ci-dessous.

Si vous appliquez des requêtes ciblant 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 google.visualization.Query.send() de l'API Google Visualization. Vous trouverez des exemples de requêtes et de réponses JSON au bas de cette page, dans la section Exemples. Vous pouvez utiliser les bibliothèques d'aide Java ou Python pour créer cette chaîne de réponse.

Ce format de réponse est un objet JSON encodé au format UTF-8 (objet entouré d'accolades { } avec chaque propriété séparée par une virgule) qui 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 comme celle-ci (par souci de concision, une seule propriété est affichée):

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

Si la requête n'incluait 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'objets de réponse disponibles:

{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'}]}
      ]
} 

Optimiser les réponses JSON

Si un client effectue deux requêtes et que les données n'ont pas changé entre les requêtes, il est logique de ne pas renvoyer les données, car cela gaspille la bande passante. Pour améliorer l'efficacité des requêtes, le protocole prend en charge la mise en cache des données sur le client et l'envoi d'un signal dans la réponse si les données n'ont pas été modifiées 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 une valeur DataTable ainsi qu'un hachage de l'objet DataTable, puis les renvoie dans sa réponse (le hachage est renvoyé dans le paramètre tqx.sig). Le client de l'API Google Visualization 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 été modifiées par rapport à la requête précédente, la source de données renvoie le nouveau hachage de la valeur DataTable et le nouveau hachage de la valeur sig.
   • Si les données n'ont pas changé par rapport à la requête précédente, la source de données renvoie status=error, reason=not_modified, 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'agira simplement de la version mise en cache de la table.

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

Format de réponse CSV

Si la requête spécifie out:csv, la réponse ne comprend pas de métadonnées, mais simplement une représentation CSV des données. Une table CSV est généralement constituée d'une liste d'éléments séparés par une virgule, où chaque ligne de données est une liste de valeurs séparées par des virgules et se termine par un caractère de nouvelle ligne UNIX (\n). Les valeurs des cellules doivent être du même type pour chaque colonne. La première ligne contient les libellés des colonnes. Voici un exemple de table à trois lignes et 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 responsable de la définition de son format CSV. Cependant, un format courant est un ensemble de valeurs séparées par des virgules (sans espaces intermédiaires) et un saut de ligne (\n) à la fin de chaque ligne. Lorsqu'un navigateur reçoit une réponse sous forme de chaîne CSV, il peut demander à l'utilisateur l'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 pour convertir un tableau de données en 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 ne prend pas en charge les requêtes de réponse CSV. Si un client souhaite demander un fichier CSV, vous pouvez intégrer un gadget de barre d'outils de visualisation sur votre page, utiliser du code personnalisé pour créer la requête 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

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 ne comprend pas de métadonnées, mais simplement une représentation des données délimitée par des tabulations et encodée en utf-16. 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 un tableau HTML avec les données. Cela est 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 obtenir une réponse HTML à l'aide de l'objet google.visualization.Query. Vous devez effectuer une requête pour une réponse HTML à l'aide de 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

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 n'ont pas fait l'objet d'un échappement d'URL. Cette opération est généralement effectuée soit par le navigateur, soit par l'objet google.visualization.Query.

Requête simple: renvoie les informations de base avec une table à trois colonnes et 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 des types de données différents.

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 chaîne de requête simple:requête portant sur une seule colonne, elle renvoie une seule colonne de 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, et non 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 sources de données Java (de Google) : gère la requête et la réponse, crée la table de réponses à partir des données que vous lui fournissez et implémente le langage de requête SQL de Google Chart Tools.
• Bibliothèque Datasource Python (de Google) : crée une table de réponses qui génère la syntaxe de la réponse. Ne gère pas l'analyse de la requête ni la mise en œuvre du langage de requête SQL de Google Chart Tools.
• MC-Google_Visualization (tiers) : cette bibliothèque côté serveur vous permet d'implémenter une source de données d'outils de graphique pour les moteurs de base de données MySQL, SQLite et PostgreSQL à l'aide de PDO.
• bortosky-google-visualization (tiers) : cette bibliothèque d'aide permet de créer un tableau de données de l'API Google Visualization pour les utilisateurs de .NET.
• GV Streamer (tiers) : GV Streamer est un outil côté serveur qui peut convertir des données provenant de différentes sources en réponses aux requêtes valides en graphiques Google. GV Streamer est compatible avec plusieurs langages (par exemple, PHP, Java ou .NET) et plusieurs sources de données brutes (par exemple, MySql).
• TracGViz (tiers) : TracGViz est un outil sans frais et Open Source qui fournit des composants lui permettant d'utiliser des gadgets de graphique et d'implémenter les données gérées par Trac en tant que source de données Google Chart Tools.
• vis-table (tiers) : bibliothèque mettant en œuvre une source de données Google Chart Tools en PHP. Il se compose de trois parties principales. L'implémentation du tableau de données elle-même, l'analyseur de langage de requête et les outils de mise en forme.
• Implémentation des sources de données Google dans Oracle PL/SQL (tiers) : package Oracle PL/SQL qui permet à Oracle de stocker des sources de données directement à partir de la base de données. Vous pouvez donc utiliser n'importe quelle requête Oracle comme source de données Google Chart Tools (le package renverra un fichier JSON contenant les données). Il est presque entièrement compatible avec le langage de requête Google.