O que é GAS (Google Apps Script)?
Guia para automatizar o Planilhas Google

O GAS é a forma do Google de executar programas. Ele usa a mesma sintaxe do JavaScript e trabalha com o Planilhas Google e também com Gmail, Google Agenda, Google Drive e Formulários Google.

Basta uma conta do Google. É gratuito e não precisa instalar nada: abra uma planilha no navegador e comece a escrever. O programa roda nos servidores do Google, não no seu computador.

O Planilhas Google tem "macros", que gravam o que você faz para repetir quantas vezes quiser. Comece a gravar em "Extensões" → "Macros" → "Gravar macro", selecione e digite em células, e suas ações são salvas como código GAS.

/** @OnlyCurrentDoc */

function myFunction() {
  var spreadsheet = SpreadsheetApp.getActive();
  spreadsheet.getRange('B2').activate();
  spreadsheet.getCurrentCell().setValue('test');
  spreadsheet.getActiveRangeList().setFontWeight('bold');
};

Ou seja, uma macro é GAS por dentro. Mesmo que você dê um nome como "Teste negrito", a função no código se chama myFunction. O nome no menu e o nome da função são guardados separadamente.

Ao gravar, você escolhe na barra de baixo "Usar referências absolutas" ou "Usar referências relativas". As absolutas são salvas como endereços (B2), então a macro escreve sempre no mesmo lugar, qualquer que seja a célula selecionada. As relativas são salvas como "uma linha abaixo da célula atual" e partem da célula selecionada.

Só gravando não dá para lidar com tabelas de tamanho variável nem com passos que dependem de condições. Daí em diante, você lê o código gravado e completa.

• Apagar as linhas vazias de dados colados e formatar os cabeçalhos
• Olhar valores ou datas e escrever "Grande" ou "Vencido" em uma coluna
• Adicionar um menu próprio à planilha e rodar tarefas como em um botão
• Criar funções próprias para usar nas células (funções personalizadas)
• Enviar e-mails pelo Gmail com base em uma tabela
• Rodar uma tarefa em horário fixo, por exemplo toda manhã às 8h (acionadores)
• Copiar para outra página as respostas do Formulários Google assim que chegam

À mão, cada uma dessas tarefas leva de alguns minutos a dezenas de minutos. Escrita uma vez, depois basta clicar em um menu, ou ela roda sozinha.

1. Abra a planilha e escolha "Extensões" → "Apps Script"
2. O editor abre em uma nova guia: "Código.gs" à esquerda e function myFunction() { } à direita
3. Escreva o código dentro de { } e salve (Ctrl+S, ⌘+S no Mac)
4. Clique em "▷ Executar" no alto. O resultado aparece embaixo, no "Registro de execução"

function myFunction() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const value = sheet.getRange('A1').getValue();
  Logger.log(value);
  sheet.getRange('B1').setValue('Verificado');
}

Logger.log escreve um valor no registro de execução. Os números aparecem com ponto decimal, por exemplo 120.0 (console.log mostra 120). Se algo não funcionar como esperado, confira primeiro os valores no registro.

Na primeira vez que você executa seu código, aparece uma tela perguntando se o script pode ler e editar sua planilha. Muita gente trava aqui, então vamos passo a passo.

1. "Autorização necessária" → Revisar permissões / OK
2. Escolher uma conta
3. "O Google não verificou este app" → "Avançado" no canto inferior esquerdo
4. "Acessar (nome do projeto) (não seguro)"
5. Confira o que está permitindo e clique em "Permitir" (se houver itens para selecionar, selecione e clique em "Continuar")

"O Google não verificou este app" é um aviso mostrado para scripts que o Google não revisou. Os scripts que você escreve e as macros que você grava não são revisados, então essa tela sempre aparece. Se foi você que criou, pode continuar sem problema.

Por outro lado, se essa tela aparecer em uma planilha que um desconhecido lhe passou, escolha "Voltar à segurança". Depois de permitido, o script pode mexer nas suas planilhas e e-mails usando a sua conta.

Se você colocar /** @OnlyCurrentDoc */ no início do código, o script só pode mexer "nesta planilha" e as permissões pedidas ficam mais restritas. As macros gravadas já vêm com isso.

Você pode fazer os mesmos passos na missão 1 da prática.

Aqui está o que mais se usa ao trabalhar com uma planilha. Os números de linha e coluna começam em 1, e os índices de uma matriz lida com getValues começam em 0.

function judgeTargets() {
  const sheet = SpreadsheetApp.getActiveSheet();
  for (let row = 2; row <= sheet.getLastRow(); row++) {
    const sales = sheet.getRange(row, 2).getValue();
    const target = sheet.getRange(row, 3).getValue();
    if (sales >= target) {
      sheet.getRange(row, 4).setValue('Atingido');
    } else {
      sheet.getRange(row, 4).setValue('Não atingido');
    }
  }
}

function onOpen() {
  SpreadsheetApp.getUi()
    .createMenu('Fechamento mensal')
    .addItem('Marcar vendas grandes', 'markLarge')
    .addToUi();
}

Uma função chamada onOpen roda automaticamente quando a planilha é aberta. Se você a executar com "▷ Executar" no editor, aparece o erro Cannot call SpreadsheetApp.getUi() from this context., então salve e abra a planilha de novo para conferir.

Os temas mais pesquisados sobre GAS são o envio de e-mails e os acionadores.

function sendReminders() {
  const sheet = SpreadsheetApp.getActiveSheet();
  const rows = sheet.getRange(2, 1, sheet.getLastRow() - 1, 2).getValues();
  rows.forEach(([name, email]) => {
    MailApp.sendEmail(email, 'Aviso de prazo de entrega', name + ',\n\no prazo de entrega é nesta sexta-feira.');
  });
}

Há um limite de envio: uma conta gratuita do Google pode enviar até 100 e-mails por dia (contas do Google Workspace, mais). Cada execução dura no máximo 6 minutos; depois disso, para com "Exceeded maximum execution time".

Para agendar, clique à esquerda do editor em "Acionadores" (ícone de relógio) → "Adicionar acionador" e escolha a função e "Baseado no tempo". Dá para definir uma faixa de horário todo dia, semana ou mês.

Os e-mails são enviados de verdade mesmo quando você só está testando. Teste primeiro com uma tabela que tenha apenas o seu próprio endereço.

As ideias são as mesmas nos dois: ler células, escrever, repetir e separar por condições. Quem sabe um consegue ler o outro. As macros do Excel estão na nossa introdução às macros do Excel.

Na simulação de macros e GAS deste site, você pratica executando código real em uma planilha e em um editor do Apps Script virtuais. Você preenche lacunas no código e, no celular, escolhe cada lacuna entre quatro opções.

1. Capítulo 1 Gravar e executar macros

   Executar uma macro gravada e gravar a sua. Referências absolutas e relativas, como ler e corrigir o código gravado.

2. Capítulo 2 Ler, repetir, separar

   Ler células com getValue, escrever com setValue e conferir valores no registro de execução. Percorrer todas as linhas com for e separar com if.

3. Capítulo 3 Estudo de caso: organizar a tabela de vendas do mês

   Apagar linhas vazias, marcar as vendas grandes de uma vez e rodar tudo a partir de um menu próprio. Por fim, sua própria função para as células.

Começar a simulação (13 missões) →

Um bom começo é "Gravar macro" em uma planilha sua e ler o código gerado. Assim fica mais fácil ver o que cada comando faz.

A IA generativa também escreve código. Mas para saber se ele está certo e onde corrigir, você precisa conseguir ler pelo menos o "código mais usado" deste artigo.