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, você vai conhecer uma das formas mais fáceis de escrever código para acessar as tecnologias de desenvolvedores do Google. Tudo isso é feito com JavaScript, uma linguagem de desenvolvimento da Web muito usada. Com o Google Apps Script, você vai escrever um código para extrair um endereço de uma célula em uma planilha Google, gerar um mapa do Google Maps com base nesse endereço e enviar o mapa como um anexo usando o 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 o Google Planilhas, o Google Maps e o Gmail.
  • Desenvolver código usando o editor no navegador para o Apps Script.

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 Google Planilhas
  • Capacidade de ler a notação A1 do Google Sheets

2. Pesquisa

Como você vai usar este codelab/tutorial?

Apenas leitura Leitura e exercícios

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

Iniciante Intermediário Proficiente

3. Visão geral

Agora que você sabe sobre o que é este codelab, o que você vai fazer exatamente?

  1. Aprenda um pouco sobre o Apps Script, que é baseado em JavaScript.
  2. Crie uma planilha Google Planilhas.
  3. Insira um endereço na célula superior esquerda da planilha (A1).
  4. Aprenda a abrir o editor de script 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 integrados 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 é preciso instalar nada, fornecemos um editor de código no seu navegador e os scripts são executados nos servidores do Google.
  • Não é preciso se preocupar com temas complexos, como segurança e permissões de acesso aos dados, já que a plataforma cuida disso para você.

O Apps Script pode ser usado para criar vários aplicativos, de bots de chat a apps da Web. Um dos usos mais comuns é estender a funcionalidade de uma planilha Google Planilhas. No restante deste codelab, você vai aprender a usar o Apps Script para extrair dados de uma planilha e conectá-los a outros serviços do Google.

4. Criar uma planilha Google e inserir um endereço

Em uma nova planilha Google, insira um endereço válido seguindo estas instruções:

  1. Crie uma planilha Google usando este link (sheets.google.com/create). Se preferir, acesse o Google Drive (drive.google.com) e clique em Novo > Google Planilhas > Planilha em branco.

413a93e5b2f6b3d4.png

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

7077e446455639df.png

Não é preciso fazer mais nada 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 do Planilhas Google, é hora de editar o script vinculado a ele. Siga estas instruções:

Abrir o editor de scripts

Na barra de menus, 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 vinculado ao contêiner padrão da planilha. Uma função padrão chamada myFunction() é criada automaticamente, e o cursor é colocado dentro dela para que você possa começar.

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

O código "modelo" que você recebeu está vazio. Por isso, substitua-o pelo nosso aplicativo.

  1. No editor de script, substitua o bloco de código myFunction() padrão pelo seguinte código:
/** @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]});
}
  1. Substitua o endereço de e-mail do marcador ('YOUR_EMAIL_ADDR') por um válido. Por exemplo, friend@example.com.
  2. Para salvar o script, clique em Salvar salvar.
  3. Para renomear seu projeto do Apps Script, clique em Projeto sem título, insira um título e clique em Renomear.

Revisão de código

Vamos revisar 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 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. A primeira linha é um comentário que contém uma anotação opcional instruindo o Apps Script a limitar o acesso à planilha atual (em vez de todas as planilhas do usuário). É sempre uma prática recomendada incluir essa anotação quando você trabalha apenas com um único arquivo.

O código usa uma declaração de função normal do 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, fazemos referência ao intervalo de células (de uma única célula) na notação A1 com getRange(). Um "intervalo" é um grupo de células, incluindo uma única célula como A1 (onde inserimos o endereço). Para buscar o que está dentro do intervalo, o método getValue() retorna o valor da célula superior esquerda no intervalo e o atribui à variável address. Você também pode 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 marcador ao mapa usando o endereço na planilha.

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

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

  GmailApp.sendEmail('friend@example.com', 'Map', 'See below.', {attachments:[map]});
}

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

Depois de nomeada e salva, é 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 Executar.

Um recurso do Apps Script que os desenvolvedores apreciam é não precisar escrever um código de autorização que conceda ao programa acesso aos dados do usuário. Embora o Apps Script faça isso, os usuários do seu app ainda precisam permitir que o script acesse as planilhas e envie e-mails pelo Gmail. A primeira caixa de diálogo de autorização é assim:

ba6e1a798e404e0d.png

Clique em Revisar permissões para continuar.

Em seguida, você vai receber a janela de diálogo do OAuth2 pedindo permissão para acessar sua planilha e enviar e-mails em seu nome:

9bed7ef1ccbd7569.png

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

Verifique a conta de e-mail para onde você enviou a mensagem. Procure um e-mail com o assunto "Map" e uma mensagem parecida com esta:

51f61fc51a13d28f.png

Ao abrir o anexo na mensagem de e-mail, você vai receber um mapa do Google com um marcador no endereço inserido na planilha:

739bb45b75e3f7c7.png

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 se aprofundar no material abordado neste codelab e conhecer outras formas de acessar as ferramentas para desenvolvedores do Google de maneira programática.

Documentação

Vídeos

Notícias e atualizações

Outros codelabs

Básico

Intermediário

Aplicativos de referência