Implementação do protocolo de fonte de dados de ferramentas de gráficos (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.

Conteúdo

Público

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

Esta página também é destinada a leitores interessados em entender o protocolo de transferência 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 precisará ler esta página.

Para ler este documento, você precisa entender a sintaxe básica das solicitações JSON e HTTP. Você também deve entender como os gráficos funcionam da perspectiva de um usuário.

Visão geral

Você pode implementar o protocolo da fonte de dados do Chart Tools para se tornar um provedor de fontes de dados para seus próprios gráficos ou de outros tipos. Uma fonte de dados do Chart Tools expõe um URL, chamado URL da fonte de dados, para o 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 o protocolo de transferência eletrônica da API de visualização do Google.

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

Como uma fonte de dados das ferramentas de gráficos, você precisa analisar uma solicitação em um formato específico e retornar uma resposta nesse formato. Isso pode ser feito de duas maneiras gerais:

• Use uma das seguintes bibliotecas auxiliares para processar a solicitação e a resposta, além de criar o DataTable a ser retornado. Se você usa uma dessas bibliotecas, precisa escrever apenas o código necessário para disponibilizar seus dados para a biblioteca na forma de uma tabela.
  • Biblioteca Java de fontes de dados: processa a solicitação e a resposta, cria a tabela de resposta com os dados fornecidos e implementa a linguagem de consulta SQL das Ferramentas de gráficos do Google.
  • Biblioteca de fontes de dados do Python: cria uma tabela de resposta que gera a sintaxe de resposta. Não lida com a análise da solicitação ou a implementação da linguagem de consulta SQL das Ferramentas de gráficos do Google.
    
    OU
    
    
• Escreva sua própria fonte de dados do zero processando a solicitação, construindo uma DataTable e enviando a resposta.

Como funciona:

1. A fonte de dados expõe um URL, chamado de URL da fonte de dados, a que 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 da solicitação.
4. A fonte de dados prepara os dados no formato solicitado. Normalmente, é uma tabela JSON. Os formatos de resposta são abordados na seção Formato de resposta. Opcionalmente, a fonte de dados pode ser compatível com a linguagem de consulta da API de visualização 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 da resposta.

Observação: todos os parâmetros e valores constantes de string listados neste documento para solicitações e respostas, como responseHandler e "ok", estão em letras minúsculas e diferenciam maiúsculas de minúsculas.

Requisitos mínimos

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

• A fonte de dados precisa aceitar solicitações HTTP GET e precisa estar disponível para os clientes.
• O protocolo pode mudar e é compatível com um esquema de versão (a versão atual é 0.6). Portanto, sua fonte de dados precisa aceitar solicitações que usam versões anteriores e a versão atual. Tente oferecer suporte às novas versões assim que elas forem lançadas para evitar prejudicar os clientes que fizerem upgrade para a versão mais recente rapidamente.
• Não falhe se propriedades desconhecidas forem enviadas como parte da solicitação. Isso ocorre porque as novas versões podem introduzir novas propriedades que você não conhece.
• Analise apenas as propriedades esperadas. As novas versões podem introduzir novas propriedades, mas não aceite e use toda a string de solicitação. Para se proteger contra ataques maliciosos, analise cuidadosamente e use apenas as propriedades esperadas.
• Documente os requisitos de fonte de dados com atenção se você não estiver codificando os gráficos de cliente. Isso inclui documentar as seguintes informações:
  • Todos os parâmetros personalizados que você aceitar,
  • Se você pode analisar ou não a linguagem de consulta da API de visualização do Google e
  • Que tipo de dados você retorna e a estrutura desses dados (o que as linhas e colunas representam, além de qualquer rotulagem).
• Tome todas as precauções de segurança padrão para um site que aceita solicitações de clientes desconhecidos. É possível 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 espera que os clientes estejam cientes dos seus requisitos e respondam a eles. No entanto, documente bem todos os seus requisitos se não estiver codificando os gráficos. Consulte Considerações de segurança abaixo.
• Todas as strings de solicitação e resposta precisam ser codificadas em UTF-8.
• O formato de resposta mais importante é JSON. Primeiro, implemente o JSON, já que 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 de visualização, mas isso torna sua fonte de dados mais útil para os clientes.
• Você não precisa oferecer suporte a solicitações de nenhum tipo de gráfico, mas pode aceitar parâmetros personalizados para gráficos personalizados. No entanto, você precisa retornar as respostas no formato padrão descrito abaixo.

Considerações sobre segurança

Ao projetar sua fonte de dados, você precisa considerar o nível de segurança deles. Você pode usar vários esquemas de segurança para o site, desde o simples acesso por senha até a autenticação segura por cookies.

Os ataques de inclusão de script em vários locais (XSSI, na sigla em inglês) são um risco nos gráficos. Um usuário pode navegar para uma página que contenha um script malicioso que começa a tentar fazer consultas aos URLs da fonte de dados usando as credenciais do usuário atual. Se o usuário não tiver feito logout de um site, o script será autenticado como o usuário atual e terá permissões no site. Com o uso de uma tag <script src>, o script malicioso pode incluir a fonte de dados, da mesma forma que o JSONP.

Como um nível extra de segurança, restrinja as solicitações àquelas provenientes do mesmo domínio da sua fonte de dados. Isso restringe consideravelmente a visibilidade da sua fonte de dados. No entanto, se você tiver dados muito sensíveis que não podem ser acessados de fora do seu domínio, pense nisso. Uma fonte de dados que só permite solicitações do mesmo domínio é chamada de fonte de dados restrita, ao contrário de uma fonte de dados irrestrita, que aceita consultas de qualquer domínio. Confira alguns detalhes sobre como implementar uma fonte de dados restrita:

Para garantir que uma solicitação realmente venha do seu domínio e não de um domínio externo (ou de um navegador dentro do domínio que está sob ataque XSRF):

• Verifique a presença de um cabeçalho "X-DataSource-Auth" na solicitação. Esse cabeçalho é definido pela API de visualização do Google. Você não precisa examinar o conteúdo dele, apenas verificar se ele está lá. Se você estiver usando a biblioteca de fonte de dados das Ferramentas de gráfico do Google, a biblioteca poderá cuidar disso para você.
• Use a autenticação de cookies para autenticar o cliente. Não há uma maneira conhecida de injetar cabeçalhos personalizados em uma solicitação de vários domínios mantendo os cookies de autenticação ativos.
• Torna o JavaScript improvável de ser executado quando incluído com uma tag <script src>. Para fazer isso, acrescente um prefixo à resposta JSON com )]}' seguido de uma nova linha. No seu cliente, remova o prefixo da resposta. Para XmlHttpRequest, isso só é possível quando a solicitação é originada 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, assinatura e outros elementos. Você é responsável apenas por analisar os parâmetros descritos nesta seção e precisa ter cuidado para não processar outros para evitar ataques maliciosos.

Verifique se você tem valores padrão para os parâmetros opcionais (padrão e personalizados) e documente todos os seus padrões na documentação do site.

Veja alguns exemplos de solicitações. Consulte mais exemplos de solicitação e resposta no final 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 de parâmetros (como "version") e valores de strings constantes (como "ok", "warning" e "not_modify") diferenciam maiúsculas de minúsculas. A tabela também descreve se o parâmetro precisa ser enviado e, se enviado, se você precisa processá-lo.

Formato da resposta

O formato da resposta depende do parâmetro out da solicitação, que especifica o tipo de resposta esperada. 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 de ser implementado corretamente.
• 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 ser processada pelo navegador.
• HTML: retorna uma tabela HTML a ser renderizada pelo navegador.

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

Formato da resposta JSON

O formato de resposta padrão será JSON se a solicitação incluir um cabeçalho "X-DataSource-Auth" e JSONP, caso contrário. O cliente dos gráficos do Google é compatível com versões modificadas de JSON e JSONP. Se você estiver usando as bibliotecas auxiliares Java ou Python, elas gerarão o código adequado. Se você analisar as respostas manualmente, consulte Modificações de JSON abaixo.

Se você estiver aplicando solicitações do 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 da API de visualização do Google google.visualization.Query.send() . Confira alguns exemplos de solicitações e respostas 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 unido ao valor de parâmetro responseHandler da solicitação. Portanto, se o valor responseHandler da solicitação era "myHandler", você deve retornar uma string como esta (somente uma propriedade é mostrada para concisão):

"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 (somente uma propriedade é mostrada para fins de brevidade):

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

Estes são os membros do objeto de resposta disponíveis:

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

Como otimizar respostas JSON

Se um cliente faz duas solicitações e os dados não mudam entre elas, faz sentido não reenviar os dados, porque isso desperdiçaria largura de banda. Para tornar as solicitações mais eficientes, o protocolo é compatível com o armazenamento em cache dos dados no cliente e com o envio de um sinal na resposta caso os dados não tenham sido alterados desde a última solicitação. Veja como funciona:

1. O cliente envia uma solicitação à fonte de dados.
2. A fonte de dados gera um DataTable e um hash do objeto DataTable e retorna ambos na resposta (o hash é retornado no parâmetro tqx.sig). O cliente da API de visualização do Google armazena em cache os valores DataTable e sig.
3. O cliente envia outra solicitação de dados, incluindo o valor tqx.sig armazenado em cache.
4. A fonte de dados pode responder de duas maneiras:
   • Se os dados tiverem sido alterados em relação à solicitação anterior, a fonte de dados retornará o novo DataTable e o novo hash do valor sig.
   • Se os dados da solicitação anterior não tiverem sido modificados, a fonte de dados enviará 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 DataTable chamando QueryResponse.getDataTable(). Se os dados forem os mesmos, serão apenas a versão armazenada em cache da tabela.

Isso só funciona para solicitações JSON de gráficos criados na API de visualização do Google.

Formato da resposta CSV

Se a solicitação especificar out:csv, a resposta não incluirá metadados, mas simplesmente uma representação CSV dos dados. Uma tabela CSV geralmente é 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 UNIX (\n). Os valores das células precisam ter o mesmo tipo em todas as colunas. A primeira linha contém os rótulos da coluna. Aqui está 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 um DataTable 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 uma solicitação de resposta CSV. Se um cliente quiser solicitar o CSV, você pode incorporar um gadget da barra de ferramentas de visualização à sua página, ou ele pode usar um código personalizado para criar a solicitação. Também é possível fornecer um link que defina explicitamente a propriedade out:csv de tqx, conforme mostrado no seguinte URL de solicitação:

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, mas apenas uma representação separada por tabulação dos dados, codificada 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 da resposta HTML

Se a solicitação especificar out:html, a resposta deverá ser uma página HTML que defina uma tabela HTML com os dados. Isso é útil para depurar o código, porque o navegador pode renderizar o resultado em um formato legível diretamente. Não é possível enviar uma consulta para uma resposta HTML usando o objeto google.visualization.Query. Crie uma consulta para receber uma resposta HTML usando um código personalizado ou digitando um URL semelhante a 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

Aqui estão alguns exemplos de solicitações e respostas. As solicitações não tiveram 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 resposta: retorna uma tabela de três colunas 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: solicitação de 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 data_truncated. Observe que 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. A mensagem detalhada é genérica, e não a mensagem de erro 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

• Biblioteca Java de fontes de dados (do Google): 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áficos do Google.
• Biblioteca de fontes de dados Python (do Google): cria uma tabela de resposta que gera a sintaxe de resposta. Não lida com a análise da solicitação ou a implementação da linguagem de consulta SQL das Ferramentas de gráficos do Google.
• MC-Google_Visualization (terceiros): é uma biblioteca PHP do lado do servidor que pode ser usada para implementar uma fonte de dados de ferramentas de gráficos para os mecanismos de banco de dados MySQL, SQLite e PostgreSQL usando PDO.
• bortosky-google-visualization (terceiro): é uma biblioteca auxiliar para criar uma tabela de dados da API de visualização do Google para usuários .NET.
• GV Streamer (terceiro): o GV Streamer é uma ferramenta do lado do servidor que pode converter dados de diferentes fontes em respostas de consulta válidas para os gráficos do Google. O GV Streamer é compatível com várias linguagens (por exemplo, PHP, Java, .NET) e diversas fontes de dados brutos (por exemplo, MySql).
• TracGViz (terceiro): o TracGViz é uma ferramenta de código aberto e sem custo financeiro que fornece componentes para que ele possa usar gadgets de gráficos e implementar dados gerenciados por ele como uma fonte de dados das Ferramentas de gráfico do Google.
• vis-table (terceiro): uma biblioteca que implementa uma fonte de dados das ferramentas de gráficos 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 Oracle PL/SQL que permite que o Oracle disponibilize fontes de dados diretamente do banco de dados. Basicamente, você pode usar qualquer consulta Oracle como uma fonte de dados das Ferramentas de gráfico do Google (o pacote retornará um arquivo JSON com os dados). e oferece suporte quase total para a linguagem de consulta do Google.