Implementa el protocolo de fuente de datos de herramientas de gráficos (V0.6)

En esta página, se describe cómo puedes 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 de consulta.

Contenido

Público

Esta página está destinada principalmente a los 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 la usas o cualquier otra biblioteca auxiliar, primero lee la documentación de tu biblioteca.

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

Si creas o usas una visualización, no necesitas leer esta página.

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

Nota: Google no respalda ni respalda oficialmente ninguna fuente de datos que no sea de Google que admita el protocolo de fuente de datos de herramientas para gráficos.

Descripción general

Puedes implementar el protocolo de fuente de datos de las herramientas de gráficos para convertirte en un proveedor de fuentes de datos de tus propios gráficos, o de otros gráficos. Una fuente de datos de herramientas de gráfico expone una URL, denominada URL de 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 procesar 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. Puedes hacerlo de dos maneras generales:

  • Usa una de las siguientes bibliotecas auxiliares para controlar la solicitud y la respuesta, y construye la tabla de datos que se mostrará. Si usas una de estas bibliotecas, solo debes escribir el código necesario para que tus datos estén disponibles en forma de tabla.
  • Escribir tu propia fuente de datos desde cero: controla la solicitud, construye una DataTable y envía la respuesta.

Cómo funciona:

  1. La fuente de datos expone una URL, denominada URL de la fuente de datos, a la que los gráficos envían una solicitud HTTP GET.
  2. El cliente realiza una solicitud HTTP GET con parámetros que describen qué formato usar para los datos que se muestran, una string de consulta opcional y parámetros personalizados opcionales.
  3. La fuente de datos recibe y analiza la solicitud, como se describe en Formato de 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 abordan en la sección Formato de respuesta. Opcionalmente, la fuente de datos puede admitir el lenguaje de consulta de la API de visualización que especifica filtros, ordenamientos y otros tipos de manipulación de datos.
  5. La fuente de datos crea una respuesta HTTP que incluye los datos serializados y otros parámetros de respuesta, y los envía de vuelta al cliente, como se describe en Formato de respuesta.

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

Requisitos mínimos

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

  • La fuente de datos debe aceptar las solicitudes GET de HTTP y debe estar disponible para tus clientes.
  • El protocolo puede cambiar y admitir un esquema de versión (la versión actual es 0.6), por lo que la fuente de datos debe admitir solicitudes que usen versiones anteriores y la actual. Deberías intentar admitir versiones nuevas en cuanto se lancen para evitar romper con los clientes que se actualizan a la versión más rápida rápidamente.
  • No falles si se envían propiedades desconocidas como parte de la solicitud. Esto se debe a que las versiones nuevas pueden introducir propiedades nuevas que desconoces.
  • Analiza solo las propiedades que esperas. Aunque las versiones nuevas podrían introducir propiedades nuevas, no aceptes y uses ciegamente toda la string de solicitud. Para protegerte de los ataques maliciosos, analiza con cuidado y usa solo las propiedades que esperas.
  • Documenta con cuidado los requisitos de la fuente de datos si no codificas los gráficos del cliente por tu cuenta. Esto incluye documentar la siguiente información:
    • Cualquier parámetro personalizado que acepte
    • Si puedes o no analizar el lenguaje de consultas de la API de visualización de Google
    • Qué tipo de datos se muestran y su estructura (lo que representan las filas y columnas, y cualquier etiqueta)
  • Toma todas las precauciones estándar de seguridad para un sitio que acepta solicitudes de clientes desconocidos. Puedes admitir de forma razonable el MD5, el hashing y otros mecanismos de seguridad en tus parámetros para autenticar las solicitudes o ayudar a proteger contra ataques maliciosos, y esperar que los clientes conozcan tus requisitos y respondan a ellos. Sin embargo, asegúrate de documentar todos tus requisitos bien si no codificas los gráficos tú mismo. Consulta Consideraciones de seguridad a continuación.
  • Todas las strings de solicitud y respuesta deben estar codificadas en UTF-8.
  • El formato de respuesta más importante es JSON. Asegúrate de implementar primero JSON, ya que este es el formato que usan la mayoría de los gráficos. Agrega otros tipos de respuesta luego.
  • 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 admitir solicitudes de todos los tipos de gráficos. Además, 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 una variedad de esquemas de seguridad para tu sitio, desde el simple acceso de contraseñas hasta la autenticación segura de cookies.

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

Como nivel adicional de seguridad, puedes considerar restringir las solicitudes a aquellas que provengan del mismo dominio que tu fuente de datos. Esto restringirá considerablemente la visibilidad de la fuente de datos, pero si tienes datos muy sensibles a los que no se debe acceder desde fuera de tu dominio, debes considerarlos. Una fuente de datos que solo permite solicitudes del mismo dominio se denomina fuente de datos restringida, a diferencia de la fuente de datos sin restricciones, que aceptará consultas de cualquier dominio. A continuación, se incluyen algunos detalles sobre cómo implementar una fuente de datos restringida:

Para asegurarte de que una solicitud provenga realmente de tu dominio y no de un dominio externo (o un navegador dentro del dominio que se encuentra en ataque XSRF):

  • Verifica la presencia de un encabezado "X-DataSource-Auth" en la solicitud. La API de visualización de Google define este encabezado; no es necesario que examines el contenido, solo verifica que esté allí. Si usas la biblioteca de fuente de datos de las herramientas de gráficos de Google, puedes dejar que la biblioteca se encargue de esto por ti.
  • Usa la autenticación de cookies para autenticar al cliente. No hay una forma conocida de inyectar encabezados personalizados a una solicitud de varios dominios, mientras se mantienen las cookies de autenticación.
  • Cuando JavaScript se incluya en una etiqueta <script src>, es poco probable que se ejecute JavaScript. Para hacer esto, agrega el prefijo de tu respuesta JSON con )]}', 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 solicitud

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

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

Aquí encontrarás 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 el formato de escape de URL antes de enviarse.

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 string de solicitud. Ten en cuenta que ambos nombres de parámetros (como "version") y los valores de string constantes (como "ok", "warning" y "not_Modified") distinguen mayúsculas de minúsculas. En la tabla, también se describe si se debe enviar el parámetro y, si se envía, si se requiere que lo maneje.

Parámetro
¿Obligatorio en la solicitud?
¿La fuente de datos debe manejar?
Descripción
tq
No
No

Una consulta escrita en el lenguaje de consulta de la API de visualización de Google y que especifica cómo filtrar, ordenar o manipular los datos mostrados. La string no necesita estar entre comillas.

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

tqx
No

Un conjunto de pares clave-valor delimitados por dos puntos para parámetros estándar o personalizados. Los pares se separan mediante punto y coma. Esta es una lista de los parámetros estándar definidos por el protocolo de visualización:

  • reqId: [Obligatorio en la solicitud: la fuente de datos debe manejar] Un identificador numérico para esta solicitud. Esto se usa de modo que si un cliente envía varias solicitudes antes de recibir una respuesta, la fuente de datos pueda identificar la respuesta con la solicitud adecuada. Envía este valor de vuelta en la respuesta.
  • version: [Opcional en la solicitud: la fuente de datos debe manejar] El número de versión del protocolo de visualización de Google. La versión actual es 0.6. Si no se envió, asume la versión más reciente.
  • sig: [Opcional en solicitud: opcional para que maneje la fuente de datos] Un hash del DataTable enviado a este cliente en cualquier solicitud anterior a esta fuente de datos. Esta es una optimización para evitar enviar datos idénticos a un cliente dos veces. Consulta Cómo optimizar tu solicitud a continuación para obtener información sobre cómo usar esto.
  • out [Opcional en la solicitud: la fuente de datos debe manejar] Una string que describe el formato de los datos que se muestran. Puede ser cualquiera de los siguientes valores:
    • json [valor predeterminado]: Es una string de respuesta JSON (como se describe a continuación).
    • html: Es una tabla HTML básica con filas y columnas. Si se usa, lo único que se debe mostrar es una tabla HTML con los datos; esto es útil para depurar, como se describe en la sección Formato de respuesta a continuación.
    • csv: valores separados por comas. Si se usa, solo lo que se muestra es una string de datos CSV. Puedes solicitar un nombre personalizado para el archivo en los encabezados de respuesta mediante la especificación de un parámetro outFileName.
    • tsv-excel: Es similar a csv, pero usa pestañas en lugar de comas y todos los datos están codificados en utf-16.
    Ten en cuenta que el único tipo de datos que un gráfico creado en la API de visualización de Google solicitará es JSON. Consulta Formato de la respuesta a continuación para obtener detalles sobre cada tipo.
  • responseHandler [Opcional en la solicitud: la fuente de datos debe controlar] El nombre de string de la función de control de JavaScript en la página cliente a la que se llamará con la respuesta. Si no se incluye en la solicitud, el valor es "google.visualization.Query.setResponse". Esto se enviará como parte de la respuesta; consulta Formato de respuesta a continuación para obtener información sobre cómo hacerlo.
  • outFileName (opcional para la solicitud; opcional para que la fuente de datos lo controle). Si especificas out:csv o out:tsv-excel, puedes solicitar de forma opcional el nombre de archivo especificado aquí. Ejemplo: outFileName=results.csv.

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

tqrt
No
No

Reservado: Ignora este parámetro. El método que se usó para enviar la consulta.

Formato de 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 de un objeto JavaScript que se pueden pasar directamente a un constructor DataTable para propagarlo. Este es, por lejos, el tipo de solicitud más común y la más importante para implementar de manera correcta.
  • CSV: Muestra una lista de valores separados por comas plana, que el navegador administrará.
  • TSV: Muestra una lista de valores separados por tabulaciones, para que el navegador la administre.
  • HTML: Muestra una tabla HTML que el navegador procesará.

Puedes usar la biblioteca de fuentes 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 de los gráficos de Google realmente admite una versión modificada de JSON y JSONP. Si usas las bibliotecas auxiliares Java o Python, se colocará el código adecuado para ti. Si analizas las respuestas a mano, consulta la sección Modificaciones 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 y respuestas JSON al final de esta página en Ejemplos. Puedes usar las bibliotecas auxiliares Java o Python para crear esta string de respuesta.

Este formato de respuesta es un objeto JSON codificado en UTF-8 (un objeto unido por llaves { } con cada propiedad separada por una coma) que incluye las propiedades en la tabla a continuación (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", deberías mostrar una string como la siguiente (solo se muestra una propiedad para abreviar):

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

Si la solicitud no incluyó un valor responseHandler, el valor predeterminado es "google.visualization.Query.setResponse", por lo que debes mostrar una string como la siguiente (solo se muestra una propiedad para abreviar):

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

Estos son los miembros del objeto de respuesta disponibles:

Propiedad
¿Obligatoria?
Descripción
version
No

Número de string que proporciona el número de versión del protocolo de cable de Visualización de Google Si no se especifica, el cliente adopta la versión más reciente.

Ejemplo: version=0.6.

ID de solicitud
SÍ*
Un número de string que indica el ID de esta solicitud para este cliente. Si se encontraba en la solicitud, muestra el mismo valor. Consulta la descripción de reqId en la sección de solicitud para obtener más detalles.

* Si este parámetro no se especificó en la solicitud, no tienes que configurarlo en la respuesta.
estado

Una string que describe el éxito o fracaso de esta operación. Debe ser uno y solo uno de los siguientes valores:

  • ok - Solicitud correcta. Se debe incluir una tabla en la propiedad table.
  • warning - Correcto, pero con problemas. Se debe incluir una tabla en la propiedad table.
  • error - Hubo un problema. Si lo haces, no debes mostrar table y debes mostrar errors.

Ejemplo: status:'warning'.

advertencias
Solo si status=warning

Un arreglo de uno o más objetos, cada uno de los cuales describe un problema recuperable. Es obligatorio si status=warning no está permitido. Cada objeto tiene las siguientes propiedades de string: muestra solo un valor para cada propiedad:

  • reason: Es una descripción de string de una palabra de la advertencia (obligatorio). El protocolo define los siguientes valores, pero, si es necesario, puedes definir tus propios valores (sin embargo, el cliente no procesará valores personalizados de ninguna manera especial). Solo puedes tener un valor de reason:
    • data_truncated: Se quitaron algunas filas del objeto DataTable que se mostró, ya sea porque el usuario incluyó una string de consulta que recortó la lista de resultados o porque la fuente de datos no quiso mostrar los resultados completos por algún motivo.
    • other: Es una advertencia genérica sin especificar.
  • message: Es una string entrecomillada que explica el problema, y se puede usar como título para un cuadro de alerta (opcional). Esto se puede mostrar al usuario. No se admite HTML.
  • detailed_message [Opcional] Un mensaje de string entre comillas detallado que explica el problema y las posibles soluciones. El único código HTML admitido es el elemento <a> con un único atributo href. Se admite la codificación Unicode. Esto se puede mostrar al usuario.

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

errores
Obligatorio si status=error

Un arreglo de uno o más objetos, cada uno de los cuales describe un error. Es obligatorio si status=error no está permitido. Esto es similar al valor warnings. Ten en cuenta que, aunque sea un error not_modified, no es un error para el cliente.

El arreglo tiene los siguientes miembros de string (muestra solo un valor para cada miembro):

  • reason ([obligatorio] Igual que warnings.reason, pero se definen los siguientes valores:
    • not_modified: Los datos no cambiaron desde la última solicitud. Si este es el motivo del error, no deberías tener un valor para table.
    • user_not_authenticated: si la fuente de datos requiere autenticación y todavía no se realizó, especifica este valor. Luego, el cliente mostrará una alerta con el valor message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other: Es un error genérico sin especificar.
  • message ([Opcional] Igual que warnings.message. Nota: Es posible que un usuario malicioso use una string de datos detallada para acceder a datos no autorizados o incluso atacarlos o atacar tu sitio. Si almacenas datos que deben ser seguros o procesas consultas de usuarios directamente, procura no mostrar un mensaje de error detallado que pueda proporcionar información a un atacante. En su lugar, proporciona un mensaje genérico, como "String de consulta incorrecta".
  • detailed_message ([Opcional] Igual que warnings.detailed_message. Consulta la advertencia para obtener información de message demasiado detallada.

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

sig
No

Un valor de hash del objeto de tabla. Es útil para optimizar la transferencia de datos entre el cliente y la fuente de datos. Puedes elegir el algoritmo de hash que desees. Si admites esta propiedad, debes mostrar el valor que pasó el cliente si no se muestran datos, o mostrar un hash nuevo si se muestran datos nuevos.

Ejemplo: sig:'5982206968295329967'.

tabla
No

Un objeto DataTable en notación literal de JavaScript, con tus datos. Consulta la sección de referencia vinculada para obtener detalles sobre el formato de este objeto. A continuación, se muestra un ejemplo de una tabla de datos sencilla:

{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 propiedad table solo debe estar presente si status=ok o status=warning. Si no muestras datos, no incluyas esta propiedad (es decir, no pases la propiedad con un valor de string vacío).

Ejemplo: Consulta los ejemplos que aparecen a continuación.

 

Se requiere un JSON estricto

Las bibliotecas auxiliares de Google y todas las consultas que se envían a Google muestran JSON/JSONP estrictos. Si no analizas el código que se muestra, no debería ser importante para ti. Si es así, puedes usar JSON.parse() para convertir la string JSON en un objeto JavaScript. Una diferencia en la manera en que la API procesa JSON es que, aunque JSON no admite valores de fecha de JavaScript (por ejemplo, "new Date(2008,1,28,0,31,26)"; la API admite una representación JSON válida de fechas como una string en el siguiente formato: Date(year, month, day[,hour, minute, second[, millisecond]]), en el que todo lo posterior al día es opcional, y los meses están basados en cero).

 

Cómo optimizar las respuestas JSON

Si un cliente realiza dos solicitudes y los datos no cambiaron entre ellas, tiene sentido no volver a enviar los datos; de lo contrario, se desperdiciaría el 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 muestra ambos 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 las siguientes dos maneras:
    • Si los datos cambiaron desde la solicitud anterior, la fuente de datos envía el nuevo hash DataTable y el nuevo valor sig.
    • Si los datos no cambiaron de la solicitud anterior, la fuente de datos devuelve status=error, reason=not_modified y sig=old_sig_value.
  5. En cualquier caso, la página que aloja el gráfico obtiene una respuesta exitosa y puede recuperar el DataTable llamando a QueryResponse.getDataTable(). Si los datos son los mismos, solo 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 CSV

Si en la solicitud se especifica out:csv, la respuesta no incluirá metadatos, sino solo una representación de los datos en formato CSV. 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 finaliza en un carácter de salto de línea de UNIX (\n). Los valores de las celdas deben tener el mismo tipo para cada columna. La primera fila son las etiquetas de columna. A continuación, se muestra 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 definir su formato CSV. 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 string CSV, podría preguntarle al usuario qué aplicación debe usar para abrir la string o simplemente procesarla en la pantalla. Las bibliotecas de código abierto de Java y Python proporcionan un método para convertir una tabla de datos 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 desea solicitar CSV, podrías incorporar un gadget de 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 forma 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 de TSV

Si en la solicitud se especifica out:tsv-excel, la respuesta no incluirá 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 en la solicitud se especifica out:html, la respuesta debe ser una página HTML que defina una tabla HTML con los datos. Esto es útil para depurar el código, ya que el navegador puede procesar el resultado directamente en un formato legible. No puedes enviar una consulta a una respuesta HTML con el objeto google.visualization.Query. Debes realizar una consulta para una respuesta HTML mediante 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. Por lo general, el navegador o el objeto google.visualization.Query hacen esto.

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 respuesta: 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 string de consulta simple: solicitud para una sola columna, que 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 todavía 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'}]});

String de consulta no válida: Ejemplo de una solicitud con una string de consulta no válida. Ten en cuenta que el mensaje detallado es un mensaje genérico, en lugar del 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): Se encarga de la solicitud y la respuesta, crea la tabla de respuesta a partir de los datos que le proporcionas e 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 de SQL de las herramientas de gráficos de Google.
  • MC-Google_Visualizacióntion (de terceros): Esta es una biblioteca del servidor PHP que puedes usar para implementar una fuente de datos de herramientas de gráficos para MySQL, SQLite, y motores de bases de datos de PostgreSQL mediante PDO.
  • bortosky-google-visualization (de terceros): Esta 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 en 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 (de terceros): TracGViz es una herramienta de código abierto gratuita que proporciona componentes para que Trac pueda usar gadgets de gráficos y también implementar datos administrados por Trac como fuente de datos de las herramientas de gráficos de Google.
  • vis-table (terceros): Es una biblioteca que implementa una fuente de datos de herramientas de gráficos de Google en PHP. Tiene tres partes principales. La implementación de la tabla de datos en sí, el analizador del lenguaje de consultas y los formateadores
  • Implementación de fuentes de datos de Google en Oracle PL/SQL (terceros): Un paquete de PL/SQL de Oracle que le permite a Oracle almacenar en servidores de origen de datos directamente desde la base de datos. Por lo tanto, puedes usar cualquier consulta de Oracle como una fuente de datos de las herramientas de los gráficos de Google (el paquete mostrará un archivo JSON con los datos). Tiene compatibilidad casi total con el lenguaje de consulta de Google.