Otimize sua caixa de entrada do Gmail com o Google Cloud Functions

1. Introdução

Bilhões de empresas e pessoas usam o Gmail e outros serviços do G Suite para se comunicar e processar dados. O Google oferece APIs do G Suite para ajudar você a acessar informações nesses serviços de maneira programática, e você pode usar as APIs para automatizar seu fluxo de trabalho diário com facilidade. Neste laboratório, você vai criar uma extensão avançada do Gmail que categoriza automaticamente os e-mails recebidos e salva essas categorias em uma planilha Google. Esta extensão usará as APIs RESTful do G Suite, o Google Cloud Functions e outros serviços do Google Cloud Platform.

O que você criará

Neste laboratório, você criará e implantará algumas Funções do Cloud conectadas às APIs do G Suite e a outros serviços do Google Cloud Platform. Essas funções irão:

  • Autorizar o acesso seguro aos dados do Gmail e das Planilhas Google
  • Extraia imagens anexadas aos e-mails recebidos
  • Categorizar essas imagens usando a API Cloud Vision
  • Escrever essas categorias, o endereço do remetente e o nome do anexo em um arquivo das Planilhas Google

O que você vai aprender

  • Noções básicas das APIs RESTful do G Suite
  • Noções básicas do Google Cloud Functions e de outros serviços do Google Cloud Platform
  • Como acessar o Gmail de maneira programática usando o Google Cloud Functions

O que é necessário

  • Uma Conta do Google com acesso ao Gmail e às Planilhas Google. Se você não tiver uma, crie uma aqui.
  • Conhecimento básico de JavaScript/Node.js.

2. Antes de mais nada

Ative as APIs

Neste laboratório, você usará os seguintes produtos/serviços do Google:

  • Google Cloud Functions
  • Google Cloud Pub/Sub
  • Google Cloud Vision API
  • Google Cloud Datastore
  • API Gmail
  • API Google Sheets

Google Cloud Functions

O Google Cloud Functions é a plataforma de funções como serviço sem servidor do Google que permite executar snippets de código individuais ("funções") de maneira simples e escalonável.

Para ativar o Google Cloud Functions, clique no menu de navegação no canto superior esquerdo da tela para abrir a barra lateral de navegação à esquerda:

f457988e33594bb6.png

Encontre o Cloud Functions no menu de navegação e clique nele. Clique em Ativar API para ativar o Google Cloud Functions no projeto.

Google Cloud Pub/Sub

O Google Cloud Pub/Sub é uma base simples e escalonável para streaming de dados e entrega de eventos. Neste laboratório, ele faz a ponte entre o Gmail e o Google Cloud Functions.

Para ativar o Google Cloud Pub/Sub, abra a barra lateral de navegação à esquerda, encontre e clique em Pub/Sub. Clique em Ativar API para ativar o Google Cloud Pub/Sub no seu projeto.

Google Cloud Datastore

O Google Cloud Datastore é um banco de dados sem servidor escalonável e distribuído.

Para ativar o Google Cloud Datastore, na barra lateral de navegação à esquerda, encontre e clique em Datastore. Clique em Selecionar o modo Datastore na nova página.

98012c91fd4080d4.png

É possível usar qualquer local de banco de dados neste laboratório. clicar em Criar banco de dados para ativar o Google Cloud Datastore; o processo pode levar alguns minutos.

Google Cloud Vision

A API Google Cloud Vision é um serviço avançado de machine learning que usa modelos pré-treinados para gerar insights de imagens.

Consulte as instruções abaixo para saber como ativar a API Google Cloud Vision.

ativar a API Gmail, a API Google Sheets e a API Google Cloud Vision

Mais uma vez, abra a barra lateral de navegação esquerda e localize APIs e Serviços. Clique em Biblioteca. Na caixa de diálogo Pesquisar APIs e Services, digite Gmail. Nos resultados da pesquisa, selecione API Gmail e clique em Ativar.

Volte para a página da biblioteca de APIs. Pesquise e ative a API Google Sheets.

Repita o processo. Pesquise e ative a API Cloud Vision.

Abrir o Google Cloud Shell

Neste laboratório, você vai usar o Google Cloud Shell para realizar a maioria das operações. O Cloud Shell oferece acesso de linha de comando aos seus recursos do Google Cloud Platform diretamente no navegador, permitindo que você os gerencie sem usar uma máquina local.

Para abrir o Google Cloud Shell, clique no botão Ativar o Cloud Shell na barra horizontal azul superior:

fd5c2925ca9cdfdd.png

Um novo painel será exibido na parte inferior da tela:

34f498402e910802.png

Clique no botão Iniciar editor de código para iniciar o editor do Cloud Shell:

10f8631ef48bed22.png

O editor de código do Cloud Shell será aberto em uma nova janela.

Fazer o download do código

Execute o comando abaixo no Cloud Shell para clonar o projeto:

git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git

cd gcf-gmail-codelab

Uma nova pasta, gcf-gmail-codelab, vai aparecer no editor de código do Cloud Shell.

3. Visão geral da arquitetura

Confira abaixo o fluxo de trabalho deste laboratório:

79c5d3e43f674b33.png

  1. O usuário configura as notificações push do Gmail: toda vez que uma nova mensagem chega à caixa de entrada, o Gmail envia uma notificação para o Cloud Pub/Sub.
  2. O Cloud Pub/Sub entrega a notificação de nova mensagem ao Google Cloud Functions.
  3. Quando a notificação de nova mensagem chega, uma instância do Cloud Functions se conecta ao Gmail e recupera a nova mensagem.
  4. Se o e-mail tiver uma imagem como anexo, a instância do Cloud Functions chamará a API Cloud Vision para analisar o anexo.
  5. A instância do Cloud Functions atualiza uma planilha Google de sua escolha, especificando quem envia a mensagem e onde fazer o download do anexo.

4. Autorizar acesso ao Gmail

Antes de configurar uma função do Cloud para ler e-mails automaticamente, é preciso autorizar o acesso dela ao Gmail. Você precisa registrar um cliente OAuth no Google e criar um ID do cliente associado.

Registrar um cliente OAuth

No menu de navegação à esquerda do console do Google Cloud, encontre APIs e Serviços. Clique na Tela de permissão OAuth.

91b2a3bac30bb2c5.png

Digite um nome no campo Application name, como GCF + Gmail Codelab. Não altere as outras configurações, role a página para baixo e clique em Salvar.

Criar um ID do cliente associado

Alterne para a guia Credenciais. Clique em Criar credenciais e selecione ID do cliente OAuth. Escolha o tipo Aplicativo da Web, dê um nome a ele (você pode usar GCF + Gmail Codelab novamente aqui) e clique em Criar. Deixe os campos "Restrições" em branco por enquanto.

Anote o ID e a chave secreta do cliente retornada na janela pop-up. Clique no nome dele na página para ver esses valores novamente:

1160d8027ea52d90.png

Executar o processo de autorização

No código de amostra, auth/index.js especifica duas funções do Cloud, auth_init e auth_callback, que trabalham juntas para realizar o processo de autorização usando o ID e a chave secreta do cliente que você acabou de criar.

Para inspecionar o código, abra auth/index.js no editor de código do Cloud Shell.

O processo de autorização retorna dois tipos de tokens: de acesso e de atualização.

  • Os tokens de acesso são provas de identidade de curta duração que concedem a qualquer pessoa que os possuírem acesso com escopo aos seus dados. auth_callback as salva no Cloud Datastore.
  • Os tokens de atualização são usados para receber novos tokens de acesso e têm uma duração significativamente maior.

Normalmente, eles são criptografados e/ou armazenados separadamente dos tokens de acesso.

Edite auth/env_vars.yaml no editor de código do Cloud Shell. Substitua YOUR-GOOGLE-CLIENT-ID e YOUR-GOOGLE-CLIENT-SECRET pelos seus próprios valores. Veja a etapa anterior para mais informações. Não mude os valores de YOUR-GOOGLE-CLIENT-CALLBACK-URL e YOUR-PUBSUB-TOPIC por enquanto.

a2b4853c39a78bc6.png

Depois de editar auth/env_vars.yaml, execute o seguinte comando no Cloud Shell para implantar o Cloud Functions:

cd ~
cd gcf-gmail-codelab/auth

# Deploy Cloud Function auth_init
gcloud functions deploy auth_init --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

# Deploy Cloud Function auth_callback
gcloud functions deploy auth_callback --runtime=nodejs8 --trigger-http --env-vars-file=env_vars.yaml

A implantação do Cloud Functions pode levar alguns minutos. Se solicitado, conceda ao SDK Cloud a permissão para instalar comandos Beta.

Em seguida, acesse o console do Google Cloud e clique em Cloud Functions no menu de navegação à esquerda. Clique em auth_callback na lista do Cloud Functions e mude para a guia Gatilho.

cb094bd341f9b299.png

45678a327c80e0f1.png

Copie o URL da página. Volte para a página do Cloud Functions e clique em auth_init na lista. Na guia Geral, clique em Editar. Clique em Variáveis ambientais, rede, tempos limite e muito mais e substitua o valor de GOOGLE_CALLBACK_URL pelo URL que você copiou.

939ca3bd38047282.png

Clique em Implantar para aplicar as mudanças. Repita o processo e atualize auth_callback também.

Por fim, abra o menu de navegação à esquerda e clique em APIs e Serviços > Verificação de domínio. Para adicionar um domínio autorizado, clique em Adicionar domínio. Por exemplo, se o URL copiado antes for semelhante a

https://us-central1-my-project.cloudfunctions.net/auth_callback

Adicione o seguinte como um domínio autorizado:

us-central1-my-project.cloudfunctions.net

Pressione Adicionar domínio para confirmar.

4348748f232ceb87.png

Volte para a página Credenciais. Clique no nome do cliente OAuth e adicione o URL copiado como um URI de redirecionamento autorizado. Pressione Enter para confirmar.

Remova a parte /auth_callback do URL e adicione o restante como uma origem JavaScript autorizada. Por exemplo, se o URL for semelhante a

https://us-central1-my-project.cloudfunctions.net/auth_callback

Adicione o seguinte como a origem:

https://us-central1-my-project.cloudfunctions.net/

159bad719432582c.png

Pressione Enter para confirmar e clique em Salvar para aplicar as alterações.

5. Configurar notificações push do Gmail

Se o processo de autorização for bem-sucedido, o auth_callback chamará automaticamente a API Gmail para configurar as notificações push.

Para receber notificações push do Gmail, crie um tópico do Pub/Sub. Todos os assinantes do tópico receberão notificações de mensagens automaticamente quando chegarem no Gmail.

Para criar um tópico do Pub/Sub, acesse o console do Google Cloud e clique em Pub/Sub > Tópicos no menu de navegação à esquerda. Clique em Criar tópico. Digite o nome do tópico, como gmail-watch, e clique em Criar. Além disso, você precisa permitir que o Gmail envie mensagens ao seu tópico do Pub/Sub: clique no menu de contexto do tópico que você acabou de criar (três pontos verticais) e escolha Permissões; Clique em Adicionar membros, especifique gmail-api-push@system.gserviceaccount.com como um novo membro e atribua a ele o papel de Pub/Sub > Editor do Pub/Sub Por fim, clique em Salvar para aplicar as alterações.

Atualize a função do Cloud auth_callback para especificar qual tópico do Pub/Sub usar. Clique em Cloud Functions no menu de navegação à esquerda e selecione auth_callback na lista de funções do Cloud. Na guia Geral, clique em Editar. Clique em Mais e substitua o valor de PUBSUB_TOPIC pelo nome do tópico do Pub/Sub que você acabou de criar. Clique em Salvar para aplicar as mudanças.

Agora você já pode autorizar e configurar as notificações push do Gmail. Aguarde até que as novas alterações sejam concluídas e volte para a página Cloud Functions, selecione auth_init na lista do Cloud Functions e mude para a guia Gatilho. Clique no URL para acessar a página Fazer login com o Google:

348ab0a7e0c9cd03.png

Faça login com uma conta do Gmail que você possui. Qualquer nova mensagem que chegar na caixa de entrada da conta acionará uma notificação push. Após o login, você verá a página abaixo:

cfdad62fd02de004.png

Clique em Permitir para autorizar o acesso. auth_callback concluirá o processo de autorização, salvará os tokens de acesso e configurará as notificações push do Gmail para você. Você verá a mensagem Successfully set up Gmail push notifications no navegador quando esse processo for concluído.

Este codelab usa o pacote @google-cloud/express-oauth2-handlers para automatizar o fluxo de trabalho de autorização para você. Para mais informações, consulte o repositório no GitHub (link em inglês).

6. Processar mensagens recebidas

Como mencionamos anteriormente, qualquer assinante do tópico do Pub/Sub que você criou receberá notificações quando novas mensagens chegarem à sua caixa de entrada. pubsub/index.js especifica uma função do Cloud, watchGmailMessages, que, depois de implantada como assinante do tópico, lerá as novas mensagens, categorizará as imagens anexadas e exportará essas categorias para um arquivo das Planilhas Google.

Para inspecionar o código, abra pubsub/index.js no editor de código do Cloud Shell.

Recuperando mensagens

Uma notificação push do Gmail inclui o endereço de e-mail a que a notificação está associada e um ID do histórico. Por motivos de simplicidade, neste codelab, você vai simplesmente pedir à API Gmail a mensagem mais recente quando uma notificação push chegar. Para um resultado melhor, use o ID do histórico para procurar mensagens.

// Look up the most recent message.
const listMessagesRes = await gmail.users.messages.list({
  userId: email,
  maxResults: 1
});
const messageId = listMessagesRes.messages[0].id;

// Get the message using the message ID.
const message = await gmail.users.messages.get({
  userId: email,
  id: messageId
});

return message;

Analisar anexos de imagem

Se a mensagem tiver um anexo de imagem, o watchGmailMessages chamará a API Cloud Vision para anotar a imagem. Neste codelab, você vai solicitar que a API Cloud Vision classifique a imagem e retorne várias tags de imagem. Por exemplo, se você fornece uma imagem de um céu azul, a API Cloud Vision pode retornar as tags blue, sky e nature.

watchGmailMessages usa a biblioteca da API Cloud Vision para Node.js para chamar a API Cloud Vision:

// Tag the attachment using Cloud Vision API
const analyzeAttachment = async (data, filename) => {
  var topLabels = ['', '', ''];
  if (filename.endsWith('.png') || filename.endsWith('.jpg')) {
    const [analysis] = await visionClient.labelDetection({
      image: {
        content: Buffer.from(data, 'base64')
      }
    });
    const labels = analysis.labelAnnotations;
    topLabels = labels.map(x => x.description).slice(0, 3);
  }

  return topLabels;
};

Atualizar o Planilhas Google

watchGmailMessages exporta os resultados dessa análise para um arquivo do Planilhas Google. Ele inclui o nome do remetente, o nome do anexo e tags de anexos de imagem (se houver).

Primeiro, crie uma planilha Google. Abra as Planilhas Google e clique no modelo Em branco em Criar uma nova planilha. Copie o ID da planilha. Por exemplo, se o endereço no seu navegador for assim:

https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0

O ID da sua planilha é abcdefghij01234567890. No editor de código do Cloud Shell, atualize gcf-gmail-codelab/pubsub/env_vars.yaml e substitua YOUR-GOOGLE-SHEET-ID pelo seu próprio valor.

O watchGmailMessages se conecta à API Google Sheets para anexar informações:

const updateReferenceSheet = async (from, filename, topLabels) => {
  await googleSheets.spreadsheets.values.append({
    spreadsheetId: SHEET,
    range: SHEET_RANGE,
    valueInputOption: 'USER_ENTERED',
    requestBody: {
      range: SHEET_RANGE,
      majorDimension: 'ROWS',
      values: [
        [from, filename].concat(topLabels)
      ]
    }
  });
};

Última etapa

No editor de código do Cloud Shell, abra gcf-gmail-codelab/pubsub/env_vars.yaml e substitua YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET e YOUR-GOOGLE-CALLBACK-URL pelos seus próprios valores. É possível encontrar esses valores no Console do Google Cloud: abra o Cloud Functions no menu de navegação à esquerda, selecione auth_init na lista do Cloud Functions e procure a seção Variáveis de ambiente.

Implantar o código

Execute o comando abaixo para implantar a função do Cloud:

cd ~

cd gcf-gmail-codelab/pubsub

gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml

Se você nomeou seu tópico do Cloud Pub/Sub de um jeito diferente de gmail-watch, substitua gmail-watch pelo nome do tópico. A implantação da função do Cloud pode levar alguns segundos.

7. Faça um teste

Parabéns, você terminou! Envie um e-mail para seu endereço de e-mail com uma imagem anexada. Em alguns segundos, a planilha Google que você criou será atualizada automaticamente com as informações fornecidas.