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.

Nota: Google no respalda oficialmente ni brinda asistencia a fuentes de datos que no sean de Google y que admitan el protocolo de fuentes de datos de herramientas de gráficos.

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

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

Consulta escrita en el lenguaje de consulta de la API de visualización de Google que especifica cómo filtrar, ordenar o manipular de otra manera los datos que se muestran. No es necesario que la cadena esté 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. A continuación, se incluye 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 controlar] Es un identificador numérico para esta solicitud. Esto se usa para 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 en la respuesta.
  • version: [Opcional en la solicitud; la fuente de datos debe controlar] el número de versión del Protocolo de visualización de Google. La versión actual es 0.6. Si no se envió, supone la versión más reciente.
  • sig: [Opcional en la solicitud; opcional para que la fuente de datos lo maneje] Es 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 usarla.
  • out: [opcional en la solicitud; la fuente de datos debe controlar] una cadena 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 (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 la depuración, como se describe en la sección Formato de respuesta a continuación.
    • csv: Valores separados por comas. Si se usa, lo único que se muestra es una cadena de datos CSV. Puedes solicitar un nombre personalizado para el archivo en los encabezados de respuesta si especificas 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 compilado en la API de visualización de Google solicitará es json. Consulta Formato de respuesta a continuación para obtener detalles sobre cada tipo.
  • responseHandler: [Opcional en la solicitud; la fuente de datos debe controlar] El nombre de la cadena 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 en la solicitud; opcional para que la fuente de datos lo maneje] Si especificas out:csv o out:tsv-excel, puedes solicitar 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. Es el método que se usó para enviar la consulta.

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:

Propiedad
¿Obligatorio?
Descripción
versión
No

Es un número de cadena que proporciona el número de versión del protocolo de cable de la Visualización de Google. Si no se especifica, el cliente asume la última versión.

Ejemplo: version=0.6.

reqId
Sí*
Un número de cadena que indica el ID de esta solicitud para este cliente. Si esto estuvo 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 no se especificó este parámetro en la solicitud, no es necesario que lo configures en la respuesta.
status

Es una cadena que describe el éxito o el fracaso de esta operación. Debe ser solo uno de los siguientes valores:

  • ok: Se realizó la solicitud. Se debe incluir una tabla en la propiedad table.
  • warning: Listo, pero con problemas. Se debe incluir una tabla en la propiedad table.
  • error - Ocurrió un problema. Si muestras esto, no debes mostrar table, sino errors.

Ejemplo: status:'warning'.

advertencias
Solo si status=warning

Es un array de uno o más objetos, cada uno de los cuales describe un problema recuperable. Es obligatorio si es status=warning; de lo contrario, no se permite. Cada objeto tiene las siguientes propiedades de cadena (muestra solo un valor para cada propiedad):

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

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

errores
Obligatorio si status=error

Un array de uno o más objetos, cada uno de los cuales describe un error. Es obligatorio si es status=error; de lo contrario, no se permite. Esto es similar al valor warnings. Ten en cuenta que el error not_modified, aunque sea un error, en realidad no es un error para el cliente.

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

  • reason - [Obligatorio] Igual que el 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 no se hizo, 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 no especificado.
  • message: [Opcional] Igual que warnings.message. Nota: Es posible que un usuario malicioso utilice una cadena de datos detallada como medio para acceder a datos no autorizados o incluso usarla para atacar tus datos o tu sitio. Si almacenas datos que deberían 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 "Cadena de consulta incorrecta".
  • detailed_message: [Opcional] Igual que warnings.detailed_message. Consulta la advertencia para obtener información demasiado detallada sobre message.

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

sig
No

Es un valor de hash del objeto de la tabla. Es útil para optimizar la transferencia de datos entre el cliente y la fuente de datos. Puedes elegir el algoritmo de hash que quieras. 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'.

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

Ejemplo: consulta la sección Ejemplos a continuación.

 

Se requiere un JSON estricto

Las bibliotecas auxiliares de Google y todas las consultas que se envían a Google muestran un formato JSON/JSONP estricto. Si no estás analizando el código que se muestra, esto no debería ser importante para ti. Si es así, puedes usar JSON.parse() para convertir la cadena JSON en un objeto de JavaScript. Una diferencia en la forma 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 las fechas como una cadena en el siguiente formato: Date(year, month, day[,hour, minute, second[, millisecond]]), donde todo después del día es opcional y los meses están basados en cero.

 

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.