Macros & Custom Functions

O material à seguir foi retirado e traduzido da página de suporte ao desenvolvedor do Google, mais especificamente da seção Apps Script que é a linguagem do Google utilizada na G Suite onde está incluído o Google Drive e as Planilhas do Google, trata-se de explicações básicas sobre o funcionamento dos scripts do Google, embora essa linguagem seja o meio de conversa entre as diferentes ferramentas do Google daremos foco no uso desta linguagem com as Planilhas do Google, quem tiver interesse em se aprofundar nesse conhecimento poderá acessar o link https://developers.google.com/apps-script/ não é necessário conhecimentos prévios para iniciar a trabalhar com o apps script, no entanto, conhecimentos sobre A1 notation e Javascript são bem úteis e você pode adquirir conhecimento sobre estes itens gratuitamente nos links https://developers.google.com/sheets/api/guides/concepts#a1_notation e https://www.codecademy.com/catalog/language/javascript.

O primeiro Guia que vamos fazer é o de Macros e Custom Functions, pois é um dos melhores guias iniciais para se ter uma ideia geral do que é possível fazer com o Apps Scripts dentro das Planilhas do Google, vejamos então abaixo o conteúdo retirado do link: https://codelabs.developers.google.com/codelabs/apps-script-fundamentals-1/#0. Recomendamos que seja feito no mínimo dois dos 5 tutoriais à seguir, este e o de Formatação de Dados

Criação de uma macro no Planilhas

Normalmente, ao trabalhar em planilhas, você pode entrar em um ciclo de ações repetitivas – copiar valores de células, formatar, criar fórmulas e assim por diante – o que pode se tornar tedioso e levar a erros. Para fornecer a você uma maneira de automatizar ações repetitivas, o Planilhas Google fornece macros . As macros permitem ‘registrar’ uma série de ações em uma planilha. Com uma macro gravada, você pode repetir essa série de ações em outro lugar em uma planilha com um simples pressionamento de 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 você começar

Antes de continuar, você precisa de uma planilha com alguns dados. Fornecemos um para você: clique neste link para copiar a planilha de dados e, em seguida, clique no botão Fazer uma cópia .

Conjunto de dados

Uma cópia da planilha de exemplo para você usar deve ser colocada na pasta inicial do Google Drive com o nome “Cópia dos 10 filmes de maior bilheteria (2018)”.

Criação de uma macro

Agora que você tem uma planilha para trabalhar, 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:

Clique na célula A1 para focar o cursor nessa linha. Esta é a sua linha de cabeçalho.
No menu, selecione Ferramentas> Macros> Gravar macros .

Assim que você começa a gravar, o Planilhas Google começa a se lembrar de cada ação realizada na planilha: destacar células, adicionar dados, alternar para planilhas diferentes, formatar e assim por diante. Essas ações se tornam o ‘script’ que é repetido assim que você salva e ativa a macro posteriormente.

Na caixa Macro, selecione Referência relativa.

Gif: Use referências relativas

Termos-chave: as macros podem usar dois tipos de referências nas planilhas para se referir a células específicas. As referências absolutas são fixadas nos locais exatos registrados (por exemplo, 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 abaixo da seleção atual).

Selecione a linha 1 .

Gif: destacar a linha 1

Recolorir a cor de preenchimento da linha superior de branco para magenta escuro 3 .

Menu de cores (magenta escuro 3)

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

Menu de cores (branco)

Coloque o texto em negrito clicando em Ctrl + B (ou Cmd + B em Macs).
Selecione Exibir> Congelar> 1 linha para congelar a linha superior.

Congelar 1 linha

Clique no botão Salvar na caixa de diálogo da macro na parte inferior da tela. Uma nova caixa de diálogo pede que você nomeie a macro; dê a ele o nome “Cabeçalho” e clique em Salvar .

Gif: Salvar macro como 'Cabeçalho'

Usando a interface de usuário do Planilhas, você criou uma macro especializada para formatar cabeçalhos!

Folha com macro

Você fez uma macro para formatar cabeçalhos. Passe para a próxima seção para aprender como aplicar macros no Planilhas.

Ativando sua macro

Você criou uma macro no Planilhas! Você pode tentar aplicar sua macro no Planilhas seguindo estas instruções:

Clique em ou Adicionar planilha para criar uma nova planilha.

Na nova planilha, adicione algum texto a A1:C2. Sinta-se à vontade para seguir os exemplos de entrada abaixo:

Entradas de exemplo

Destaque a primeira linha.

Selecionando a linha 1

Selecione Ferramentas> Macros> Cabeçalho para aplicar a macro à área selecionada.

Aplicando macro

Autorize a macro seguindo as instruções na tela.

Repita a Etapa 4 para executar a Macro novamente (autorizando-a para a primeira execução).

Você aprendeu a aplicar macros no Planilhas. Parabéns! Sua planilha deve ter a seguinte aparência:

As macros permitem que você crie planilhas de maneira eficiente e, na próxima parte deste codelab, você aprenderá como tornar suas macros ainda mais poderosas! Este é o segredo: quando você grava uma macro, o que você realmente está fazendo é escrever o código do Apps Script . Nos bastidores, o Sheets constrói o código que corresponde às ações da macro para você. E, na próxima seção, você aprenderá como modificar esse código de macro diretamente usando o editor do navegador do Apps Script.

Apresentando o editor de script

Conforme 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 Apps Script para realizar as mesmas ações na mesma ordem.

Olhando para o editor de script

Agora que você criou uma macro, pode examinar seu código. Você pode examinar seu script de macro selecionando Ferramentas> Editor de scripts para abrir um editor de código do navegador para Apps Script.

Imagem: Ferramentas> Editor de Script

Agora você pode ver o editor de script! O editor de script permite que você escreva códigos no Apps Script e execute esses scripts nos servidores do Google.

O editor de script mostrado acima tem vários componentes:

Um título de projeto ou nome do projeto de script que contém seus scripts.
Um menu ou lista de operações relacionadas ao seu projeto.
Uma barra de tarefas ou lista de operações relacionadas ao seu script, como Salvar .
Uma barra lateral de script que descreve os scripts do projeto.
O script atual que mostra o script selecionado na barra lateral do script.

Compreensão `macro.gs`

A seguir, observe o script atual. O Sheets criou o macros.gs arquivo de script quando você gravou a Header macro, preenchendo-o com uma função correspondente do Apps Script chamada Header. Quando você ativa a macro, o Planilhas executa esta função.

Observe a imagem abaixo para se familiarizar com a estrutura da função macro no Apps Script. Nota: Seu código pode parecer um pouco diferente se você registrou as etapas em uma ordem diferente ou clicou ao redor da planilha durante a gravação.

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

/** @OnlyCurrentDoc */

A maioria dos scripts pede ao usuário algum conjunto de permissões antes de poderem ser executados. Essas permissões controlam o que o usuário está permitindo que o script faça. Quando o @OnlyCurrentDoc comentário está presente em um projeto de script, o Apps Script só pede permissão para acessar e atualizar a planilha atual. Sem esse comentário, o Apps Script solicitaria permissão para acessar e atualizar todas as planilhas do usuário. É sempre uma boa ideia incluir essa anotação quando você espera trabalhar apenas com um único arquivo. O gravador de macro adiciona este comentário automaticamente para você.

Para começar a entender como o Apps Script representa as instruções de sua macro, você pode examinar 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);
};

Este código é executado quando você ativa a Header macro! A seguir function, o rótulo Header() define o nome da função e seus parâmetros. Reconheça que Header() não requer parâmetros, pois funções de macro no Apps Script não precisam de entradas. Os colchetes sempre incluem o corpo de uma função no Apps Script.

Os codelabs posteriores nesta lista de reprodução explicam as classes e conceitos envolvidos na criação da macro. Mas, por enquanto, você pode percorrer as seguintes descrições de código para ter uma idéia geral de seus componentes e sua função na construção de sua macro. Considere a primeira linha:

var spreadsheet = SpreadsheetApp.getActive();

Aqui, getActive() retorna um objeto que representa o arquivo de planilha ativa atual no Planilhas e o define para 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 obtém a primeira linha inteira usando o getRange() método e depois chama activate() para ativá-la. A primeira linha é especificada usando os números específicos de linha e coluna. A spreadsheet.getCurrentCell().getRow() chamada 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 pedaço de código fica mais complexo. Para chamar eficiente métodos com spreadsheet, o código pilhas três métodos Onto getActiveRangeList() para evitar que o código redundante chamando getActiveRangeList() em spreadsheet mais de uma vez. Conforme você codifica cada vez mais usando o Apps Script, pode se familiarizar mais com esta convenção de chamar vários métodos em uma classe (também conhecido como encadeamento de método ). Por enquanto, você pode ler o seguinte para obter breves explicações sobre cada método no bloco de código:

getActiveRangeList() retorna o ativo atual RangeList em spreadsheet. Neste caso, é simplesmente a primeira linha que a linha anterior ativou.
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 para células no intervalo ativo.

Por último, a linha final congela a primeira linha da macro:

spreadsheet.getActiveSheet().setFrozenRows(1);

E esse é o script que você gerou quando gravou sua macro! Não se preocupe com quaisquer termos ou métodos desconhecidos mencionados acima. O objetivo da descrição é fazer com que você pense sobre algumas das ideias em que o Apps Script se concentra em uma função típica de macros e em quais tópicos futuros codelabs se aprofundarão.

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

Personalização de macros com Apps Script

O editor do Apps Script mostra a macro que você criou anteriormente no Planilhas Google. Ajustando 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 ajustar sua macro para que ela afete apenas as primeiras 10 colunas da primeira linha, em vez de toda a linha. Você pode excluir a macro e regravá-la. Mas, usando o editor do Apps Script, você pode fazer essas alterações diretamente. Esta é uma maneira de fazer isso:

No editor de script, substitua sheet.getMaxColumns() por 10 na linha 6. Esta 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);
}

Select , File> Save , ou Ctrl + S ( Cmd + S em Macs) para salvar seu script. Em seguida, você testará a macro editada.
Pode aparecer um prompt para solicitar um nome de projeto. Nesse caso, insira “Macros e funções personalizadas” como o novo nome do projeto e clique em OK.

Em Planilhas, clique em ou Adicionar planilha para criar uma nova planilha.

No editor de script, selecione ou Executar> Executar função> Cabeçalho para executar a função macro.

Gif: executar código

Em sua nova planilha, você deverá ver o seguinte resultado:

Ao ajustar 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 notação A1 como parâmetro para especificar em quais células agir.

Agora, é hora de aprender a personalizar suas cores macro!

Mudando as cores de sua macro

Para ajudá-lo a projetar o esquema de cores de macros ou outros elementos no Planilhas, o Apps Script pode ajustar o preenchimento de um intervalo ou a cor do texto. Siga as instruções a seguir para ver como você pode personalizar as cores de sua macro.

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

Em Planilhas, volte para a planilha original (Planilha 1) que contém os dados.
Clique na primeira linha para realçá-la.
No editor de script, substitua #4c1130 por #afeeee na linha 6. Esses valores representam cores diferentes usando a notação hexadecimal tripla .

/** @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);
}

Select , File> Save , ou Ctrl + S ( Cmd + S em Macs) para salvar seu script.
Selecione ou Executar> Executar função> Cabeçalho para compilar e executar o script.

No Planilhas, o preenchimento do plano de fundo das primeiras 10 colunas na primeira linha muda para uma cor turquesa personalizada, conforme mostrado aqui:

Imagem: fundo macro recolorido

Ao mudar a notação de cor hex nos parâmetros de setBackground(color) partir #4c1130 (magenta escuro 3) #afeeee (turquesa pálido, uma opção não está acessível no menu de cores padrão Sheets), você muda o atributo de cor da cor de fundo do seu macro.

Você ajustou a cor de fundo definida por sua macro. Suponha agora que você deseja alterar a cor do texto também, para tornar os rótulos do cabeçalho mais visíveis. Você pode fazer isso alterando o segundo código de cor:

No Planilhas, clique na primeira linha para verificar se ela ainda está destacada.
No editor de script, substitua #ffffff por #191970 na linha 8. 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);
}

Select , File> Save , ou Ctrl + S ( Cmd + S em Macs) para salvar seu script.
Selecione ou Executar> Executar função> Cabeçalho para compilar e executar o script.

Retorne ao Planilhas. Veja que a cor do texto da linha do cabeçalho agora é azul marinho!

Imagem: texto macro recolorido

Agora você viu como as macros são na verdade ações do Planilhas registradas como código do Apps Script. Na próxima seção, você verá outra maneira como o Apps Script pode ajudá-lo a trabalhar com o Planilhas Google: funções personalizadas .

Codificando seu primeiro script: Funções personalizadas

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

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

Criação de um novo arquivo de script

Com a mesma planilha e projeto de script usados na seção Macros, você pode seguir estas instruções para aprender como fazer um novo script (que você pode eventualmente usar para fazer sua primeira função personalizada!):

No editor de script, selecione Arquivo> Novo> Arquivo de script .
Nomeie o novo arquivo de script customFunctions (o Apps Script acrescenta automaticamente uma .gs extensão ao nome do arquivo de script).

Uma nova guia nomeada customFunctions.gs dentro do editor deve aparecer:

Sempre que você cria um novo script, o editor gera automaticamente um padrão myFunction()para sua conveniência.

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

Conversão de dólares americanos em francos suíços

Suponha que você queira ajustar os dados de ‘Dez filmes de maior bilheteria de 2018’ para mostrar não apenas os valores brutos em dólares americanos, mas também em francos suíços. Com 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 em francos.

Antes de escrever sua primeira função personalizada, ajuste seu conjunto de dados para permitir que a função demonstre uma saída adequada. Para fazer isso:

Em folhas, clique com o botão direito coluna H.
No menu resultante, clique em Inserir 1 à direita.

Gif: clique com o botão direito em H> Inserir 1 à direita

Identifique a coluna “Worldwide_Gross (francos suíços)” na célula I1 .

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

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

/**
 * 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 converterá dólares americanos em francos suíços. Experimente as instruções abaixo e veja como você pode executar uma função personalizada em planilhas.

Select , File> Save , ou Ctrl + S ( Cmd + S em Macs) para salvar seu script.
Em Planilhas, selecione a célula I2 .
Na barra de funções, digite =USDTOCHF(H2).

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

Mova seu cursor para o canto inferior direito da célula I2 e selecione a pequena caixa azul (seu cursor deve se transformar em quando passar o mouse sobre a caixa azul).
Clique e arraste a caixa azul para baixo para destacar o I3 : I11 .

Gif: Aplicando fórmula

A coluna I agora lista as conversões em francos suíços dos valores em dólares americanos da coluna G!

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

Analisando a função `USDTOCHF()`

Começando do início do código, você pode reconhecer os comentários detalhando 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 freqüência na programação para explicar o que as funções fazem.

Neste comentário, você pode identificar duas partes: a descrição da função (para converter dólares 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 utiliza JSDoc para ajudá-lo a documentar e criar dicas de preenchimento automático para seu código. Você pode ler abaixo como cada anotação usada no USDTOCHF()ajuda você no desenvolvimento do Apps Script:

@param: Você pode usar a @param0 anotação para descrever cada parâmetro passado para a função.
@return: Você pode utilizar a @return anotação para descrever o que a função retorna.
@customfunction: Você sempre deve adicionar @customfunction comentários de doc de qualquer função personalizada. Esta anotação notifica o Planilhas para preencher automaticamente sua função personalizada, assim como o Planilhas preenche automaticamente funções integradas quando você digita o nome de uma função em uma célula, conforme mostrado abaixo:

Gif: função personalizada USDTOCHF

Observe que 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. Você pode tornar suas funções personalizadas mais fáceis de usar, certificando-se de que as descrições criadas sejam bem escritas e completas.

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

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

Conforme mencionado anteriormente, USDTOCHF() pega a variável numérica dólares e retorna esse valor convertido em francos suíços na variável numérica swissFrancs, multiplicando-o por uma taxa de câmbio fixa. O parâmetro de entrada é o valor contido na célula que você especificou ao adicionar a função personalizada a uma célula. Neste exemplo, os valores em dólares de entrada vêm da coluna H. O valor de saída swissFrancs é colocado na célula da função (ou seja, 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.

Concatenando 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 seguintes instruções:

No editor de script, mude return var na linha 10 para return 'CHF' + swissFrancs.

O +operador anexa a string CHF à frente do valor contido em swissFrancs. Seu código agora deve ter a seguinte aparência:

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

Reveja as etapas abaixo, para que você possa salvar e executar sua função para ver os resultados!

Select , File> Save , ou Ctrl + S ( Cmd + S em Macs) para salvar seu script.

O franco suíço agora prefixa os valores da coluna I:

Coluna I

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

Avançado: Buscando dados externos

Este é um bom começo para uma função personalizada básica, mas este exemplo pressupõe que a taxa de câmbio de dólares para francos suíços é constante. Suponha que, em vez disso, você queira que a taxa de câmbio atual sempre seja usada, de modo que, sempre que a planilha for recarregada, os valores sejam recalculados para representar a conversão atual. Para fazer isso, você precisa de um meio de descobrir qual é a taxa de câmbio atual. Essas informações não estão disponíveis no Planilhas Google, mas felizmente você pode usar o Apps Script para obtê-las!

Você pode usar o código abaixo para obter a taxa de conversão atual de francos suíços em 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 that 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;
}

Este código obtém a taxa de câmbio atual de um servidor de informações financeiras usando a 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 ver a versatilidade do Apps Script para automatizar tarefas complexas no Planilhas Google.

Diretrizes de função personalizada

Parabéns por completar os exercícios para funções personalizadas. À medida que você usa funções personalizadas em seus projetos, é importante entender que elas têm certas 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 suas funções personalizadas para cumprir tarefas mais simples, como cálculos de dados de amostra, edição de texto, etc. Consulte Como usar os serviços do Apps Script .
Não nomeie uma função personalizada da mesma forma que outra função interna, ou termine o nome com um sublinhado. Consulte as diretrizes de nomenclatura .
Não passe argumentos variáveis para funções personalizadas. Você só pode passar valores determinísticos (valor fixo) para funções personalizadas como argumentos. Passar argumentos variáveis, 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 em escopo. É melhor manter os cálculos realizados nas 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 scripts para trabalhar com macros e criar funções personalizadas! Na próxima e última seção, você pode revisar o que aprendeu e o que pode fazer a seguir para melhorar suas habilidades de script.

Conclusão

Você concluiu o primeiro codelab de Fundamentos do Apps Script. Ao criar e editar macros e funções personalizadas do Planilhas, você aprendeu os conceitos básicos do Apps Script. Você pode expandir ainda mais seus conhecimentos sobre o Apps Script no próximo codelab!

Nesse tutorial você viu:

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

Termos chave importante:

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, planilha, intervalo ou célula especificada é a que está sendo exibida ou destacada pelo usuário da planilha.
Apps Script : uma plataforma de desenvolvimento rápido de aplicativos, baseada em JavaScript, que torna mais rápido e fácil estender os aplicativos do G Suite e automatizar o trabalho.
Autorização : o processo do usuário que concede permissões para permitir que um script acesse os dados do usuário ou execute ações em nome do usuário.
Script vinculado ao contêiner : qualquer script vinculado e criado a partir de um documento do G Suite, como uma planilha ou um documento do Google.
Funções personalizadas : fórmulas definidas pelo usuário no Apps Script que são usadas em planilhas para operações simples.
JSDoc : uma linguagem de marcação usada para escrever notas explicativas sobre arquivos de origem JavaScript.
Macro : abreviação de “macroinstrução”. Uma série gravada de ações do Planilhas Google que você pode repetir rapidamente usando um item de menu ou tecla de atalho.
Encadeamento de métodos : um idioma de programação para invocar várias chamadas de método no objeto, contando com o fato de que cada chamada de método retorna o próprio objeto.
Intervalo : um agrupamento de 1 ou mais células adjacentes da 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 em relação à seleção de células atual.
Editor de script : o editor de código no navegador para Apps Script.
Folha : Uma única página de uma planilha (semelhante às pastas de trabalho do Microsoft Excel). Às vezes usado para se referir a um arquivo do Planilhas Google no Google Drive.
Serviço de planilha : um serviço do Apps Script que permite que os scripts criem, acessem e modifiquem arquivos do Planilhas Google.