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

1. Este é o 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 no Google Workspace. Com o Apps Script, você economiza tempo e esforço ao simplificar trabalhos trabalhosos ou complexos no Google Workspace.

Os recursos do Apps Script incluem o seguinte:

• Com os serviços integrados do Apps Script, você pode ler, atualizar e manipular os dados do seu app do Google Workspace com scripts.
• Você pode criar scripts usando o editor de código no navegador do Apps Script, sem precisar instalar ou executar um software de desenvolvimento de código.
• Você pode criar interfaces do usuário para editores do Google Workspace que permitem ativar scripts diretamente desses editores com itens de menu, caixas de diálogo e barras laterais.

Esta playlist de codelab com os conceitos básicos do Apps Script com o Planilhas Google ensina os conceitos básicos e como usá-lo para melhorar sua experiência no Planilhas Google. Este codelab se concentra no ensino de princípios básicos do Apps Script.

O serviço de planilhas

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

• Crie ou modifique uma planilha.
• Ler e atualizar dados, fórmulas e formatação de células.
• Criar botões e menus personalizados.
• Importe e exporte dados de outros apps do Google ou de origens de terceiros.
• compartilhar e controlar o acesso a planilhas;

O que você vai aprender

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

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

Os codelabs nesta playlist precisam ser lidos em ordem, portanto, comece com este e conclua-os em sequência para ter a melhor experiência de aprendizado.

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

2. Introdução

Bem-vindo ao primeiro codelab desta playlist. Neste codelab, você aprenderá as noções básicas do uso do Apps Script com o 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 no Planilhas Google. Depois de gravada, é possível ativar a macro para repetir essas ações mais tarde com um item de menu ou 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 ofertas de funções integradas do Planilhas (como SUM ou AVERAGE), você pode usar o Apps Script para criar funções personalizadas para operações simples e de nicho (como conversões ou concatenação de strings). Depois de criar, você pode chamar essas funções no Planilhas como faria com uma função integrada. 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 o Planilhas Google.
• Como navegar no editor do Apps Script.
• Como criar e atualizar macros.
• criar sua primeira função personalizada do Planilhas;

Pré-requisitos

• Ter noções básicas sobre o JavaScript
• Ter noções básicas sobre o Planilhas Google
• Capacidade de ler a notação A1 no Planilhas

Observação:o Apps Script é baseado em JavaScript. Se você não conhece JavaScript, o Codecademy oferece um curso sem custo financeiro de JavaScript introdutório. Embora o Google não tenha criado esse curso, ele abrange 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 executar um loop de ações repetitivas, como copiar valores de células, formatar, criar fórmulas, entre outros, o que pode deixar a tarefa cansativa e causar erros. Para automatizar ações repetidas, o Planilhas Google fornece macros. Com as macros, você pode "gravar uma série de ações em uma página. Com uma macro gravada, você pode repetir as mesmas ações em outro local da planilha pressionando uma tecla de atalho.

Nesta seção, você aprenderá a criar uma macro no Planilhas. Na próxima seção, você verá como as macros são criadas usando o Apps Script.

Antes de começar

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

Uma cópia da planilha de exemplo que você pode usar está na sua pasta do Google Drive com o nome "Copiada dos 10 filmes mais rentáveis (2018)".

Criar uma macro

Agora que você tem uma planilha para usar, pode gravar uma macro no Planilhas Google. Para este exemplo, você 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. Essa é a linha de cabeçalho.
2. No menu, selecione Extensões > Macros > Gravar macros.

Quando você começa a gravar, o Planilhas Google lembra de todas as ações realizadas na planilha, como destacar células, adicionar dados, alternar para páginas diferentes, formatar e assim por diante. Essas ações se tornam o "script' que é repetido depois que você salva e ativa a macro mais tarde.

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

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

Este codelab solicita que você use referências relativas para suas macros.

4. Selecione a linha 1.

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

6. Altere a Cor do texto da linha superior de preto para branco.

7. Para aplicar negrito ao texto, pressione Ctrl+B (ou Cmd+B no macOS).
8. Para congelar a linha superior, selecione Ver > Congelar > 1 linha.

9. Clique em Salvar na caixa de diálogo da macro. Uma nova caixa de diálogo solicitará que você nomeie a macro. Digite o nome "Header" e clique em Salvar.

Com a interface do usuário do Planilhas, você criou uma macro especializada na formatação de cabeçalhos.

Ativar sua macro

Para aplicar sua nova macro no Planilhas, siga estas instruções:

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

2. Na nova página, adicione texto para A1:C2. Siga os exemplos de entrada 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 exibidas na tela.

Observação:se você estiver usando uma conta do gmail.com, também poderá ver uma caixa de diálogo de app não verificada ao usar seu script pela primeira vez. O Google usa isso para avisar os usuários que talvez estejam usando o código de autores desconhecidos ou não confiáveis. Se você vir essa caixa de diálogo, poderá prosseguir, já que você é o autor do script. Siga as instruções na tela para continuar autorizando o script. O processo para conseguir essa permissão é chamado de autorização.

6. Repita a etapa 4 para executar a macro novamente. Autorizá-la interrompe a primeira execução.

Parabéns, você aprendeu a aplicar macros no Planilhas. Sua planilha terá esta aparência:

As macros permitem que você crie planilhas de maneira eficiente e, na próxima parte deste codelab, você aprenderá a tornar suas macros ainda mais eficientes. Este é o segredo: ao gravar uma macro, o que você realmente faz é escrever o código do Apps Script. Em segundo plano, o Planilhas cria o código que corresponde às ações da macro. Na próxima seção, você aprenderá a modificar o código diretamente usando o editor do navegador do Apps Script.

4. Macros no editor de script

Quando você cria uma macro, o Planilhas Google salva suas ações como uma função do Apps Script. Quando você ativa a macro, o Planilhas Google chama a função do Apps Script para aplicar essas ações na mesma ordem.

O editor de script

Agora que você criou uma macro, é possível analisar o código dela. Para visualizar o script de macro, clique em Extensões > Apps Script para abrir o editor de código do navegador do Apps Script.

O editor de script permite que você escreva códigos no Apps Script e os execute nos servidores do Google.

Observação:as macros e os scripts criados neste codelab são anexados ao arquivo do Planilhas Google em que eles operam e podem ser acessados a qualquer momento no menu Extensões do Planilhas Google (Apps Script). Os scripts anexados a um arquivo do Planilhas Google como esse são chamados de contêiner vinculado.

Análise de macro.gs

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

Veja a imagem abaixo e conheça a estrutura da sua função de macro no Apps Script. Se você registrou as etapas em uma ordem diferente ou clicou ao redor da 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 solicita algumas permissões ao usuário antes de executá-los. Essas permissões controlam o que o usuário pode fazer no script. Quando o comentário @OnlyCurrentDoc está presente em um projeto de script, o Apps Script pede apenas permissão para acessar e atualizar a planilha atual. Sem esse comentário, o Apps Script pediria permissão para acessar e atualizar todas as planilhas dos usuários. É recomendável incluir essa anotação somente quando você estiver trabalhando 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, você pode analisar 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 requer parâmetros, já que as funções de macro no Apps Script não precisam de entradas. As chaves sempre delimitam o corpo de uma função no Apps Script.

Os codelabs futuros desta playlist explicam as classes e os conceitos envolvidos na criação da macro. Por enquanto, você pode analisar as descrições de código a seguir para ter uma ideia geral dos componentes e do papel deles na criação da macro. Considere a primeira linha:

var spreadsheet = SpreadsheetApp.getActive();

Aqui, o getActive() retorna um objeto que representa o arquivo de planilha ativo atual no 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 página atual na variável sheet, enquanto a segunda linha recebe a primeira linha usando o método getRange() e depois 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 página.

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

Esse 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 de forma redundante nesse método spreadsheet mais de uma vez. À medida que você codificar mais usando o Apps Script, saberá mais sobre essa convenção de chamar vários métodos em uma classe (também conhecido como encadeamento de métodos). Por enquanto, leia as seguintes explicações 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 foi ativada.
• Os métodos setBackground(color) e setFontColor(color) alteram os atributos de cor das células no intervalo ativo.
• setFontWeight(fontWeight) ajusta o peso da fonte das células no intervalo ativo.

Por fim, a linha final congela a primeira linha da macro:

spreadsheet.getActiveSheet().setFrozenRows(1);

É o script que você gerou ao gravar sua macro. Não se preocupe com termos ou métodos desconhecidos mencionados acima. O objetivo da descrição é fazer você pensar em algumas das ideias do Apps Script em uma função básica comum e nos temas dos codelabs futuros.

A próxima seção se concentra na manipulação do código da função Header() para mostrar como você pode usar o editor de script para personalizar ainda mais as macros.

Personalizar macros com o Apps Script

O editor do Apps Script mostra a macro que você criou no Planilhas Google. Ao ajustar o conteúdo do corpo da função, você pode personalizar ainda mais as instruções da sua 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.

Alterar as células afetadas

Digamos que você queira modificar sua macro de modo que ela afete somente as primeiras 10 colunas da primeira linha, e não a linha inteira. Exclua a macro e grave-a novamente. Mas, usando o Apps Script, você pode fazer essas alterações diretamente. Veja como fazer isso:

1. No editor de script, substitua sheet.getMaxColumns() por 10. Essa edição altera o intervalo de células que a macro afeta 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 seu projeto, insira "macros e funções personalizadas" como nome do novo projeto e clique em Renomear.
4. Para criar uma planilha, clique em Adicionar página no Planilhas.

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

Você verá o seguinte resultado na sua nova planilha:

Ao modificar o intervalo ativo ou de destino, sua macro agora 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 as células a serem usadas.

A seguir, vamos aprender a personalizar as cores das macros.

Mudar as cores da macro

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

Estas instruções se concentram na alteração da cor do plano de fundo da macro:

1. No Planilhas, volte para a página que contém os dados originais (página 1).
2. Clique na primeira linha para destacá-la.
3. No editor de script, substitua a cor do plano de fundo #4c1130 por #afeeee. Esses valores representam cores diferentes usando a notação tripla 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 Planilhas, o preenchimento do plano de fundo das 10 primeiras colunas da primeira linha mudará 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-pálido, uma opção não acessível no menu de cores padrão do Planilhas), você altera o atributo de cor da cor de plano de fundo da sua macro.

Agora, você modificou a cor de plano de fundo definida pela macro. Se você também quiser mudar a cor do texto, mude o segundo código de cor.

1. No Planilhas, clique na primeira linha para conferir 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-azul.

/** @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.

Retorne ao Planilhas Google para ver a cor de texto da linha de cabeçalho agora em azul-marinho.

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

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

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

Esta seção mostra como criar uma função personalizada no Apps Script que realiza uma conversão monetária.

Criar um arquivo de script

Siga as instruções abaixo para saber como criar um novo script, que pode ser usado para criar sua primeira função personalizada, usando o mesmo projeto de planilha e script da seção "Macros":

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

Uma nova guia chamada customFunctions.gs aparecerá no editor.

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

Converta dólares americanos em francos suíços

Imagine que você queira modificar os dados dos "10 filmes mais rentáveis de 2018 e 39" para mostrar não apenas os valores brutos globais em dólares americanos, mas também em francos suíços. Com as funções personalizadas, você pode fazer isso facilmente. O exercício a seguir demonstra como criar uma função personalizada para converter matematicamente seus valores em dólares para valores francos.

Antes de gravar a primeira função personalizada, modifique seu conjunto de dados para permitir que a função demonstre uma saída adequada. Para isso, siga estas etapas:

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

3. Marque a coluna "Worldwide_Gross (susss 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 script 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;
}

Esse é o código que converterá o dólar americano em francos suíços. Siga as instruções abaixo e veja como executar uma função personalizada no Planilhas.

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

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

8. Mova o cursor para o canto inferior direito da célula I2 e selecione a pequena caixa azul. O cursor precisa se transformar em ao 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 francês sueco dos valores em dólares americanos na coluna H.

Parabéns, você criou sua primeira função personalizada. A próxima seção explica o código que abrange 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, você pode identificar duas partes: a descrição da função (para converter dinheiro em francos) e as anotações que descrevem os parâmetros da função e o tipo de retorno.

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. Veja abaixo como cada anotação usada no USDTOCHF() ajuda no desenvolvimento do Apps Script:

• @param: é possível usar a anotação @param para descrever cada parâmetro transmitido à função.
• @return: é possível utilizar a anotação @return para descrever o que a função retorna.
• @customfunction: sempre adicione @customfunction em qualquer comentário de documento de função personalizada. Essa anotação avisa o Planilhas para preencher automaticamente sua função personalizada da mesma forma que o Planilhas preenche automaticamente funções integradas quando você insere um nome de função em uma célula, como pode ser visto abaixo:

Observe que o texto que aparece no pop-up de preenchimento automático corresponde exatamente ao texto de descrição que você inseriu no bloco de comentários. Para que suas funções personalizadas sejam mais fáceis de usar, é preciso que as descrições estejam bem escritas e completas.

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

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

Como mencionado anteriormente, USDTOCHF() pega a variável numérica em dólares, a multiplica por uma taxa de câmbio fixa e retorna um valor convertido para 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ólares da entrada são 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 funcionar 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 de Franco suíço CHF. É possível 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 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 .

Agora, a string franca suíça prefixa os valores da coluna I:

Sua função personalizada agora não apenas converte dólares americanos em francos suíços, como 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 o exemplo considera que a taxa de câmbio para os francos suíços é constante. Digamos que você queira usar a taxa de câmbio atual. Então, sempre que a página for atualizada, os valores serão recalculados para representar a conversão atual? Para isso, você precisará de uma forma de descobrir qual é a taxa de câmbio atual. Essa informação não está disponível rapidamente no Planilhas Google, mas você pode usar o Apps Script para consegui-lo.

Use o código abaixo para verificar 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 de 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 o UrlFetchApp e o CacheService. Esses conceitos avançados estão fora do escopo deste codelab específico, mas você pode começar a ver a versatilidade do Apps Script para automatizar tarefas complexas no Planilhas Google.

Diretrizes de funções personalizadas

Parabéns por concluir os exercícios das funções personalizadas. Quando você usa 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 no 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 os serviços do Apps Script.
• Não nomeie uma função personalizada da mesma forma que outra função integrada ou encerre o nome com um sublinhado. Leia as diretrizes de nomenclatura.
• Não transmita argumentos de variáveis para funções personalizadas. Só é possível transmitir valores determinísticos (fixos) para funções personalizadas como argumentos. Transmitir argumentos de variável, como o resultado de =RAND(), 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, ocorrerá um erro. Portanto, mantenha o código da função simples e limitado no escopo. É melhor manter os cálculos realizados nas funções personalizadas o mais simples possível. Veja as diretrizes de valores de devolução.

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ê poderá revisar o que aprendeu e o que fazer a seguir para melhorar suas habilidades de script.

6. Conclusão

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

Você achou este codelab útil?

Sim Não

O que vimos

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

Termos-chave

• Referência absoluta: uma configuração de gravação de macro que especifica as ações de macro gravadas é aplicada às células exatas usadas na gravação.
• Ativa (status): indica que a planilha, a planilha, o intervalo ou a célula especificada é a que o usuário da planilha está visualizando ou destacando.
• Apps Script: uma plataforma de desenvolvimento rápido de apps baseada em JavaScript, que facilita e amplia os aplicativos do Google Workspace de forma rápida e automática.
• Autorização: o processo de autorização do usuário para que o Apps Script acesse os dados do usuário nos Serviços do Google relevantes ou realize ações em nome do usuário.
• Script vinculado ao contêiner: é qualquer script vinculado e criado a partir de um documento do Google Workspace, como um arquivo do Planilhas ou Documentos 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 sobre arquivos de origem baseados em JavaScript.
• Macro: abreviação de "quot;macroinstruction"". Uma série de ações do Planilhas Google que você pode repetir usando um item de menu ou a tecla de atalho.
• Encadeamento de métodos: uma expressão de programação para invocar várias chamadas de método em um objeto, com base no fato de que cada chamada de método retorna o objeto.
• Intervalo: um grupo de uma ou mais células adjacentes em uma página.
• Referência relativa: uma configuração de gravação de macro que especifica as ações de macro gravadas é aplicada às células em relação à 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 à planilha do Microsoft Excel). Às vezes usado para fazer referência a um arquivo do Planilhas Google no Google Drive.
• SpreadsheetApp: essa classe serve como a classe pai para o serviço de planilhas e fornece um ponto de partida para o código que lê ou manipula dados do Planilhas Google.
• Arquivo do Planilhas: um arquivo do Planilhas Google que fica no Google Drive.
• Serviço do Planilhas: um serviço do Apps Script que permite criar, acessar e modificar arquivos do Planilhas Google.

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

A seguir

O próximo codelab nesta playlist apresenta as principais classes e terminologia do serviço Planilhas do Apps Script. Com esse serviço, você controla os valores e a apresentação dos dados no Planilhas Google usando o Apps Script.

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