Prática com o Google Apps Script: acesse o Planilhas Google, o Maps e o Gmail com apenas quatro linhas de código.

1. Introdução ao Google Apps Script

Neste codelab, vamos apresentar uma das maneiras mais fáceis de escrever código para acessar as tecnologias de desenvolvedores do Google. Tudo é feito com a aplicação do JavaScript, uma linguagem convencional de desenvolvimento da Web. Com o Google Apps Script, você escreverá um código para extrair um endereço de uma célula do app Planilhas Google, gerar um mapa do Google Maps com base no endereço e enviá-lo como um anexo pelo Gmail. Sabe qual é a melhor parte? Serão apenas quatro linhas de código.

O que você vai aprender

• Como usar o Google Apps Script com vários serviços do Google, como Planilhas Google, Google Maps e Gmail.
• Desenvolva código para o Apps Script usando o editor integrado ao navegador.

O que é necessário

• Um navegador da Web com acesso à Internet
• Uma Conta do Google (as contas do Google Workspace podem exigir a aprovação do administrador)
• Conhecimento básico do Planilhas Google
• Saber ler a notação A1 em planilhas.

2. Pesquisa

Como você usará este codelab/tutorial?

Apenas leitura Leitura e exercícios

Como você classificaria sua experiência com as ferramentas para desenvolvedores do Google Workspace? APIs?

Iniciante Intermediário Proficiente

3. Visão geral

Agora que você sabe do que se trata este codelab, o que vai fazer exatamente?

1. Saiba um pouco mais sobre o Apps Script, que é baseado em JavaScript.
2. Crie um arquivo do Planilhas Google.
3. Insira um endereço na célula superior esquerda da planilha (A1).
4. Saiba como abrir o editor do Apps Script em qualquer documento.
5. Edite, salve e execute o código do Apps Script.
6. Use o Gmail para ver o resultado.

Vamos começar.

O que é o Google Apps Script?

O Google Apps Script é uma plataforma de desenvolvimento que facilita e agiliza a criação de scripts e pequenos aplicativos que se integram ao Google Workspace. Com o Apps Script, é possível:

• Escreva código em JavaScript e acesse bibliotecas integradas para aplicativos do Google Workspace, como Gmail, Agenda, Drive etc.
• Não precisa instalar nada. Nós fornecemos um editor de código diretamente no seu navegador, e seus scripts são executados nos servidores do Google.
• Não se preocupe com tópicos complexos, como segurança e permissões de acesso a dados, já que a plataforma cuida disso para você.

OBSERVAÇÃO: o modo de escrever código JavaScript está fora do escopo deste codelab específico. Nosso objetivo é fazer você se familiarizar com o ambiente de desenvolvimento do Apps Script e conferir os tipos de aplicativos que pode criar com ele.

Se você não tem experiência com JavaScript, o Codecademy oferece um curso sem custo financeiro de Introdução ao JavaScript. Embora o Google não tenha criado este curso, ele deve abordar tudo o que você precisa saber.

O Apps Script pode ser usado para criar vários aplicativos, desde chatbots até apps da Web. Um dos usos mais populares é ampliar a funcionalidade de uma planilha do Planilhas Google. No restante deste codelab, você aprenderá a usar o Apps Script para extrair dados de uma planilha e conectá-la a outros Serviços do Google.

4. Criar um arquivo das Planilhas Google e insira um endereço

Em um novo arquivo das Planilhas Google, insira um endereço válido seguindo estas instruções:

1. Crie uma planilha Google usando este link de conveniência (sheets.google.com/create). Você também pode acessar o Google Drive (drive.google.com) e clicar em Novo > Planilhas Google > Planilha em branco

2. Na planilha em branco, vá para a primeira célula no canto superior esquerdo (A1). Essa é a linha 1 da coluna A. Se precisar se familiarizar novamente, confira esta descrição da notação A1.
3. Insira um endereço válido na célula. Escolha um endereço no mundo com uma localização exata usando um endereço, um CEP/código postal ou uma combinação de cidade e estado/província. Aqui está um exemplo de um endereço na cidade de Nova York:

Isso é tudo o que você precisa fazer na planilha. Vamos abrir o editor e escrever um código.

5. Edite o código do Apps Script

Agora que você tem um novo arquivo das Planilhas Google, é hora de editar o script vinculado. Siga estas instruções:

Abrir o editor de script

Na barra de menu, selecione Extensões > Apps Script para abrir o editor de código do navegador para o Apps Script.

Em uma nova guia do navegador, o editor de código mostra o script container-bound padrão da página. Uma função padrão chamada myFunction() é criada automaticamente, e o cursor é colocado dentro da função para que você possa começar.

Enviar um mapa do endereço do Google por e-mail

O "modelo" o código que você recebeu está vazio, então vamos substituí-lo por nosso aplicativo.

1. No editor de script, substitua o bloco de código myFunction() padrão por este:

/** @OnlyCurrentDoc */
function sendMap() {
  var sheet = SpreadsheetApp.getActiveSheet();
  var address = sheet.getRange('A1').getValue();
  var map = Maps.newStaticMap().addMarker(address);
  GmailApp.sendEmail('YOUR_EMAIL_ADDR', 'Map', 'See below.', {attachments:[map]});
}

2. Substitua o endereço de e-mail do marcador ('YOUR_EMAIL_ADDR') por um válido. Por exemplo, [e-mail].
3. Para salvar o script, clique em Salvar .
4. Para renomear seu projeto do Apps Script, clique em Projeto sem título, digite um título e clique em Renomear.

Revisão de código

Vamos analisar as quatro linhas da função sendMap() que compõem todo o aplicativo. Curiosamente, o código faz referência a três produtos diferentes do Google.

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 da execução. Essas permissões controlam o que o usuário permite que o script faça. A primeira linha é um comentário com uma anotação opcional que instrui o Apps Script a limitar o acesso à planilha atual, e não a todas as planilhas do usuário. É sempre uma prática recomendada incluir essa anotação quando estiver trabalhando apenas com um único arquivo.

O código usa uma declaração de função normal de JavaScript para sendMap():

function sendMap() {

A próxima linha chama o serviço Planilhas, que pode ser acessado no Apps Script pelo objeto SpreadsheetApp. A planilha retornada é atribuída a uma variável com o mesmo nome. O método getActiveSheet() recebe uma referência ao objeto da planilha atual e a armazena na variável sheet.

  var sheet = SpreadsheetApp.getActiveSheet();

Com o objeto sheet, referenciamos o intervalo de células (de uma única célula) em notação A1 com getRange(). Um "intervalo" é um grupo de células, incluindo uma única, como a célula A1 (aquela em que inserimos o endereço). Para buscar o que está dentro do intervalo, o método getValue() retorna o valor da célula no canto superior esquerdo do intervalo e atribui o valor à variável address. Você também pode tentar adicionar mais endereços e ler células diferentes.

  var address = sheet.getRange('A1').getValue();

A terceira linha de código se conecta ao serviço do Google Maps usando o objeto Maps. newStaticMap() cria um objeto de mapa estático, e o método addMarker() adiciona um "fixo". ao mapa usando o endereço na planilha.

  var map = Maps.newStaticMap().addMarker(address);

Por fim, o serviço do Gmail no objeto MailApp chama o método sendEmail() para enviar o e-mail que inclui o texto "Confira abaixo". e a imagem do mapa como anexo.

  GmailApp.sendEmail('[e-mail]', 'Map', 'See below.', {attachments:[map]});
}

6. Execute o app do Planilhas Google, do Maps e do Gmail

Depois de nomear e salvar, é hora de executar a função. Na parte de cima do editor, verifique se sendMap() está selecionado na lista de funções e clique em Run.

Um recurso do Apps Script apreciado pelos desenvolvedores é que você não precisa escrever um código de autorização que conceda ao programa acesso aos dados dos usuários. Embora o Apps Script gerencie isso, os usuários do app ainda precisam conceder permissão para que o script acesse as planilhas e envie e-mails pelo Gmail. A primeira caixa de diálogo de autorização tem a seguinte aparência:

Clique em Revisar permissões para continuar.

Observação:se você estiver usando uma conta do gmail.com, talvez receba a mensagem "Este app não foi verificado". quando você usar seu script pela primeira vez. O Google usa essas informações para alertar usuários que possam estar usando código de autores desconhecidos ou não confiáveis. Se essa caixa de diálogo for exibida, não há problema em continuar, já que você é o autor do script. Siga as instruções na tela para continuar autorizando o script:

1. Na caixa de diálogo do app não verificado, clique em Avançado.
2. Clique em Acessar nome-do-projeto (não seguro).
3. Clique em Permitir.

Ao longo deste codelab, você pode receber várias solicitações de permissão. Leia mais sobre esse processo em Autorização para serviços do Google.

Em seguida, será exibida a caixa de diálogo do OAuth2 solicitando permissão para acessar a planilha e enviar e-mails em seu nome:

Depois de receber sua permissão, o script será executado.

Verifique a conta de e-mail para a qual você enviou a mensagem. Você deve encontrar um e-mail com "Mapa". como assunto e uma mensagem como esta:

Ao abrir o anexo na mensagem de e-mail, você verá um mapa do Google com um alfinete no endereço digitado na planilha:

Com apenas quatro linhas de código, você acessou três produtos diferentes do Google de maneira significativa.

7. Outros recursos

O código apresentado neste codelab também está disponível no repositório do GitHub em github.com/googleworkspace/apps-script-intro-codelab. Confira abaixo mais recursos para você se aprofundar no que foi abordado neste codelab e conhecer outras maneiras de acessar as ferramentas para desenvolvedores do Google de maneira programática.

Documentação

• Site da documentação do Google Apps Script
• Apps Script: Serviço do Gmail
• Apps Script: serviço das Planilhas
• Apps Script: serviço do Maps

Vídeos

• Totalmente imprevisível
• Programa para desenvolvedores do Google Workspace

Notícias e atualizações

• Blog de desenvolvedores do Google Workspace
• Twitter: Google Workspace Developers (@workspacedevs)

Outros codelabs

Básico

• [Planilhas Google] Noções básicas do Apps Script com o Planilhas Google
• [APIs REST] Usar o Google Workspace e APIs do Google para acessar arquivos e pastas no seu Google Drive

Intermediário

• [Apps Script] Complementos do Google Workspace para o Gmail
• [Apps Script] Bots personalizados para o Hangouts Chat
• [APIs REST] Usar o Planilhas Google como a ferramenta de relatórios do seu aplicativo
• [APIs REST] Gerar apresentações Google usando a API BigQuery

Aplicativos de referência

• Gere apresentações Google usando marcações e HTML usando a API Slides