Como implementar o protocolo de fonte de dados das ferramentas de gráfico (V0.6)

Nesta página, descrevemos como implementar um serviço compatível com o protocolo de fonte de dados das Ferramentas de gráfico para expor dados a gráficos usando a classe de consulta.

Índice

Público

Esta página é destinada principalmente a desenvolvedores que criam as próprias fontes de dados sem a ajuda da Biblioteca de fontes de dados das Ferramentas de gráfico. Se você estiver usando essa ou qualquer outra biblioteca auxiliar, primeiro leia a documentação da biblioteca.

Esta página também é destinada a leitores interessados em entender o protocolo de transmissão eletrônica usado para comunicação entre uma visualização do cliente e uma fonte de dados.

Se você estiver criando ou usando uma visualização, não será necessário ler esta página.

Para ler este documento, é preciso entender a sintaxe básica de solicitações HTTP e JSON. Você também deve compreender como os gráficos funcionam do ponto de vista do usuário.

Observação:o Google não apoia oficialmente nem aceita fontes de dados que não sejam do Google e sejam compatíveis com o protocolo de fontes de ferramentas do gráfico.

Visão geral

Você pode implementar o protocolo de fonte de dados das Ferramentas de Gráfico para se tornar um provedor de fonte de dados para seus próprios gráficos ou outros. Uma fonte de dados de ferramentas de gráfico expõe um URL, chamado de URL da fonte de dados, ao qual um gráfico pode enviar solicitações HTTP GET. Em resposta, a fonte de dados retorna dados formatados corretamente que o gráfico pode usar para renderizar o gráfico na página. Esse protocolo de solicitação/resposta é conhecido como protocolo de transferência da API Google Visualize.

Os dados veiculados por uma fonte podem ser extraídos de vários recursos, como um arquivo ou banco de dados. A única restrição é que é possível formatar os dados como uma tabela bidimensional com colunas digitadas.

Como uma fonte de dados de Ferramentas de Gráfico, você precisa analisar uma solicitação em um formato específico e retornar uma resposta em um formato específico. É possível fazer isso de duas maneiras gerais:

  • Use uma das seguintes bibliotecas auxiliares para processar a solicitação e a resposta, e crie a DataTable a ser retornada. Se você usa uma dessas bibliotecas, precisa escrever apenas o código necessário para disponibilizar os dados na biblioteca na forma de uma tabela.
    • Biblioteca Java Datasource: gerencia a solicitação e a resposta, cria a tabela de resposta com base nos dados fornecidos e implementa a linguagem de consulta SQL das Ferramentas de gráfico do Google.
    • Biblioteca de origem de dados Python: cria uma tabela de resposta que gera a sintaxe de resposta. não processa a análise da solicitação nem a implementação da linguagem de consulta SQL das ferramentas do gráfico do Google;

      OU

  • Escreva sua própria fonte de dados do zero lidando com a solicitação, construindo uma DataTable e enviando a resposta.

Como funciona:

  1. A fonte de dados expõe um URL, chamado URL de fonte de dados, ao qual os gráficos enviam uma solicitação HTTP GET.
  2. O cliente faz uma solicitação HTTP GET com parâmetros que descrevem qual formato usar para os dados retornados, uma string de consulta opcional e parâmetros personalizados opcionais.
  3. A fonte de dados recebe e analisa a solicitação, conforme descrito em Formato de solicitação.
  4. A fonte de dados prepara os dados no formato solicitado. Normalmente, ela é uma tabela JSON. Os formatos de resposta são abordados na seção Formato de resposta. A fonte de dados pode ser compatível com a linguagem de consulta da API dele, que especifica filtragem, classificação e outras manipulações de dados.
  5. A fonte de dados cria uma resposta HTTP que inclui os dados serializados e outros parâmetros de resposta e a envia de volta ao cliente, conforme descrito em Formato de resposta.

Observação: todos os parâmetros e valores de constante de string listados neste documento para solicitações e respostas (como responseHandler e "ok") são maiúsculos e diferenciam maiúsculas de minúsculas.

Requisitos mínimos

Estes são os requisitos mínimos para servir como fonte de dados de ferramentas de gráfico:

  • A fonte de dados deve aceitar solicitações HTTP GET e estar disponível para os clientes.
  • O protocolo pode mudar e aceitar um esquema de versão (a versão atual é 0.6). Portanto, a fonte de dados precisa aceitar solicitações que usam versões anteriores e a versão atual. Ofereça compatibilidade a novas versões assim que elas forem lançadas para evitar que os clientes façam upgrade para a versão mais recente rapidamente.
  • Não falhe se propriedades desconhecidas forem enviadas como parte da solicitação. Isso acontece porque as novas versões podem introduzir novas propriedades que você não conhece.
  • Analise apenas as propriedades esperadas. Embora novas versões possam introduzir novas propriedades, não aceite e use cegamente toda a string de solicitação. Para se proteger contra ataques maliciosos, analise e use com cuidado apenas as propriedades esperadas.
  • Documente seus requisitos de fonte de dados com cuidado se não estiver codificando os gráficos do cliente. Isso inclui a documentação do seguinte:
    • Todos os parâmetros personalizados aceitos
    • Você pode analisar a linguagem de consulta da API Google preview?
    • Os tipos de dados retornados e a estrutura desses dados (o que as linhas e colunas representam e qualquer rotulagem).
  • Tome todas as precauções de segurança padrão para um site que aceita solicitações de clientes desconhecidos. Você pode oferecer suporte razoável a MD5, hash e outros mecanismos de segurança nos seus parâmetros para autenticar solicitações ou ajudar a proteger contra ataques maliciosos e esperar que os clientes conheçam seus requisitos e respondam a eles. No entanto, documente bem todos os seus requisitos se você não estiver codificando os gráficos. Consulte Considerações sobre segurança abaixo.
  • Todas as strings de solicitação e resposta precisam ser codificadas em UTF-8.
  • O formato de resposta mais importante é JSON. Implemente JSON primeiro, porque esse é o formato usado pela maioria dos gráficos. Adicione outros tipos de resposta posteriormente.
  • Não é obrigatório oferecer suporte à linguagem de consulta da API, mas ela torna sua fonte de dados mais útil aos clientes.
  • Não é necessário aceitar solicitações de nenhum tipo de gráfico, nem de parâmetros personalizados. No entanto, é preciso retornar as respostas no formato padrão descrito abaixo.

Considerações sobre segurança

Ao projetar sua fonte de dados, você precisa considerar a segurança dos dados. É possível usar vários esquemas de segurança no seu site, desde o acesso simples à senha até a autenticação segura de cookies.

Ataques de scripting em vários locais (XSSI, na sigla em inglês) são um risco para gráficos. Um usuário pode navegar para uma página que contém um script malicioso que começa a fazer consultas para URLs de fonte de dados usando as credenciais do usuário atual. Se o usuário não tiver saído de um site, o script será autenticado como o usuário atual e terá as permissões necessárias. Usando uma tag <script src>, o script malicioso pode incluir a fonte de dados, semelhante ao JSONP.

Como um nível adicional de segurança, é possível restringir as solicitações provenientes do mesmo domínio da sua fonte de dados. Isso restringe consideravelmente a visibilidade da sua fonte de dados, mas, se você tiver dados muito confidenciais que não podem ser acessados de fora do domínio, considere-os. Uma fonte de dados que só permite solicitações do mesmo domínio é chamada de fonte de dados restrita, em vez de uma fonte de dados não restrita, que aceita consultas de qualquer domínio. Veja alguns detalhes sobre como implementar uma fonte de dados restrita:

Para garantir que a solicitação esteja realmente vindo do seu domínio e não de um domínio externo (ou de um navegador dentro do domínio que esteja sob ataque XSRF):

  • Verifique a presença de um cabeçalho "X-DataSource-Auth" na solicitação. Esse cabeçalho é definido pela API Google preview. Você não precisa examinar o conteúdo desse cabeçalho, apenas verificar se ele está lá. Se você estiver usando a biblioteca de origem de dados das Ferramentas de gráfico do Google, ela pode fazer isso para você.
  • Use a autenticação de cookie para autenticar o cliente. Não há uma maneira conhecida de injetar cabeçalhos personalizados em uma solicitação de vários domínios e manter os cookies de autenticação ativos.
  • Não execute o JavaScript quando ele for incluído com uma tag <script src>. Para fazer isso, use o prefixo )]} antes da sua resposta JSON, seguida de uma nova linha. No cliente, remova o prefixo da resposta. Para XMLHttpRequest, isso só é possível quando a solicitação se origina do mesmo domínio.

Formato da solicitação

Um cliente envia uma solicitação HTTP GET com vários parâmetros, incluindo elementos personalizados, uma string de consulta opcional, uma assinatura e outros elementos. Você é responsável apenas pela análise dos parâmetros descritos nesta seção e precisa ter cuidado para não lidar com outras pessoas e evitar ataques maliciosos.

Tenha valores padrão para os parâmetros opcionais (padrão e personalizado) e documente todos os padrões na documentação do site.

Veja alguns exemplos de solicitação (veja mais amostras de solicitações e respostas no fim deste documento em Exemplos):

Observação: as strings de solicitação a seguir e as mostradas na seção Exemplos precisam ter escape de URL antes do envio.

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

Veja a lista de todos os parâmetros padrão na string de solicitação. Os nomes dos parâmetros (como "version") e os valores de string constantes (como "ok", "warning" e "not_Modified") diferenciam maiúsculas de minúsculas. A tabela também descreve se o parâmetro precisa ser enviado e, se for enviado, se você precisa processá-lo.

Parâmetro
Obrigatório na solicitação?
A fonte de dados precisa processar?
Descrição
tq
Não
Não

Uma consulta escrita na linguagem de consulta da API Google preview, especificando como filtrar, classificar ou manipular os dados retornados. A string não precisa estar entre aspas.

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

txx
Não
Sim

Um conjunto de pares de chave-valor delimitados por dois-pontos para parâmetros padrão ou personalizados. Os pares são separados por ponto e vírgula. Veja uma lista dos parâmetros padrão definidos pelo protocolo de visualização:

  • reqId: [obrigatório na solicitação, a fonte de dados precisa processar] um identificador numérico para a solicitação. Isso é usado de modo que, se um cliente enviar várias solicitações antes de receber uma resposta, a fonte de dados poderá identificar a resposta com a solicitação apropriada. Envie esse valor de volta na resposta.
  • version - [opcional na solicitação; a fonte de dados precisa processar] o número da versão do protocolo de visualização do Google. A versão atual é 0.6. . Se não for enviada, considere a versão mais recente.
  • sig: [opcional na solicitação, opcional para a fonte de dados a ser processado] um hash do DataTable enviado a este cliente em todas as solicitações anteriores para essa fonte de dados. Essa é uma otimização para evitar o envio duplicado de dados idênticos a um cliente. Consulte Como otimizar sua solicitação abaixo para ver informações sobre como usá-la.
  • out: [opcional na solicitação, a fonte de dados precisa processar] Uma string que descreve o formato dos dados retornados. Pode ser qualquer um destes valores:
    • json: [valor padrão] uma string de resposta JSON (descrita abaixo).
    • html: uma tabela HTML básica com linhas e colunas. Se for usada, a única coisa que precisa ser retornada é uma tabela HTML com os dados. Isso é útil para depuração, conforme descrito na seção Formato de resposta abaixo.
    • csv: valores separados por vírgula. Se usado, o único resultado será uma string de dados CSV. Você pode solicitar um nome personalizado para o arquivo nos cabeçalhos de resposta especificando um parâmetro outFileName.
    • tsv-excel: semelhante a csv, mas usando guias em vez de vírgulas, e todos os dados são codificados em utf-16.
    O único tipo de dado que um gráfico criado na API Google Visualize vai solicitar é "json". Consulte o Formato de resposta abaixo para ver detalhes de cada tipo.
  • responseHandler: [opcional na solicitação; a fonte de dados precisa processar] O nome da string da função de tratamento do JavaScript na página do cliente que será chamada com a resposta. Se não estiver incluído na solicitação, o valor será "google.visualization.Query.setResponse". Ele será enviado de volta como parte da resposta. Consulte Formato de resposta abaixo para saber como.
  • outFileName: [opcional na solicitação e opcional para a fonte de dados. Se você especificar out:csv ou out:tsv-excel, será possível solicitar o nome do arquivo especificado aqui. Exemplo:outFileName=results.csv.

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

tqrt
Não
Não

Reservado: ignore este parâmetro. Método usado para enviar a consulta.

Formato da resposta

O formato da resposta depende do parâmetro out da solicitação, que especifica o tipo de resposta esperado. Consulte as seções a seguir para saber como responder a cada tipo de solicitação:

  • JSON: retorna uma resposta JSON que inclui os dados em um objeto JavaScript que pode ser transmitido diretamente para um construtor DataTable para preenchê-lo. Esse é de longe o tipo de solicitação mais comum e o mais importante para a implementação correta.
  • CSV: retorna uma lista simples de valores separados por vírgulas a ser processada pelo navegador.
  • TSV: retorna uma lista de valores separados por tabulação a serem processadas pelo navegador.
  • HTML: retorna uma tabela HTML a ser renderizada pelo navegador.

É possível usar a Biblioteca de fontes de dados da visualização do Google (java) ou a biblioteca Python de visualização para gerar esses formatos de saída.

Formato de resposta JSON

O formato de resposta padrão será JSON se a solicitação incluir um cabeçalho "X-DataSource-Auth", e JSONP em outros casos. Observe que o cliente de gráficos do Google é compatível com uma versão modificada de JSON e JSONP. Se você estiver usando as bibliotecas auxiliares Java ou Python, elas mostrarão o código adequado. Se você estiver analisando respostas manualmente, consulte Modificações JSON abaixo.

Se você estiver aplicando solicitações de mesmo domínio, verifique a presença do cabeçalho "X-DataSource-Auth" na solicitação e use cookies de autorização.

Esse é o único formato de resposta especificado pelo método google.visualization.Query.send() da API Google preview. Veja alguns exemplos de solicitações e respostas de JSON no final desta página em Exemplos. É possível usar as bibliotecas auxiliares Java ou Python para criar essa string de resposta para você.

Esse formato de resposta é um objeto JSON codificado em UTF-8 (um objeto entre chaves { } com cada propriedade separada por uma vírgula) que inclui as propriedades na tabela abaixo (os dados são atribuídos à propriedade table). Esse objeto JSON precisa ser encapsulado dentro do valor do parâmetro responseHandler da solicitação. Portanto, se o valor responseHandler da solicitação fosse "myHandler", você precisa retornar uma string como esta (apenas uma propriedade mostrada para ser resumida):

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

Se a solicitação não incluir um valor responseHandler, o valor padrão será "google.visualization.Query.setResponse". Portanto, retorne uma string como esta (apenas uma propriedade mostrada para ser resumida):

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

Veja os membros do objeto de resposta disponíveis:

Propriedade
Obrigatório?
Descrição
version
Não

Um número de string que informa o número da versão do protocolo de transmissão da visualização do Google. Se não for especificado, o cliente assumirá a versão mais recente.

Exemplo: version=0.6.

reqId
Sim*
Um número de string que indica o ID desta solicitação deste cliente. Se isso estiver na solicitação, retorne o mesmo valor. Consulte a descrição de reqId na seção de solicitação para mais detalhes.

* Se esse parâmetro não for especificado na solicitação, você não precisará configurá-lo na resposta.
status
Sim

Uma string que descreve o sucesso ou a falha dessa operação. Precisa ser apenas um dos seguintes valores:

  • ok: solicitação enviada. Uma tabela precisa ser incluída na propriedade table.
  • warning - Tudo bem, mas com problemas. Uma tabela precisa ser incluída na propriedade table.
  • error - Ocorreu um problema. Se isso for retornado, não retorne table e será necessário retornar errors.

Exemplo: status:'warning'.

avisos
Somente se status=warning

Uma matriz com um ou mais objetos, cada um descrevendo um problema não fatal. Obrigatório se status=warning, não permitido. Cada objeto tem as seguintes propriedades de string (retorna apenas um valor para cada propriedade):

  • reason - [obrigatório] é uma descrição de string de uma palavra do aviso. O protocolo define os valores a seguir, mas você pode definir seus próprios valores, mas o cliente não processará valores personalizados de nenhuma maneira especial. É possível ter apenas um valor reason:
    • data_truncated: o DataTable retornado teve algumas linhas removidas, seja porque o usuário incluiu uma string de consulta que cortou a lista de resultados, ou porque a fonte de dados não queria retornar resultados completos por algum motivo.
    • other: um aviso genérico não especificado.
  • message - [opcional] uma string entre aspas curta que explica o problema, possivelmente usada como título para uma caixa de alerta. Ela pode ser exibida ao usuário. Não há suporte para HTML.
  • detailed_message - [opcional] uma mensagem de string detalhada entre aspas explicando o problema e as possíveis soluções. O único HTML compatível é o elemento <a> com um único atributo href. A codificação Unicode é compatível. Ela pode ser exibida ao usuário.

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

erros
Obrigatório se status=error

Uma matriz com um ou mais objetos, cada um descrevendo um erro. Obrigatório se status=error, não permitido. Isso é semelhante ao valor warnings. Embora o erro not_modified não seja um erro do cliente.

A matriz tem os seguintes membros de string (retorna apenas um valor para cada membro):

  • reason - [obrigatório] O mesmo que warnings.reason, mas os seguintes valores são definidos:
    • not_modified: os dados não mudaram desde a última solicitação. Se esse for o motivo do erro, você não deve ter um valor para table.
    • user_not_authenticated: se a fonte de dados exigir autenticação e ela não tiver sido feita, especifique esse valor. O cliente exibirá um alerta com o valor de message.
    • unknown_data_source_id
    • access_denied
    • unsupported_query_operation
    • invalid_query
    • invalid_request
    • internal_error
    • not_supported
    • illegal_formatting_patterns
    • other: erro genérico não especificado.
  • message - [Opcional] O mesmo que warnings.message. Observação:um usuário mal-intencionado pode usar uma string de dados detalhada como meio de acessar dados não autorizados ou até mesmo usá-la para atacar seus dados ou o site. Se você armazenar dados que precisam ser seguros ou processar consultas de usuários diretamente, considere não retornar uma mensagem de erro detalhada que possa fornecer informações a um invasor. Em vez disso, passe uma mensagem genérica, como "String de consulta incorreta".
  • detailed_message - [Opcional] O mesmo que warnings.detailed_message. Veja o aviso para informações message muito detalhadas.

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

sig
Não

Um valor de hash do objeto de tabela. Útil para otimizar a transferência de dados entre o cliente e a fonte de dados. Você pode escolher qualquer algoritmo de hash. Se você aceitar essa propriedade, retorne o valor transmitido pelo cliente se nenhum dado for retornado ou um novo hash se novos dados forem retornados.

Exemplo: sig:'5982206968295329967'.

tabela
Não

Um objeto DataTable na notação literal de JavaScript, com seus dados. Consulte a seção de referência vinculada para ver detalhes sobre o formato deste objeto. Veja um exemplo de uma tabela de dados simples:

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

A propriedade table só vai estar presente se status=ok ou status=warning. Se você não retornar dados, não inclua essa propriedade (ou seja, não transmita a propriedade com um valor de string vazio).

Exemplo: consulte os exemplos abaixo.

 

JSON obrigatório

As bibliotecas auxiliares e todas as consultas enviadas ao Google retornam JSON/JSONP rígidos. Se você não estiver analisando o código retornado, isso não importa para você. Se estiver, use JSON.parse() para converter a string JSON em um objeto JavaScript. Uma diferença em como o JSON é processado pela API é que, embora o JSON não aceite valores de data JavaScript (por exemplo, "new Date(2008,1,28,0,31,26)". A API oferece suporte a uma representação JSON válida de datas como uma string no seguinte formato: Date(year, month, day[,hour, minute, second[, millisecond]]), em que tudo é opcional após os dias e meses são baseados em zero.

 

Como otimizar respostas JSON

Se um cliente fizer duas solicitações e os dados não tiverem mudado entre elas, não faz sentido reenviar os dados, já que isso desperdiçaria largura de banda. Para tornar as solicitações mais eficientes, o protocolo permite o armazenamento em cache dos dados no cliente e o envio de um sinal na resposta se os dados não tiverem mudado desde a última solicitação. Veja como funciona:

  1. O cliente envia uma solicitação para a fonte de dados.
  2. A fonte de dados gera um DataTable, bem como um hash do objeto DataTable, e retorna ambos na resposta (o hash é retornado no parâmetro tqx.sig). O cliente da API Google preview armazena em cache os valores DataTable e sig.
  3. O cliente envia outra solicitação de dados, incluindo o valor de tqx.sig armazenado em cache.
  4. A fonte de dados pode responder de duas maneiras:
    • Se os dados tiverem mudado em relação à solicitação anterior, a fonte de dados enviará de volta o novo hash de valor DataTable e sig.
    • Se os dados não tiverem sido alterados em relação à solicitação anterior, a fonte de dados retornará status=error, reason=not_modified, sig=old_sig_value.
  5. Em ambos os casos, a página que hospeda o gráfico recebe uma resposta bem-sucedida e pode recuperar o DataTable chamando QueryResponse.getDataTable(). Se os dados forem os mesmos, será a versão em cache da tabela.

Isso só funciona para solicitações JSON de gráficos criados na API Google preview.

Formato de resposta CSV

Se a solicitação especificar out:csv, a resposta não incluirá metadados, apenas uma representação CSV dos dados. Uma tabela CSV normalmente é uma lista separada por vírgulas, em que cada linha de dados é uma lista de valores separados por vírgulas, terminando em um caractere de nova linha do UNIX (\n). Os valores das células precisam ter o mesmo tipo de coluna. A primeira linha são os rótulos de colunas. Veja um exemplo de uma tabela de três linhas e três colunas:

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

O formato CSV não é especificado por esse protocolo. A fonte de dados é responsável por definir o formato CSV. No entanto, um formato comum é um conjunto de valores separados por vírgulas (sem espaços intermediários) e uma nova linha (\n) no final de cada linha. Quando um navegador recebe uma resposta de string CSV, ele pode perguntar ao usuário qual aplicativo usar para abrir a string ou simplesmente renderizá-la na tela. As bibliotecas de código aberto Java e Python oferecem um método para converter uma tabela de dados em uma string CSV.

Se a solicitação incluir um membro outFileName do parâmetro tqx , tente incluir o nome do arquivo especificado nos cabeçalhos de resposta.

O objeto google.visualization.Query não aceita solicitações de resposta CSV. Se um cliente quiser solicitar o CSV, você pode incorporar um widget de visualização da Barra de Ferramentas na sua página ou usar um código personalizado para criar a solicitação. Outra opção é fornecer um link que defina explicitamente a propriedade out:csv do tqx, conforme mostrado no URL da solicitação a seguir:

Solicitação

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

Resposta

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

Formato da resposta TSV

Se a solicitação especificar out:tsv-excel, a resposta não incluirá metadados, apenas uma representação separada por tabulação dos dados, codificado em utf-16. Se a solicitação incluir um membro outFileName do parâmetro tqx , tente incluir o nome do arquivo especificado nos cabeçalhos de resposta.

Formato de resposta HTML

Se a solicitação especificar out:html, a resposta será uma página HTML que define uma tabela HTML com os dados. Isso é útil para depurar o código, porque o navegador pode renderizar o resultado diretamente em um formato legível. Não é possível enviar uma consulta para uma resposta HTML usando o objeto google.visualization.Query. Você precisa fazer uma consulta para uma resposta HTML usando código personalizado ou digitando um URL parecido com este no navegador:

Solicitação

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

Resposta

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

Exemplos

Veja alguns exemplos de solicitações e respostas. As solicitações não têm escape de URL. Isso geralmente é feito pelo navegador ou pelo objeto google.visualization.Query.

Solicitação simples: retorna as informações básicas com uma tabela de três colunas e quatro linhas.

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

Solicitação simples com um gerenciador de respostas: retorna uma coluna de três linhas e três linhas com diferentes tipos de dados.

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 com uma string de consulta simples: a solicitação para uma única coluna retorna uma única coluna com quatro linhas.

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

Erro de dados não modificados: exemplo de um erro 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'}]});

Aviso de dados truncados:exemplo de um aviso de data_truncated. A solicitação ainda retorna dados.

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

Erro de acesso negado: exemplo de um erro 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 inválida:exemplo de uma solicitação com uma string de consulta inválida. Observe que a mensagem detalhada é genérica, e não 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.'}]});

Ferramentas para Desenvolvedores

  • Java Datasource Library (do Google): processa a solicitação e a resposta, cria a tabela de resposta com base nos dados fornecidos e implementa a linguagem de consulta SQL das ferramentas do gráfico do Google.
  • Biblioteca de origem de dados Python (do Google) - cria uma tabela de resposta que gera a sintaxe de resposta. não processa a análise da solicitação nem a implementação da linguagem de consulta SQL das Ferramentas de gráfico do Google;
  • MC-Google_Visualização (terceiros): esta é uma biblioteca do lado do servidor PHP que você pode usar para implementar uma fonte de dados de ferramentas de gráfico para mecanismos de banco de dados MySQL, SQLite e PostgreSQL usando PDO.
  • bortosky-google-visualization (terceiros): esta é uma biblioteca auxiliar para criar uma tabela de dados da API de visualização do Google para usuários do .NET.
  • GV Streamer: terceiros são uma ferramenta do lado do servidor que pode converter dados de diferentes fontes em respostas válidas de consulta a gráficos do Google. O GV Streamer é compatível com várias linguagens (por exemplo, PHP, Java, .NET) e com várias fontes de dados brutos (por exemplo, MySQL).
  • TracGViz (terceiro): o TracGViz é uma ferramenta sem custo financeiro e de código aberto que fornece componentes para que o Trac possa usar os gadgets de gráficos e também para implementar dados gerenciados pelo Trac como fonte de dados do Google Chart Tools.
  • vis-table (terceiros): uma biblioteca que implementa uma fonte de dados de ferramentas do gráfico do Google em PHP. Ele tem três partes principais. A própria implementação da tabela de dados, o analisador da linguagem de consulta e os formatadores.
  • Implementação da fonte de dados do Google no Oracle PL/SQL (terceiros): um pacote PL/SQL do Oracle que permite que o Oracle processe fontes de dados diretamente do banco de dados. Portanto, é possível usar qualquer consulta Oracle como fonte de dados das Ferramentas de gráfico do Google (o pacote retornará um arquivo JSON com os dados). Ele tem compatibilidade quase total com a linguagem de consulta do Google.