Consultas de dados

Nesta página, descrevemos como enviar uma consulta para uma fonte de dados compatível com o protocolo de fonte de dados das Ferramentas de gráfico.

Índice

  1. Visão geral
  2. Como enviar uma solicitação
  3. Como processar a resposta
  4. Como ler arquivos CSV
  5. Mais informações

Visão geral

A fonte de dados é um serviço da Web que oferece suporte ao protocolo de fonte de ferramentas de gráficos. Você pode enviar uma consulta SQL para uma fonte de dados e, em resposta, receber uma tabela de dados preenchida com as informações apropriadas. Alguns exemplos de fontes de dados são o Planilhas Google e o SalesForce.

Como enviar uma solicitação

Para enviar uma solicitação:

  1. Instancie um objeto Query com o URL da sua fonte de dados. O URL precisa indicar quais dados estão sendo solicitados, em uma sintaxe compreendida por essa fonte de dados.
  2. Também é possível especificar opções de solicitação, como o método de envio como um segundo parâmetro opcional no construtor de objeto Query. Consulte o parâmetro opt_options do construtor da consulta para mais detalhes:
  3. Se quiser, adicione uma string de idioma de consulta para classificar ou filtrar os resultados e envie a solicitação. As fontes de dados não são compatíveis com a linguagem de consulta de fonte de dados das Ferramentas de Gráfico. Se a fonte de dados não for compatível com a linguagem, ela vai ignorar a string de consulta SQL, mas ainda assim retornará uma DataTable. A linguagem de consulta é uma variante da SQL. Leia a sintaxe completa da linguagem de consulta.
  4. Envie a consulta, especificando um gerenciador de callback que será chamado quando a resposta for recebida. Veja os detalhes na próxima seção.

Veja um exemplo de envio de uma solicitação de dados em um intervalo de células do arquivo do Planilhas Google. Para saber como encontrar o URL de uma planilha do Google, consulte esta página: 

function initialize() {
  var opts = {sendMethod: 'auto'};
  // Replace the data source URL on next line with your data source URL.
  var query = new google.visualization.Query('http://spreadsheets.google.com?key=123AB&...', opts);

  // Optional request to return only column C and the sum of column B, grouped by C members.
  query.setQuery('select C, sum(B) group by C');

  // Send the query with a callback function.
  query.send(handleQueryResponse);
}

function handleQueryResponse(response) {
  // Called when the query response is returned.
  ...
}

Se você estiver enviando sua consulta do Apps Script, use o modo IFRAME.

Como processar a resposta

A função de gerenciador de respostas será chamada quando a solicitação for retornada. O parâmetro transmitido à função do gerenciador de respostas é do tipo google.visualization.QueryResponse. Se a solicitação foi bem-sucedida, a resposta contém uma tabela de dados (classe google.visualization.DataTable). Se a solicitação falhou, a resposta contém informações sobre o erro, e não DataTable.

O gerenciador de respostas precisa fazer o seguinte:

  1. Para verificar se a solicitação foi bem-sucedida ou não, chame response.isError(). Não é necessário mostrar mensagens de erro para o usuário. A Biblioteca de visualização exibirá uma mensagem de erro no contêiner <div>. No entanto, caso queira corrigir os erros manualmente, use a classe goog.visualization.errors para exibir mensagens personalizadas. Consulte o exemplo de wrapper de consulta para ver um exemplo de tratamento de erros personalizado.
  2. Se a solicitação for bem-sucedida, a resposta incluirá um DataTable que você pode recuperar chamando getDataTable(). Transmita-o para seu gráfico.

O código a seguir demonstra o processamento da solicitação anterior para desenhar um gráfico de pizza:

function handleQueryResponse(response) {

  if (response.isError()) {
    alert('Error in query: ' + response.getMessage() + ' ' + response.getDetailedMessage());
    return;
  }

  var data = response.getDataTable();
  var chart = new google.visualization.PieChart(document.getElementById('chart_div'));
  chart.draw(data, {width: 400, height: 240, is3D: true});
}

Como ler arquivos CSV

Se quiser criar um gráfico com base em dados CSV (valores separados por vírgula), você tem duas opções. Converta manualmente os dados CSV para o formato de tabela de dados do Google Charts ou coloque o arquivo CSV no servidor da Web que exibe o gráfico e consulte-o usando a técnica nesta página.

Mais informações