Fundamentos do Apps Script com as Planilhas Google #1: macros e funções personalizadas

1. Bem-vindo(a) ao Apps Script

O que é o Apps Script?

O Apps Script é uma plataforma de desenvolvimento rápido de apps que permite automatizar, personalizar e ampliar sua experiência com o Google Workspace. Com o Apps Script, você economiza tempo e esforço ao simplificar tarefas complexas ou trabalhosos no Google Workspace.

Os recursos do Apps Script incluem:

• Com os serviços integrados do Apps Script, é possível ler, atualizar e manipular os dados do aplicativo do Google Workspace com scripts.
• Você pode criar scripts usando o editor de código no navegador do Apps Script. Não é necessário instalar nem executar software de desenvolvimento de código.
• Você pode criar interfaces de usuário para os editores do Google Workspace que permitem ativar scripts diretamente deles usando itens de menu, caixas de diálogo e barras laterais.

Esta playlist do codelab Fundamentos do Apps Script com o Google Sheets ensina os conceitos básicos do Apps Script e como usá-lo para melhorar sua experiência com o Google Sheets. Este codelab se concentra em ensinar os conceitos básicos do Apps Script.

O serviço de planilha

Você pode usar o Apps Script para estender as Planilhas Google e economizar tempo e esforço. O Apps Script oferece o serviço de planilha, que permite que os scripts interajam com os arquivos das Planilhas Google e os dados que eles contêm. Use esse serviço para automatizar as seguintes tarefas comuns de planilhas:

• Crie ou modifique uma planilha.
• Ler e atualizar dados, fórmulas e formatação de células.
• Crie botões e menus personalizados.
• Importar e exportar dados de outros aplicativos do Google ou fontes de terceiros.
• Compartilhe e controle o acesso às planilhas.

O que você vai aprender

Esta playlist aborda todos os temas necessários para começar a usar o Apps Script com as Planilhas Google:

1. Macros e funções personalizadas
2. Planilhas, páginas e intervalos
3. Como trabalhar com dados
4. Formatação de dados
5. Criar gráficos e apresentar dados no Apresentações Google

Os codelabs nesta playlist devem ser lidos em ordem. Comece com este e conclua os outros em sequência para ter a melhor experiência de aprendizado.

Vá para a próxima seção e saiba mais sobre o conteúdo deste codelab.

2. Introdução

Este é o primeiro codelab desta playlist. Neste codelab, você vai aprender o básico sobre como usar o Apps Script com as Planilhas Google. Especificamente, este codelab se concentra em dois conceitos principais: macros e funções personalizadas.

Uma macro é uma série de ações gravadas nas Planilhas Google. Depois de gravada, é possível ativar uma macro para repetir essas ações mais tarde com um item de menu ou uma tecla de atalho. Você pode criar e atualizar suas próprias macros no Planilhas Google e no editor de código do Apps Script.

No editor de código do Apps Script, também é possível criar funções personalizadas. Assim como as funções integradas das Planilhas Google (como SUM ou AVERAGE), é possível usar o Apps Script para escrever suas próprias funções personalizadas para operações simples e específicas (como conversões ou concatenação de strings). Depois de criadas, você pode chamar essas funções nas Planilhas como se fossem funções integradas. As funções personalizadas também podem ser usadas em fórmulas de células que você escreve, combinando-as com outras funções conforme necessário.

Leia abaixo para saber quais conceitos e requisitos este codelab envolve.

O que você vai aprender

• Como criar um script para as Planilhas Google.
• Como navegar no editor do Apps Script.
• Como criar e atualizar macros.
• Como criar sua primeira função personalizada do Planilhas Google.

O que é necessário

• Ter noções básicas de JavaScript
• Conhecimento básico das Planilhas Google.
• Capacidade de ler a notação A1 do Google Sheets

Observação:o Apps Script é baseado em JavaScript. Se você não conhece JavaScript, o Codecademy oferece um curso introdutório de JavaScript sem custo financeiro. Embora o Google não tenha criado este curso, ele aborda tudo o que você precisa saber.

Você concluiu as apresentações. Acesse a próxima seção para começar a trabalhar com macros.

3. Criar uma macro no Planilhas

Normalmente, ao trabalhar em planilhas, você pode entrar em um loop de ações repetitivas (copiar valores de células, formatar, criar fórmulas etc.), o que pode se tornar cansativo e levar a erros. Para automatizar ações repetidas, o Planilhas Google oferece macros. Com as macros, é possível "gravar" uma série de ações em uma planilha. Com uma macro gravada, você pode repetir as mesmas ações em outro lugar de uma planilha com um simples pressionamento de tecla de atalho.

Nesta seção, você vai aprender a criar uma macro nas Planilhas Google. Na próxima seção, você vai saber como as macros são criadas usando o Apps Script.

Antes de começar

Antes de continuar, você precisa de uma planilha com alguns dados. Fornecemos uma para você: clique neste link para copiar a planilha de dados e depois em Fazer uma cópia.

Uma cópia da planilha de exemplo para você usar é colocada na sua pasta do Google Drive e nomeada como "Cópia dos 10 filmes de maior bilheteria (2018)".

Criar uma macro

Agora que você tem uma planilha para trabalhar, pode gravar uma macro nas Planilhas Google. Neste exemplo, você vai criar uma macro que formata uma linha de cabeçalho para seus dados. Basta seguir estas etapas:

1. Clique na célula A1 para colocar o cursor na linha. Esta é a linha de cabeçalho.
2. No menu, selecione Extensões > Macros > Gravar macros.

Depois que você começa a gravar, as Planilhas Google se lembram de todas as ações realizadas na planilha: destacar células, adicionar dados, mudar para outras planilhas, formatar e assim por diante. Essas ações se tornam o "script" que é repetido quando você salva e ativa a macro mais tarde.

3. Na caixa de diálogo "Macro", selecione Referência relativa.

Termos principais:as macros podem usar dois tipos de referências nas Planilhas para se referir a células específicas. Referências absolutas são fixadas nos locais exatos registrados (por exemplo, célula A5), enquanto referências relativas são aplicadas usando a seleção atual do usuário como ponto de partida (por exemplo, a quarta célula abaixo da seleção atual).

Neste codelab, você vai usar referências relativas para suas macros.

4. Selecione linha 1.

5. Mude a Cor de preenchimento da linha de cima de branco para magenta escuro 3.

6. Mude a Cor do texto da linha de cima de preto para branco.

7. Para colocar o texto em negrito, pressione Ctrl+B (ou Cmd+B no macOS).
8. Para congelar a linha de cima, selecione Visualizar > Congelar > 1 linha.

9. Clique em Salvar na caixa de diálogo de macro. Uma nova caixa de diálogo pede que você nomeie a macro. Insira o nome "Cabeçalho" e clique em Salvar.

Usando a interface do usuário do Google Sheets, você criou uma macro especializada para formatar cabeçalhos.

Ativar sua macro

Para aplicar a nova macro nas Planilhas, siga estas instruções:

1. Para criar uma página, clique em Adicionar página .

2. Na nova página, adicione um texto em A1:C2. Confira os exemplos de entradas abaixo:

3. Destaque a primeira linha.

4. Para aplicar a macro à área selecionada, clique em Extensões> Macros> Cabeçalho.
5. Autorize a macro seguindo as instruções na tela.

Observação:se você estiver usando uma conta gmail.com, também poderá receber uma caixa de diálogo de app não verificado ao usar o script pela primeira vez. O Google usa isso para alertar os usuários que podem estar usando código de autores desconhecidos ou não confiáveis. Se essa caixa de diálogo aparecer, você pode continuar, já que é o autor do script. Siga as instruções na tela para continuar autorizando o script. O processo de concessão dessa permissão é chamado de autorização.

6. Repita a Etapa 4 para executar a macro novamente. A autorização interrompe a primeira execução.

Parabéns! Você aprendeu a usar macros no Planilhas Google. Sua planilha deve ter esta aparência:

As macros permitem criar planilhas de forma eficiente. Na próxima parte deste codelab, você vai aprender a deixar suas macros ainda mais poderosas. O segredo é que, ao gravar uma macro, você está escrevendo código do Apps Script. Nos bastidores, o app Planilhas cria o código que corresponde às ações da macro. Na próxima seção, você vai aprender a modificar o código diretamente usando o editor no navegador do Apps Script.

4. Macros no editor de script

Ao criar uma macro, as Planilhas Google salvam suas ações como uma função do Apps Script. Quando você ativa a macro, as Planilhas Google chamam a função do Apps Script para aplicar essas ações na mesma ordem.

O editor de script

Agora que você criou uma macro, pode conferir o código dela. Para ver o script da macro, clique em Extensões > Apps Script para abrir o editor de código do navegador para o Apps Script.

O editor de script permite escrever código no Apps Script e executar esses scripts nos servidores do Google.

Observação:as macros e os scripts criados neste codelab são anexados ao arquivo das Planilhas Google em que operam e podem ser acessados a qualquer momento no menu Extensões > Apps Script das Planilhas. Os scripts anexados a uma planilha Google como esta são chamados de vinculados ao contêiner.

Análise de macros.gs

Revise o script atual. As Planilhas criaram o arquivo de script macros.gs quando você gravou a macro Header, preenchendo-o com uma função correspondente do Apps Script chamada Header. Quando você ativa a macro Header, o Planilhas executa essa função.

Confira a imagem abaixo para se familiarizar com a estrutura da função de macro no Apps Script. Se você gravou as etapas em uma ordem diferente ou clicou na planilha durante a gravação, seu código pode ser um pouco diferente.

A primeira linha é um comentário de anotação que afeta a autorização:

/** @OnlyCurrentDoc */

A maioria dos scripts pede algumas permissões ao usuário antes de serem executados. Essas permissões controlam o que o usuário permite que o script faça. Quando o comentário @OnlyCurrentDoc está presente em um projeto de script, o Apps Script pede permissão apenas para acessar e atualizar a planilha atual. Sem esse comentário, o Apps Script pediria permissão para acessar e atualizar todas as planilhas do usuário. É sempre uma prática recomendada incluir essa anotação quando você trabalha apenas com um único arquivo. O gravador de macros adiciona esse comentário automaticamente para você.

Para entender como o Apps Script representa as instruções da sua macro, consulte a função:

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
};

Esse código é executado quando você ativa a macro Header. Após function, o rótulo Header() define o nome da função e os parâmetros dela. Reconheça que Header() não exige parâmetros, já que as funções de macro no Apps Script não precisam de entradas. As chaves sempre envolvem o corpo de uma função no Apps Script.

Os codelabs posteriores nesta playlist explicam as classes e os conceitos envolvidos na criação da macro. Por enquanto, confira as descrições de código a seguir para ter uma ideia geral dos componentes e da função deles na criação da macro. Considere a primeira linha:

var spreadsheet = SpreadsheetApp.getActive();

Aqui, getActive() retorna um objeto que representa o arquivo de planilha ativo atual no app Planilhas e o define como a nova variável spreadsheet.

var sheet = spreadsheet.getActiveSheet();
sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, sheet.getMaxColumns()).activate();

Essas linhas correspondem à ação de clicar na primeira linha para destacá-la. Isso é chamado de ativação. A primeira linha armazena a planilha atual na variável sheet, enquanto a segunda linha recebe toda a primeira linha usando o método getRange() e chama activate() para ativá-la. A primeira linha é especificada usando os números de linha e coluna específicos. A chamada spreadsheet.getCurrentCell().getRow() retorna o número da linha atual, enquanto sheet.getMaxColumns() retorna o número máximo de colunas na planilha.

spreadsheet.getActiveRangeList().setBackground('#4c1130')
.setFontColor('#ffffff')
.setFontWeight('bold');

Esse trecho de código fica mais complexo. Para chamar métodos de forma eficiente com spreadsheet, o código empilha três métodos em getActiveRangeList() para evitar que o código chame esse método spreadsheet mais de uma vez. À medida que você programa mais usando o Apps Script, vai se familiarizar com essa convenção de chamar vários métodos em uma classe, também conhecida como encadeamento de métodos. Por enquanto, leia o seguinte para ver explicações breves sobre cada método no bloco de código:

• getActiveRangeList() retorna o RangeList ativo atual em spreadsheet. Nesse caso, é simplesmente a primeira linha que a linha anterior ativou.
• Os métodos setBackground(color) e setFontColor(color) mudam os atributos de cor das células no intervalo ativo.
• setFontWeight(fontWeight) ajusta a espessura da fonte das células no intervalo ativo.

Por fim, a última linha congela a primeira linha da macro:

spreadsheet.getActiveSheet().setFrozenRows(1);

Esse é o script gerado quando você gravou a macro. Não se preocupe com termos ou métodos desconhecidos mencionados acima. A descrição tem como objetivo fazer você pensar em algumas das ideias em que o Apps Script se concentra em uma função de macro típica e nos tópicos que os próximos codelabs vão abordar.

A próxima seção se concentra em manipular o código da função Header() para mostrar como usar o editor de scripts e personalizar ainda mais as macros.

Personalizar macros com o Apps Script

O editor do Apps Script mostra a macro que você criou antes no Planilhas Google. Ao ajustar o conteúdo do corpo da função, você pode personalizar ainda mais as instruções da macro para realizar ações diferentes ou adicionais. Os exercícios a seguir demonstram várias maneiras de manipular macros com o editor de script.

Mudar as células afetadas

Suponha que você queira modificar a macro para que ela afete apenas as 10 primeiras colunas da primeira linha, em vez da linha inteira. Você pode excluir e gravar de novo. Mas, usando o editor do Apps Script, você pode fazer essas mudanças diretamente. Veja uma maneira de fazer isso:

1. No editor de script, substitua sheet.getMaxColumns() por 10. Essa edição muda o intervalo de células afetadas pela macro na planilha.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
    /* sheet.getMaxColumns() replaced with 10.*/
  spreadsheet.getActiveRangeList().setBackground('#4c1130')
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

2. Para salvar o script, clique em Salvar .
3. Para renomear o projeto, insira "Macros and Custom Functions" como o novo nome e clique em Rename.
4. Para criar uma planilha, clique em Adicionar planilha .

5. No editor de script, na lista de funções, selecione Header e clique em Executar.

Na nova planilha, você vai encontrar o seguinte resultado:

Ao modificar o intervalo ativo ou de destino, a macro afeta apenas parte da primeira linha. Muitos métodos do Apps Script usam um intervalo ou a notação A1 como parâmetro para especificar em quais células agir.

Agora vamos aprender a personalizar as cores da macro.

Mudar as cores da macro

Para ajudar você a criar o esquema de cores de macros ou outros elementos nas Planilhas, o Apps Script pode modificar o preenchimento ou a cor do texto de um intervalo. Siga as instruções abaixo para saber como personalizar as cores da sua macro.

Estas instruções se concentram em mudar a cor de fundo da sua macro:

1. Nas Planilhas, volte para a planilha que contém os dados originais (Planilha 1).
2. Clique na primeira linha para destacá-la.
3. No editor de script, substitua a cor de fundo #4c1130 por #afeeee. Esses valores representam cores diferentes usando a notação de tripleto hexadecimal.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
    /* #4c1130 replaced with #afeeee.*/
  .setFontColor('#ffffff')
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

4. Para salvar o script, clique em Salvar .
5. Na lista de funções, selecione Header e clique em Executar.

No app Planilhas, o preenchimento em segundo plano das 10 primeiras colunas na primeira linha muda para uma cor turquesa personalizada:

Ao mudar a notação de cor hexadecimal nos parâmetros de setBackground(color) de #4c1130 (magenta escuro 3) para #afeeee (turquesa claro, uma opção não acessível no menu de cores padrão do Planilhas), você muda o atributo de cor da cor de fundo da sua macro.

Agora você modificou o conjunto de cores de plano de fundo definido pela sua macro. Se você também quiser mudar a cor do texto, altere o segundo código de cor.

1. No app Planilhas, clique na primeira linha para verificar se ela ainda está destacada.
2. No editor de script, substitua a cor da fonte #ffffff por #191970. Isso faz com que a macro defina uma cor de fonte azul-marinho.

/** @OnlyCurrentDoc */

function Header(){
  var spreadsheet = SpreadsheetApp.getActive();
  var sheet = spreadsheet.getActiveSheet();
  sheet.getRange(
    spreadsheet.getCurrentCell().getRow(),
    1, 1, 10).activate();
  spreadsheet.getActiveRangeList().setBackground('#afeeee')
  .setFontColor('#191970')/* #ffffff replaced with #191970.*/
  .setFontWeight('bold');
  spreadsheet.getActiveSheet().setFrozenRows(1);
}

3. Para salvar o script, clique em Salvar .
4. Na lista de funções, selecione Header e clique em Executar.

Volte para o app Planilhas e confira se a cor do texto da linha de cabeçalho agora é azul-marinho.

Agora você já sabe como as macros são ações das Planilhas gravadas como código do Apps Script. Na próxima seção, você vai conhecer outra maneira de usar o Apps Script com o Planilhas Google: as funções personalizadas.

5. Codificar seu primeiro script: funções personalizadas

Assim como a maioria dos aplicativos de planilhas, o Planilhas Google tem várias funções de fórmula integradas, como =SUM(), que permitem cálculos rápidos nos dados da planilha. As funções personalizadas são simplesmente funções especificadas usando o Apps Script. Depois de definir uma função personalizada, você pode usá-la em qualquer lugar da planilha, assim como uma função integrada.

Nesta seção, mostramos como criar uma função personalizada no Apps Script que faz uma conversão monetária.

Criar um arquivo de script

Usando a mesma planilha e o mesmo projeto de script da seção "Macros", siga estas instruções para aprender a criar um novo script, que você pode usar para criar sua primeira função personalizada:

1. Para criar um arquivo do Apps Script, volte ao editor de script.
2. Ao lado de Arquivos, clique em Adicionar um arquivo > Script.
3. Nomeie o novo arquivo de script como customFunctions e pressione Enter. O Apps Script adiciona automaticamente uma extensão .gs ao nome do arquivo de script.

Uma nova guia chamada customFunctions.gs aparece no editor.

Agora que você criou um script especificamente para funções personalizadas, é possível preenchê-lo com código.

Converter dólares americanos em francos suíços

Suponha que você queira modificar os dados de "Os 10 filmes de maior bilheteria de 2018" para mostrar não apenas os valores brutos mundiais em dólares americanos, mas também em francos suíços. Com as funções personalizadas, isso é fácil de fazer. O exercício a seguir demonstra como criar uma função personalizada para converter matematicamente seus valores em dólar para franco.

Antes de escrever sua primeira função personalizada, modifique o conjunto de dados para permitir que a função mostre uma saída adequada. Para fazer isto:

1. Nas Planilhas, clique com o botão direito do mouse na coluna H.
2. No menu resultante, clique em Inserir 1 à direita.

3. Rotule a coluna "Worldwide_Gross (Swiss francs)" na célula I1.

Agora você tem uma coluna que pode armazenar os resultados da sua função personalizada de conversão. Em seguida, use o editor de scripts para criar sua primeira função personalizada.

4. Em customFunctions.gs, substitua o código de myFunction() pelo seguinte:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The converted total of Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Este é o código que vai converter dólares americanos em francos suíços. Siga as instruções abaixo e veja como executar uma função personalizada nas Planilhas.

5. Para salvar o script, clique em Salvar .
6. No app Planilhas, selecione a célula I2.
7. Na barra de funções, digite =USDTOCHF(H2).

Para aplicar a fórmula ao restante das células na coluna:

8. Mova o cursor até o canto inferior direito da célula I2 e selecione a pequena caixa azul. O cursor vai se transformar em quando apontar para a caixa azul.
9. Arraste a caixa azul para baixo para destacar o intervalo I3:I11.

A coluna I agora lista as conversões em franco suíço dos valores em dólar americano na coluna H.

Parabéns, você criou sua primeira função personalizada. A próxima seção explica o código que compõe USDTOCHF().

Análise de USDTOCHF()

Os comentários iniciais detalham a finalidade do código:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {number} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */

Blocos de comentários como este são usados com frequência em programação para explicar o que as funções fazem.

Nesse comentário, é possível identificar duas partes: a descrição da função (para converter dólares em francos) e as anotações que descrevem os parâmetros e o tipo de retorno da função.

Com as anotações, o Apps Script usa o JSDoc para ajudar você a documentar e criar dicas de preenchimento automático para seu código. Leia abaixo como cada anotação usada em USDTOCHF() ajuda no desenvolvimento do Apps Script:

• @param: use a anotação @param para descrever cada parâmetro transmitido à função.
• @return: você pode usar a anotação @return para descrever o que a função retorna.
• @customfunction: sempre adicione @customfunction no comentário de documentação de qualquer função personalizada. Essa anotação notifica o Planilhas Google para preencher automaticamente sua função personalizada, assim como o app preenche automaticamente as funções integradas quando você insere um nome de função em uma célula, conforme mostrado abaixo:

O texto que aparece no pop-up de preenchimento automático corresponde exatamente ao texto de descrição que você colocou no bloco de comentários. Para facilitar o uso das funções personalizadas, crie descrições bem escritas e completas.

Em seguida, concentre-se no código da função USDTOCHF():

function USDTOCHF(dollars){
  var swissFrancs = dollars * .99; 
  return swissFrancs;
}

Como mencionado anteriormente, USDTOCHF() usa a variável numérica "dollars", multiplica por uma taxa de câmbio fixa e retorna um valor convertido em francos suíços na variável numérica swissFrancs. O parâmetro de entrada é o valor contido na célula especificada ao adicionar a função personalizada a uma célula. Neste exemplo, os valores em dólar de entrada vêm da coluna H. O valor de saída swissFrancs é colocado na célula da função (coluna I neste exemplo).

As funções personalizadas podem trabalhar com valores numéricos ou de string, como você verá na próxima seção.

Concatenar um prefixo de string

Suponha que você queira que a saída numérica da função USDTOCHF() inclua o prefixo do franco suíço CHF. Você pode fazer isso com o Apps Script usando o operador de concatenação (+),, conforme mostrado nas instruções a seguir:

1. No editor de script, atualize a anotação @return para retornar a string em vez do número.
2. Altere return swissFrancs para return 'CHF' + swissFrancs.

O operador + anexa a string CHF à frente do valor contido em swissFrancs. Seu código vai ficar assim:

/**
 * Converts US dollars to Swiss francs.
 *
 * @param {number} dollars The total number of dollars.
 * @return {string} swissFrancs The provided value in Swiss francs.
 * @customfunction
 */
function USDTOCHF(dollars){
  var swissFrancs = dollars * .99;
  return 'CHF' + swissFrancs;
}

3. Para salvar o script, clique em Salvar .

A string do franco suíço agora precede os valores da coluna I:

Agora, sua função personalizada não apenas converte dólares americanos em francos suíços, mas também gera a moeda com um prefixo de string.

Avançado: buscar dados externos

Esse é um bom começo para uma função personalizada básica, mas esse exemplo pressupõe que a taxa de câmbio de dólares para francos suíços é constante. Suponha que você queira usar a taxa de câmbio atual. Assim, sempre que a planilha for recarregada, os valores serão recalculados para representar a conversão atual. Para isso, você precisa descobrir qual é a taxa de câmbio atual. Essa informação não está disponível nas Planilhas Google, mas você pode usar o Apps Script para conseguir.

Você pode usar um código como este para saber a taxa de conversão atual de francos suíços para dólares americanos:

function USDTOCHF(dollars){
  // Gets a cache that is common to all users of the script.
  var cache = CacheService.getScriptCache();

  // Accesses the memory location (rates.CHF) of the script cache.
  var rate = cache.get('rates.CHF');

  // If a cache miss occurs, the program fetches the current
  // CHF rate from an API and stores the rate in the cache
  // for later convenience.
  if (!rate) {
    var response =
UrlFetchApp.fetch('https://api.exchangeratesapi.io/latest?base=USD');
    var result = JSON.parse(response.getContentText());
    rate = result.rates.CHF;
    cache.put('rates.CHF', rate);
  }
  // Converts dollars to CHF according to the latest rate.
  var swissFrancs = dollars * rate;
  // Returns the CHF value.
  return 'CHF' + swissFrancs;
}

Esse código busca a taxa de câmbio atual em um servidor de informações financeiras usando uma API de taxa de câmbio de terceiros. Isso é feito usando serviços do Apps Script, como UrlFetchApp e CacheService. Esses conceitos avançados estão fora do escopo deste codelab específico, mas você pode começar a entender a versatilidade do Apps Script para automatizar tarefas complexas no Google Sheets.

Diretrizes para funções personalizadas

Parabéns por concluir os exercícios de funções personalizadas. Ao usar funções personalizadas nos seus projetos, é importante entender que elas têm algumas restrições. A lista a seguir resume as limitações detalhadas no guia Funções personalizadas nas Planilhas Google:

• Não crie funções personalizadas que exijam autorização do usuário. Em vez disso, crie funções personalizadas para realizar tarefas mais simples, como cálculos de dados de amostra, edição de texto etc. Acesse Usar serviços do Apps Script.
• Não dê a uma função personalizada o mesmo nome de outra função integrada nem termine o nome com um sublinhado. Leia as diretrizes de nomenclatura.
• Não transmita argumentos variáveis para funções personalizadas. Só é possível transmitir valores determinísticos (fixos) para funções personalizadas como argumentos. A transmissão de argumentos variáveis, como o resultado de =RAND(), vai interromper a função personalizada. Consulte as diretrizes de argumentos.
• Não crie funções que levem mais de 30 segundos para serem concluídas. Se demorar mais, um erro vai ocorrer. Portanto, mantenha o código da função simples e limitado em escopo. É melhor manter os cálculos realizados em funções personalizadas o mais simples possível. Consulte as diretrizes de valores de retorno.

Agora você pode melhorar suas planilhas usando o editor de script para trabalhar com macros e criar funções personalizadas. Na próxima seção, você pode revisar o que aprendeu e o que pode fazer para melhorar suas habilidades de programação.

6. Conclusão

Você concluiu o primeiro codelab dos Fundamentos do Apps Script com as Planilhas Google. Ao criar e editar macros e funções personalizadas das Planilhas, você aprendeu os conceitos básicos do Apps Script. Você pode expandir ainda mais seu conhecimento sobre o Apps Script no próximo codelab.

Você achou este codelab útil?

Sim Não

O que aprendemos

• Conceitos básicos do Apps Script.
• Como navegar no editor de script.
• Como criar e atualizar macros do Google Sheets.
• Como criar funções personalizadas para as Planilhas Google.

Termos-chave

• Referência absoluta: uma configuração de gravação de macro que especifica que as ações de macro gravadas são aplicadas às células exatas usadas na gravação.
• Ativo (status): indica que a planilha, a página, o intervalo ou a célula especificada é aquela que o usuário da planilha está visualizando ou destacando no momento.
• Apps Script: uma plataforma de desenvolvimento rápido de aplicativos baseada em JavaScript que facilita e agiliza a extensão dos aplicativos do Google Workspace e a automatização do trabalho.
• Autorização: o processo em que o usuário concede permissões para permitir que o Apps Script acesse dados do usuário nos Serviços do Google relevantes ou execute ações em nome dele.
• Script vinculado ao contêiner: qualquer script vinculado e criado em um documento do Google Workspace, como uma planilha ou um documento Google.
• Funções personalizadas: fórmulas definidas pelo usuário no Apps Script usadas em planilhas para operações simples.
• JSDoc: uma linguagem de marcação usada para escrever notas explicativas em arquivos de origem baseados em JavaScript.
• Macro: abreviação de "macroinstrução". Uma série gravada de ações do Google Sheets que você pode repetir usando um item de menu ou uma tecla de atalho.
• Encadeamento de métodos: um idioma de programação para invocar várias chamadas de método em um objeto, contando com o fato de que cada chamada de método retorna o objeto.
• Intervalo: um grupo de uma ou mais células adjacentes em uma planilha.
• Referência relativa: uma configuração de gravação de macro que especifica que as ações de macro gravadas são aplicadas às células relativas à seleção de célula atual.
• Editor de script: o editor de código no navegador para o Apps Script.
• Planilha: uma única página de uma planilha (semelhante às pastas de trabalho do Microsoft Excel). Às vezes, usado para se referir a um arquivo das Planilhas Google no Google Drive.
• SpreadsheetApp: essa classe serve como classe mãe do serviço de planilhas e oferece um ponto de partida para o código que lê ou manipula dados das Planilhas Google.
• Planilha: um arquivo do Planilhas Google que fica no Google Drive.
• Serviço de planilhas: um serviço do Apps Script que permite que os scripts criem, acessem e modifiquem arquivos das Planilhas Google.

Saiba mais sobre o Apps Script na documentação do Apps Script.

A seguir

O próximo codelab desta playlist apresenta as principais classes e a terminologia do serviço de planilhas do Apps Script. Com esse serviço, é possível controlar os valores e a apresentação dos dados nas Planilhas Google usando o Apps Script.

Encontre o próximo codelab em Planilhas, planilhas e intervalos.