Implementación del protocolo de fuente de datos de las herramientas de gráficos (V0.6)

En esta página, se describe cómo implementar un servicio que admita el protocolo de fuente de datos de herramientas de gráficos para exponer datos a gráficos mediante la clase Query.

Contenido

Público

Esta página está destinada principalmente a desarrolladores que crearán su propia fuente de datos sin la ayuda de la Biblioteca de fuentes de datos de herramientas de gráficos. Si usas esa o cualquier otra biblioteca auxiliar, primero lee la documentación de tu biblioteca.

Esta página también está destinada a los lectores interesados en comprender el protocolo de conexión que se usa para la comunicación entre una visualización de cliente y una fuente de datos.

Si estás creando o usando una visualización, no es necesario que leas esta página.

Para leer este documento, debes comprender la sintaxis básica de las solicitudes JSON y HTTP. También debes comprender cómo funcionan los gráficos desde la perspectiva del usuario.

Descripción general

Puedes implementar el protocolo Fuente de datos de las herramientas de gráficos para convertirte en un proveedor de fuentes de datos para tus propios gráficos, o bien otros gráficos. Una fuente de datos de herramientas de gráficos expone una URL, denominada URL de la fuente de datos, a la que un gráfico puede enviar solicitudes HTTP GET. En respuesta, la fuente de datos muestra datos con el formato correcto que el gráfico puede usar para renderizar el gráfico en la página. Este protocolo de solicitud-respuesta se conoce como el protocolo de conexión de la API de visualización de Google.

Los datos que entrega una fuente de datos se pueden extraer de varios recursos, como un archivo o una base de datos. La única restricción es que puedes formatear los datos como una tabla bidimensional con columnas escritas.

Como fuente de datos de herramientas de gráficos, debes analizar una solicitud en un formato específico y mostrar una respuesta en un formato específico. Para ello, puede usar uno de estos métodos generales:

• Usa una de las siguientes bibliotecas auxiliares para controlar la solicitud y la respuesta, y construye la DataTable que se mostrará. Si usas una de estas bibliotecas, solo debes escribir el código necesario para que los datos estén disponibles para la biblioteca en forma de tabla.
  • Biblioteca de fuentes de datos de Java: Controla la solicitud y la respuesta, crea la tabla de respuesta a partir de los datos que le proporcionas y, luego, implementa el lenguaje de consulta de SQL de las herramientas de gráficos de Google.
  • Biblioteca de fuente de datos de Python: Crea una tabla de respuesta que genera la sintaxis de respuesta. No controla el análisis de la solicitud ni la implementación del lenguaje de consulta en SQL de las Herramientas de gráficos de Google.
    
    O
    
    
• Escribe tu propia fuente de datos desde cero. Para ello, controla la solicitud, construye una DataTable y envía la respuesta.

Cómo funciona:

1. La fuente de datos expone una URL, llamada URL de la fuente de datos, a la que los gráficos envían una solicitud HTTP GET.
2. El cliente realiza una solicitud GET HTTP con parámetros que describen qué formato se debe usar para los datos que se muestran, una cadena de consulta y parámetros personalizados opcionales.
3. La fuente de datos recibe y analiza la solicitud, como se describe en Formato de la solicitud.
4. La fuente de datos prepara los datos en el formato solicitado; por lo general, esta es una tabla JSON. Los formatos de respuesta se describen en la sección Formato de respuesta. De manera opcional, la fuente de datos puede admitir el lenguaje de consulta de la API de visualización que especifica el filtrado, el ordenamiento y otras manipulaciones de datos.
5. La fuente de datos crea una respuesta HTTP que incluye los datos serializados y otros parámetros de respuesta, y la envía de vuelta al cliente como se describe en Formato de respuesta.

Nota: Todos los parámetros y los valores constantes de string que se indican en este documento para las solicitudes y respuestas (como responseHandler y "ok") están en minúscula y distinguen mayúsculas de minúsculas.

Requisitos mínimos

Estos son los requisitos mínimos para que funcione como fuente de datos de herramientas de gráficos:

• La fuente de datos debe aceptar solicitudes HTTP GET y debe estar disponible para tus clientes.
• El protocolo puede cambiar y es compatible con un esquema de versiones (la versión actual es 0.6), por lo que tu fuente de datos debe admitir solicitudes que usan versiones anteriores y la actual. Debes intentar admitir las nuevas versiones en cuanto se lanzan para evitar fallas en los clientes que actualizan a la versión más reciente rápidamente.
• No falles si se envían propiedades desconocidas como parte de la solicitud. Esto se debe a que las versiones nuevas pueden ingresar propiedades nuevas que no conoces.
• Analiza solo las propiedades que esperas. Aunque las versiones nuevas pueden ingresar propiedades nuevas, no las aceptes ni uses a ciegas toda la cadena de solicitud. Para protegerte de ataques maliciosos, analiza con cuidado y usa solo las propiedades que esperas.
• Documenta los requisitos de la fuente de datos con cuidado si no estás codificando los gráficos del cliente tú mismo. Esto incluye documentar la siguiente información:
  • Todos los parámetros personalizados que acepte
  • si puedes o no analizar el lenguaje de consulta de la API de visualización de Google
  • El tipo de datos que muestras y la estructura de esos datos (lo que representan las filas y columnas, y cualquier etiqueta).
• Toma todas las precauciones de seguridad estándar para un sitio que acepta solicitudes de clientes desconocidos. Puedes admitir MD5, el hashing y otros mecanismos de seguridad en tus parámetros de manera razonable para autenticar solicitudes o ayudar a proteger contra ataques maliciosos, y esperar que los clientes estén al tanto de tus requisitos y respondan a ellos. Sin embargo, asegúrate de documentar bien todos tus requisitos si no codificas los gráficos tú mismo. Consulta Consideraciones de seguridad a continuación.
• Todas las cadenas de solicitud y respuesta deben estar codificadas en UTF-8.
• El formato de respuesta más importante es JSON. Asegúrate de implementar JSON primero, ya que este es el formato que usan la mayoría de los gráficos. Agrega otros tipos de respuesta después.
• No es obligatorio que admitas el lenguaje de consulta de la API de visualización, pero hace que tu fuente de datos sea más útil para los clientes.
• No es obligatorio que admitas solicitudes de todos los tipos de gráficos, y puedes admitir parámetros personalizados para gráficos personalizados. Sin embargo, debes mostrar las respuestas en el formato estándar que se describe a continuación.

Consideraciones de seguridad

Cuando diseñes tu fuente de datos, deberás considerar qué tan seguros deben ser tus datos. Puedes usar varios esquemas de seguridad para tu sitio, desde el simple acceso con contraseña hasta la autenticación segura de cookies.

Los ataques de XSSI (inclusión de secuencias de comandos entre sitios) son un riesgo en los gráficos. Un usuario puede navegar a una página que contiene una secuencia de comandos maliciosa que luego comienza a realizar consultas en las URLs de la fuente de datos con las credenciales del usuario actual. Si el usuario no salió de un sitio, la secuencia de comandos se autenticará como el usuario actual y tendrá permisos para ese sitio. Si usas una etiqueta <script src>, la secuencia de comandos maliciosa puede incluir la fuente de datos, similar a JSONP.

Como un nivel de seguridad adicional, puedes considerar restringir las solicitudes a aquellas que provengan del mismo dominio que tu fuente de datos. Esto restringirá considerablemente la visibilidad de tu fuente de datos. Sin embargo, si tienes datos muy sensibles a los que no se debería acceder desde fuera de tu dominio, deberías considerarlos. Una fuente de datos que solo permite solicitudes del mismo dominio se denomina fuente de datos restringida, a diferencia de una fuente de datos no restringida, que acepta consultas de cualquier dominio. A continuación, se incluyen algunos detalles para implementar una fuente de datos restringida:

Para asegurarte de que una solicitud provenga realmente de tu dominio y no de un dominio externo (o de un navegador dentro del dominio que sufra un ataque XSRF), haz lo siguiente:

• Verifica la presencia de un encabezado “X-DataSource-Auth” en la solicitud. La API de visualización de Google define este encabezado; no necesitas examinar el contenido de este encabezado; solo verifica que esté allí. Si usas la biblioteca de fuentes de datos de herramientas de gráficos de Google, puedes hacer que la biblioteca se encargue de ello.
• Usa la autenticación con cookies para autenticar al cliente. No hay una forma conocida de insertar encabezados personalizados en una solicitud entre dominios mientras se mantienen las cookies de autenticación en su lugar.
• Impide que JavaScript se ejecute cuando se incluye con una etiqueta <script src>. Para hacerlo, usa )]}' como prefijo de tu respuesta JSON seguido de un salto de línea. En tu cliente, quita el prefijo de la respuesta. Para XmlHttpRequest, esto solo es posible cuando la solicitud se originó en el mismo dominio.

Formato de la solicitud

Un cliente envía una solicitud GET HTTP con varios parámetros, incluidos elementos personalizados, una cadena de consulta opcional, firma y otros elementos. Solo eres responsable de analizar los parámetros descritos en esta sección y debes tener cuidado de no manejar otros para evitar ataques maliciosos.

Asegúrate de tener valores predeterminados para los parámetros opcionales (tanto estándar como personalizados) y documenta todos los valores predeterminados en la documentación del sitio.

A continuación, se muestran algunas solicitudes de ejemplo (puedes ver más ejemplos de solicitudes y respuestas al final de este documento en Ejemplos):

Nota: Las siguientes strings de solicitud, y las que se muestran en la sección Ejemplos, deben tener formato de escape por URL antes del envío.

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

A continuación, se muestra una lista de todos los parámetros estándar en la cadena de solicitud. Ten en cuenta que tanto los nombres de parámetros (como "version") como los valores de cadenas constantes (como "ok", "warning" y "not_Modified") distinguen mayúsculas de minúsculas. En la tabla, también se describe si es necesario enviar el parámetro y, si se envía, si es necesario que lo administres.

Formato de la respuesta

El formato de la respuesta depende del parámetro out de la solicitud, que especifica el tipo de respuesta esperada. Consulta las siguientes secciones para obtener información sobre cómo responder a cada tipo de solicitud:

• JSON: Muestra una respuesta JSON que incluye los datos en un objeto JavaScript que se puede pasar directamente a un constructor DataTable para propagarlo. Este es, por mucho, el tipo de solicitud más común y el más importante que se debe implementar correctamente.
• CSV: Muestra una lista plana de valores separados por comas que controlará el navegador.
• TSV: Muestra una lista de valores separados por tabulaciones que controlará el navegador.
• HTML: Muestra una tabla HTML para que el navegador la renderice.

Puedes usar la biblioteca de fuente de datos de visualización de Google (java) o la biblioteca de Python de visualización para generar estos formatos de resultados por ti.

Formato de respuesta JSON

El formato de respuesta predeterminado es JSON si la solicitud incluye un encabezado "X-DataSource-Auth"; de lo contrario, JSONP. Ten en cuenta que el cliente del gráfico de Google en realidad admite una versión modificada de JSON y JSONP. Si usas las bibliotecas auxiliares de Java o Python, te mostrarán el código adecuado. Si analizas respuestas de forma manual, consulta Modificaciones de JSON a continuación.

Si aplicas solicitudes del mismo dominio, debes verificar la presencia del encabezado "X-DataSource-Auth" en la solicitud y usar cookies de autorización.

Este es el único formato de respuesta que especifica el método google.visualization.Query.send() de la API de visualización de Google. Puedes ver algunos ejemplos de solicitudes JSON y respuestas al final de esta página en Ejemplos. Puedes usar las bibliotecas auxiliares de Java o Python para crear esta string de respuesta por ti.

Este formato de respuesta es un objeto JSON con codificación UTF-8 (un objeto unido por llaves { }, con cada propiedad separada por una coma) que incluye las propiedades de la siguiente tabla (los datos se asignan a la propiedad table). Este objeto JSON debe unirse dentro del valor del parámetro responseHandler de la solicitud. Por lo tanto, si el valor responseHandler de la solicitud era "myHandler", debes mostrar una string como la siguiente (para abreviación, se muestra solo una propiedad):

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

Si la solicitud no incluye un valor responseHandler, el valor predeterminado es "google.visualization.Query.setResponse", por lo que debes mostrar una cadena como esta (se muestra solo una propiedad para mayor brevedad):

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

Estos son los miembros del objeto de respuesta 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'}]}
      ]
} 

Optimiza las respuestas de JSON

Si un cliente realiza dos solicitudes y los datos no cambiaron entre las solicitudes, tiene sentido no volver a enviar los datos, ya que esto desperdiciaría ancho de banda. Para que las solicitudes sean más eficientes, el protocolo admite el almacenamiento en caché de los datos en el cliente y el envío de una señal en la respuesta si los datos no cambiaron desde la última solicitud. A continuación, le mostramos cómo funciona:

1. El cliente envía una solicitud a la fuente de datos.
2. La fuente de datos genera un DataTable y un hash del objeto DataTable, y los muestra en su respuesta (el hash se muestra en el parámetro tqx.sig). El cliente de la API de visualización de Google almacena en caché los valores DataTable y sig.
3. El cliente envía otra solicitud de datos, incluido el valor tqx.sig almacenado en caché.
4. La fuente de datos puede responder de una de estas dos maneras:
   • Si los datos cambiaron desde la solicitud anterior, la fuente de datos devuelve el nuevo hash de valor DataTable y sig.
   • Si los datos no cambiaron desde la solicitud anterior, la fuente de datos devuelve status=error, reason=not_modified, sig=old_sig_value.
5. En cualquier caso, la página que aloja el gráfico obtiene una respuesta correcta y puede recuperar el DataTable llamando a QueryResponse.getDataTable(). Si los datos son iguales, simplemente serán la versión almacenada en caché de la tabla.

Ten en cuenta que esto solo funciona para solicitudes JSON de gráficos compilados en la API de visualización de Google.

Formato de respuesta de CSV

Si la solicitud especifica out:csv, la respuesta no incluye metadatos, sino solo una representación CSV de los datos. Por lo general, una tabla CSV es una lista separada por comas, en la que cada fila de datos es una lista de valores separados por comas, que termina en un carácter de línea nueva de UNIX (\n). Los valores de las celdas deben tener el mismo tipo para cada columna. La primera fila son las etiquetas de las columnas. Este es un ejemplo de una tabla de tres filas y tres columnas:

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

Este protocolo no especifica el formato CSV; la fuente de datos es responsable de definirlo. Sin embargo, un formato común es un conjunto de valores separados por comas (sin espacios intermedios) y una línea nueva (\n) al final de cada fila. Cuando un navegador recibe una respuesta de cadena CSV, podría preguntarle al usuario qué aplicación usar para abrir la cadena o podría simplemente renderizarla en la pantalla. Las bibliotecas de código abierto de Java y Python proporcionan un método para convertir DataTable en una string CSV.

Si la solicitud incluye un miembro outFileName del parámetro tqx , debes intentar incluir el nombre del archivo especificado en los encabezados de respuesta.

El objeto google.visualization.Query no admite una solicitud de respuesta CSV. Si un cliente quiere solicitar un archivo CSV, puedes incorporar un widget de la Barra de herramientas de visualización en tu página, usar un código personalizado para crear la solicitud o proporcionar un vínculo que establezca la propiedad out:csv de tqx de manera explícita, como se muestra en la siguiente URL de solicitud:

Solicitud

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

Respuesta

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

Formato de respuesta del TSV

Si la solicitud especifica out:tsv-excel, la respuesta no incluye metadatos, sino solo una representación de los datos separada por tabulaciones, codificado en utf-16. Si la solicitud incluye un miembro outFileName del parámetro tqx , debes intentar incluir el nombre del archivo especificado en los encabezados de respuesta.

Formato de respuesta HTML

Si la solicitud especifica out:html, la respuesta debe ser una página HTML que defina una tabla HTML con los datos. Esto es útil para depurar tu código, ya que el navegador puede procesar el resultado en un formato legible directamente. No puedes enviar una consulta para una respuesta HTML con el objeto google.visualization.Query. Para realizar una consulta para obtener una respuesta HTML, debes usar un código personalizado o escribir una URL similar a esta en tu navegador:

Solicitud

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

Respuesta

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

Ejemplos

Estos son algunos ejemplos de solicitudes y respuestas. Ten en cuenta que las solicitudes no tienen escape de URL; esto suele hacerse mediante el navegador o el objeto google.visualization.Query.

Solicitud simple: muestra la información básica con una tabla de tres columnas y cuatro filas.

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

Solicitud simple con un controlador de respuestas: muestra una tabla de tres columnas y tres filas con diferentes tipos de datos.

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

Consulta con una cadena de consulta simple: en la solicitud de una sola columna, se muestra una sola columna con cuatro filas.

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

Error de datos no modificados: ejemplo de un error 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'}]});

Advertencia de datos truncados: Ejemplo de una advertencia de data_truncated. Ten en cuenta que la solicitud aún muestra datos.

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

Error de acceso denegado: Ejemplo de un error 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'}]});

Cadena de consulta no válida: ejemplo de una solicitud con una cadena de consulta no válida. Ten en cuenta que el mensaje detallado es un mensaje genérico, no el mensaje de error real.

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

Herramientas de desarrollo

• Biblioteca de fuentes de datos de Java (de Google): Controla la solicitud y la respuesta, crea la tabla de respuesta a partir de los datos que le proporcionas y, luego, implementa el lenguaje de consulta de SQL de las herramientas de gráficos de Google.
• Biblioteca de fuente de datos de Python (de Google): Crea una tabla de respuesta que genera la sintaxis de respuesta. No controla el análisis de la solicitud ni la implementación del lenguaje de consulta en SQL de las Herramientas de gráficos de Google.
• MC-Google_Visualization (tercero): Esta es una biblioteca del servidor de PHP que puedes usar a fin de implementar una fuente de datos de herramientas de gráficos para motores de base de datos MySQL, SQLite y PostgreSQL mediante PDO.
• bortosky-google-visualization (tercero): Es una biblioteca auxiliar que permite crear una tabla de datos de la API de visualización de Google para usuarios de .NET.
• GV Streamer (de terceros): GV Streamer es una herramienta del servidor que puede convertir datos de diferentes fuentes en respuestas de consulta válidas a gráficos de Google. GV Streamer admite varios lenguajes (por ejemplo, PHP, Java y .NET) y varias fuentes de datos sin procesar (por ejemplo, MySQL).
• TracGViz (terceros): TracGViz es una herramienta gratuita y de código abierto que proporciona componentes para que Trac pueda usar gadgets de gráficos y pueda implementar datos administrados por Trac como fuente de datos de herramientas de gráficos de Google.
• vis-table (tercero): biblioteca que implementa una fuente de datos de herramientas de gráficos de Google en PHP. Consta de tres partes principales. La implementación de la tabla de datos en sí, el analizador de lenguaje de consulta y los formateadores.
• Implementación de fuentes de datos de Google en Oracle PL/SQL (de terceros): Es un paquete de PL/SQL de Oracle que permite que Oracle servidor fuentes de datos directamente desde la base de datos. En pocas palabras, puedes usar cualquier consulta de Oracle como una fuente de datos de herramientas de gráficos de Google (el paquete mostrará un archivo JSON con los datos). Es compatible casi por completo con el lenguaje de consulta de Google.