Planilhas eletrônicas do Google

Esta página descreve como usar os Gráficos Google com as Planilhas Google.

Introdução

Os gráficos do Google e as Planilhas do Google são totalmente integrados. Você pode colocar um gráfico do Google dentro de uma planilha, e ele pode extrair dados de planilhas do Google. Esta documentação mostra como fazer ambos.

Seja qual for o método escolhido, o gráfico será alterado sempre que a planilha subjacente for alterada.

Como incorporar um gráfico a uma planilha

É fácil incluir um gráfico em uma planilha. Na barra de ferramentas das planilhas, selecione "Inserir" e "Gráfico". Assim, será possível escolher o tipo de gráfico e selecionar várias opções:

Criar um gráfico usando uma planilha separada

Normalmente, as pessoas criam gráficos do Google preenchendo uma tabela de dados e desenhando o gráfico com esses dados. Para recuperar os dados de uma planilha do Google, consulte a planilha para recuperar os dados do gráfico:

function drawChart() {
  var query = new google.visualization.Query(URL);
  query.send(handleQueryResponse);
}

function handleQueryResponse(response) {
  var data = response.getDataTable();
  var chart = new google.visualization.ColumnChart(document.getElementById('columnchart'));
  chart.draw(data, null);
}

Isso funciona porque as Planilhas do Google são compatíveis com a linguagem de consulta do Google Charts para classificar e filtrar dados. Qualquer sistema que ofereça suporte ao idioma da consulta pode ser usado como uma fonte de dados.

Os gráficos não podem usar os privilégios da pessoa que os visualiza sem autorização explícita. A planilha precisa estar visível para todos ou a página precisa adquirir explicitamente uma credencial de usuário final, conforme documentado na seção Autorização desta página.

Para usar uma planilha do Google como fonte de dados, você precisará do URL dela:

  1. Abra uma planilha existente. Essa planilha deve ter o formato esperado pela sua visualização e ter privilégios de visualização definidos corretamente. Ver os privilégios de "Público na Web" ou "Qualquer pessoa com o link" é mais fácil, e as instruções nesta seção pressupõem uma planilha que tenha sido configurada dessa forma. É possível restringir mantendo a planilha "Privada" e concedendo acesso individual a Contas do Google, mas você precisará seguir as instruções de autorização abaixo.
  2. Copie o URL do navegador. Consulte Intervalos de origem de consulta para ver detalhes sobre como selecionar intervalos específicos.
  3. Forneça o URL para google.visualization.Query(). A consulta é compatível com os seguintes parâmetros:
    • headers=N: especifica quantas linhas são de cabeçalho, em que N é um número inteiro zero ou maior. Eles serão excluídos dos dados e atribuídos como rótulos de coluna na tabela de dados. Se você não especificar esse parâmetro, a planilha vai prever quantas linhas são de cabeçalho. Se todas as colunas forem dados de string, a planilha poderá ter dificuldade em determinar quais linhas são de cabeçalho sem esse parâmetro.
    • gid=N: especifica qual página de um documento de várias páginas deve ser vinculada, se você não estiver vinculando à primeira página. N é o número de ID da página. Para saber o número do ID, acesse a versão publicada da página e procure o parâmetro gid=N no URL. Também é possível usar o parâmetro sheet em vez desse parâmetro. Gotcha:as planilhas do Google podem reorganizar o parâmetro gid no URL quando visualizado em um navegador. Ao copiar de um navegador, verifique se todos os parâmetros estão antes da marca # do URL. Exemplo: gid=1545912003.
    • sheet=sheet_name: especifica a qual página em um documento de várias páginas você está vinculando, se não estiver vinculando à primeira página. sheet_name é o nome de exibição da página. Exemplo: sheet=Sheet5.

Veja um exemplo completo:

Veja abaixo duas maneiras de desenhar esse gráfico, uma usando o parâmetro gid e a outra usando o parâmetro sheet. Inserir um desses URLs no navegador produz o mesmo resultado/dados para o gráfico.

ID do desenvolvedor
    function drawGID() {
      var queryString = encodeURIComponent('SELECT A, H, O, Q, R, U LIMIT 5 OFFSET 8');

      var query = new google.visualization.Query(
          'https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?gid=0&headers=1&tq=' + queryString);
      query.send(handleQueryResponse);
    }

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

      var data = response.getDataTable();
      var chart = new google.visualization.ColumnChart(document.getElementById('chart_div'));
      chart.draw(data, { height: 400 });
    }
Planilha
    function drawSheetName() {
      var queryString = encodeURIComponent('SELECT A, H, O, Q, R, U LIMIT 5 OFFSET 8');

      var query = new google.visualization.Query(
          'https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?sheet=Sheet1&headers=1&tq=' + queryString);
      query.send(handleSampleDataQueryResponse);
    }

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

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

Intervalos de origem da consulta

O URL de origem da consulta especifica qual parte de uma planilha será usada na consulta: uma célula específica, um intervalo de células, linhas ou colunas ou uma planilha inteira. Especifique o intervalo usando a sintaxe "range=<range_EXPRESS". Por exemplo:

https://docs.google.com/spreadsheets/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq?range=A1:C4
   

Veja alguns exemplos que demonstram a sintaxe:

  • A1:B10: intervalo da célula A1 até B10.
  • 5:7 – Linhas 5 a 7
  • D:F – colunas D-F
  • A:A70: as primeiras 70 células da coluna A
  • A70:A: coluna A da linha 70 até o fim
  • B5:5: B5 até o final da linha 5
  • D3:D: D3 até o fim da coluna D
  • C:C10: do início da coluna C até C10

Autorização

O app Planilhas Google exige credenciais de usuário final para acessar as planilhas privadas com a API Google Visualization ("solicitações tt").

Observação: as planilhas compartilhadas com a configuração "qualquer pessoa com o link pode ver" não exigem credenciais. É muito mais fácil alterar as configurações de compartilhamento da sua planilha do que implementar uma autorização.

Nos casos em que o compartilhamento de link não é uma solução viável, os desenvolvedores precisam mudar o código para transmitir uma credencial OAuth 2.0 autorizada para o escopo da API Google Sheets (https://www.googleapis.com/auth/spreadsheets).

Mais informações sobre o OAuth 2.0 estão disponíveis em Como usar o OAuth 2.0 para acessar as APIs do Google.

Exemplo: como usar o OAuth para acessar /gviz/tq

Pré-requisito: receber um ID do cliente do Google Developers Console

Veja instruções mais detalhadas para fazer a integração com o Identity Platform do Google em Login do Google e Como criar um projeto do Console de APIs do Google e um ID do cliente.

Para conseguir tokens OAuth para um usuário final, primeiro é necessário registrar seu projeto no Google Developer Console e adquirir um ID do cliente.

  1. No console para desenvolvedores, crie um novo ID do cliente OAuth.
  2. Escolha Aplicativo da Web como o tipo de aplicativo.
  3. Escolha qualquer nome, apenas para fins informativos.
  4. Adicione o nome do seu domínio e de qualquer domínio de teste como Origens JavaScript autorizadas.
  5. Deixe os URIs de redirecionamento autorizados em branco.

Depois de clicar em "Criar", copie o ID do cliente para referência futura. A chave secreta do cliente não é necessária para este exercício.

Atualize seu site para adquirir as credenciais do OAuth.

O Google fornece a biblioteca gapi.auth, que simplifica muito o processo de adição de uma credencial OAuth. A amostra de código abaixo usa essa biblioteca para adquirir uma credencial (solicitando autorização, se necessário) e transmite a credencial resultante para o endpoint /gviz/tq.

demo.html
<html>
<body>
  <button id="authorize-button" style="visibility: hidden">Authorize</button>
  <script src="./demo.js" type="text/javascript"></script>
  <script src="https://apis.google.com/js/auth.js?onload=init"></script>
</body>
</html>
demo.js (link em inglês)
// NOTE: You must replace the client id on the following line.
var clientId = '549821307845-9ef2xotqflhcqbv10.apps.googleusercontent.com';
var scopes = 'https://www.googleapis.com/auth/spreadsheets';

function init() {
  gapi.auth.authorize(
      {client_id: clientId, scope: scopes, immediate: true},
      handleAuthResult);
}

function handleAuthResult(authResult) {
  var authorizeButton = document.getElementById('authorize-button');
  if (authResult && !authResult.error) {
    authorizeButton.style.visibility = 'hidden';
    makeApiCall();
  } else {
    authorizeButton.style.visibility = '';
    authorizeButton.onclick = handleAuthClick;
  }
}

function handleAuthClick(event) {
  gapi.auth.authorize(
      {client_id: clientId, scope: scopes, immediate: false},
      handleAuthResult);
  return false;
}

function makeApiCall() {
  // Note: The below spreadsheet is "Public on the web" and will work
  // with or without an OAuth token.  For a better test, replace this
  // URL with a private spreadsheet.
  var tqUrl = 'https://docs.google.com/spreadsheets' +
      '/d/1XWJLkAwch5GXAt_7zOFDcg8Wm8Xv29_8PWuuW15qmAE/gviz/tq' +
      '?tqx=responseHandler:handleTqResponse' +
      '&access_token=' + encodeURIComponent(gapi.auth.getToken().access_token);

  document.write('<script src="' + tqUrl +'" type="text/javascript"></script>');
}

function handleTqResponse(resp) {
  document.write(JSON.stringify(resp));
}

Quando a autorização for concluída, gapi.auth.getToken() retornará todos os detalhes da credencial, incluindo o access_token que pode ser anexado às solicitações /gviz/tq.

Para mais informações sobre como usar a biblioteca gapi para autenticação, consulte:

Usar o escopo drive.file

O exemplo anterior usa o escopo da API Google Sheets, que concede acesso de leitura e gravação a todo o conteúdo da planilha de um usuário. Dependendo do aplicativo, isso pode ser mais permissivo do que o necessário. Para o acesso somente leitura, use o escopo spreadsheets.readonly, que concede acesso somente leitura às planilhas do usuário e suas propriedades.

O escopo do drive.file (https://www.googleapis.com/auth/drive.file) concede acesso somente aos arquivos que o usuário explicitamente abre com o seletor de arquivos do Google Drive, iniciado por meio da API Picker.

Usar o seletor altera o fluxo de seu aplicativo. Em vez de colar um URL ou ter uma planilha codificada, como no exemplo acima, o usuário precisa usar a caixa de diálogo do seletor para escolher qual planilha ele quer acessar. Siga o exemplo "Hello World" do seletor (link em inglês), usando google.picker.ViewId.SPREADSHEETS no lugar de google.picker.ViewId.PHOTOS.