Planilhas eletrônicas do Google

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

  1. Introdução
  2. Como incorporar gráficos em planilhas
  3. Como criar um gráfico usando uma planilha separada

Introdução

Os gráficos e as planilhas do Google estão totalmente integrados. Você pode colocar um gráfico do Google dentro de uma planilha do Google, e o Google Charts pode extrair dados das planilhas do Google. Nesta documentação, mostramos 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

Incluir um gráfico em uma planilha é fácil. Na barra de ferramentas das Planilhas, selecione "Inserir" e, em seguida, "Gráfico". Você poderá escolher o tipo de gráfico e selecionar várias opções:

Como criar um gráfico a partir de uma planilha separada

Normalmente, para criar gráficos do Google, as pessoas preenchem uma tabela de dados e desenham o gráfico usando esses dados. Se, em vez disso, você quiser recuperar os dados de uma planilha do Google, você consulta a planilha para recuperar os dados a serem representados no 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 Google têm suporte à linguagem de consulta do Google Charts para classificar e filtrar dados. Qualquer sistema compatível com essa linguagem pode ser usado como 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 Google como fonte de dados, é necessário ter seu URL:

  1. Abra uma planilha já criada. Ela precisa ter o formato esperado pela sua visualização e os privilégios de visualização definidos corretamente. Os privilégios de visualização "Público na Web" ou "Qualquer pessoa com o link" são os mais fáceis, e as instruções nesta seção consideram uma planilha configurada dessa forma. Para restringir, mantenha a planilha "Particular" e conceda acesso a Contas do Google individuais, mas será necessário seguir as instruções de autorização abaixo.
  2. Copie o URL do navegador. Consulte Intervalos de origem da consulta para detalhes sobre como selecionar intervalos específicos.
  3. Forneça o URL para google.visualization.Query(). A consulta aceita os seguintes parâmetros opcionais:
    • headers=N: especifica quantas linhas são de cabeçalho, em que N é um número inteiro zero ou maior. Elas serão excluídas dos dados e atribuídas como rótulos de coluna na tabela de dados. Se você não especificar esse parâmetro, a planilha adivinhará 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 a qual página de um documento de várias folhas vincular, se você não estiver vinculando a primeira página. N é o número de ID da planilha. Para saber o número do ID, navegue até a versão publicada da planilha e procure o parâmetro gid=N no URL. Também é possível usar o parâmetro sheet em vez deste. Gotcha: as Planilhas Google podem reorganizar o parâmetro gid no URL quando visualizado em um navegador. Se você 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 de um documento de várias folhas você está criando o link, caso não esteja 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 outra usando o parâmetro sheet. Inserir qualquer um dos URLs no navegador produzirá os mesmos resultados/dados para o gráfico.

GID
    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 });
    }
Página
    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 usar na consulta: uma célula específica, um intervalo de células, linhas ou colunas, ou a planilha inteira. Especifique o intervalo usando a sintaxe "range=<range_expr>", por exemplo:

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

Aqui estão alguns exemplos que demonstram a sintaxe:

  • A1:B10 - um intervalo das células de A1 a B10
  • 5:7 - Linhas 5-7
  • D:F - Colunas D-F
  • A:A70 - as primeiras 70 células na 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 final da coluna D
  • C:C10 - do início da coluna C até C10

Autorização

O Planilhas Google exige credenciais de usuário final para acessar planilhas particulares por meio da API Google Visualization ("/tq requests").

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

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

Para mais informações sobre o OAuth 2.0, consulte Como usar o OAuth 2.0 para acessar as APIs do Google.

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

Pré-requisito: obter um ID do cliente no Google Developer Console

Instruções mais detalhadas sobre a integração com o Identity Platform do Google podem ser encontradas no Login do Google e em Como criar um projeto e um ID do cliente no Console de APIs do Google.

Para adquirir tokens OAuth para um usuário final, primeiro registre seu projeto no Google Developer Console e adquira um ID do cliente.

  1. No Play Console, crie um novo ID do cliente OAuth.
  2. Escolha Aplicativo da Web como o tipo.
  3. Escolha qualquer nome, pois ele é apenas para sua informação.
  4. Adicione o nome do seu domínio e de todos os domínios de teste como Origens do 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 credenciais OAuth.

O Google fornece a biblioteca gapi.auth, que simplifica muito o processo de adquirência de uma credencial OAuth. O exemplo 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 
// 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 bem-sucedida, gapi.auth.getToken() retornará todos os detalhes da credencial, incluindo o access_token que pode ser anexado a solicitações /gviz/tq.

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

Como 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 abrangente do que o necessário. Para acesso somente leitura, use o escopo spreadsheets.readonly, que concede acesso somente leitura às planilhas do usuário e às propriedades dele.

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

Usar o seletor altera o fluxo do 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 a planilha que a página vai acessar. Siga o exemplo do seletor "Hello World", usando google.picker.ViewId.SPREADSHEETS no lugar de google.picker.ViewId.PHOTOS.