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. Além disso, é possível usar as APIs para automatizar seu fluxo de trabalho diário com facilidade. Neste laboratório, você vai criar uma extensão do Gmail eficiente que categoriza automaticamente os e-mails nas mensagens recebidas e salva essas categorias em uma planilha Google. Essa extensão usa 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ê vai criar e implantar algumas funções do Cloud Functions conectadas às APIs do G Suite e a outros serviços do Google Cloud Platform. Essas funções vão:

  • Autorizar o acesso seguro aos seus dados do Gmail e do Google Planilhas
  • Extrair imagens anexadas a qualquer e-mail recebido
  • Categorizar essas imagens usando a API Cloud Vision
  • Escreva essas categorias, o endereço do remetente e o nome do anexo em uma planilha Google.

O que você vai aprender

  • Noções básicas das APIs RESTful do G Suite
  • Noções básicas do 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 ao Google Planilhas. 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ê vai 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 individuais de código ("funções") de maneira simples e escalonável.

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

f457988e33594bb6.png

Encontre e clique em Cloud Functions no menu de navegação. Clique em Ativar API para ativar o Google Cloud Functions no seu 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 serve como um serviço de entrega entre o Gmail e o Google Cloud Functions.

Para ativar o Google Cloud Pub/Sub, abra a barra lateral de navegação à esquerda, encontre Pub/Sub e clique nele. 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, encontre e clique em Datastore na barra lateral de navegação à esquerda. Clique em Selecionar o modo Datastore na nova página.

98012c91fd4080d4.png

Você pode usar qualquer local de banco de dados para este laboratório. Clique em Criar banco de dados para ativar o Google Cloud Datastore. Isso pode levar alguns minutos.

Google Cloud Vision

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

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

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

Abra a barra lateral de navegação à esquerda novamente e encontre APIs e serviços. Clique em Biblioteca. No campo Pesquisar APIs e serviços, digite Gmail. Nos resultados da pesquisa, selecione API Gmail e clique em Ativar.

Volte à 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 na parte de cima:

fd5c2925ca9cdfdd.png

Um novo painel vai aparecer na parte de baixo da tela:

34f498402e910802.png

Clique no botão Iniciar editor de código para iniciar o editor de código 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: sempre que uma nova mensagem chega à caixa de entrada, o Gmail envia uma notificação ao Cloud Pub/Sub.
  2. O Cloud Pub/Sub entrega a notificação da nova mensagem ao Google Cloud Functions.
  3. Ao receber a notificação de nova mensagem, uma instância do Cloud Functions se conecta ao Gmail e recupera a mensagem.
  4. Se o e-mail tiver uma imagem como anexo, a instância do Cloud Functions vai 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 baixar o anexo.

4. Autorizar o acesso ao Gmail

Antes de configurar uma função do Cloud para ler seus e-mails automaticamente, você precisa autorizar o acesso dela ao Gmail. É necessário 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 em Tela de permissão OAuth.

91b2a3bac30bb2c5.png

Digite um nome no campo Nome do aplicativo, 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

Mude para a guia Credenciais. Clique em Criar credenciais e escolha 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" vazios por enquanto.

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

1160d8027ea52d90.png

Realizar o processo de autorização

No exemplo de código, auth/index.js especifica duas funções do Cloud Functions, auth_init e auth_callback, que trabalham juntas para realizar o processo de autorização usando o ID do cliente e o segredo 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: tokens de acesso e tokens de atualização.

  • Os tokens de acesso são provas de identidade de curta duração que concedem a qualquer pessoa que os possua acesso limitado aos seus dados. O auth_callback os salva no Cloud Datastore.
  • Os tokens de atualização são usados para receber novos tokens de acesso e têm uma duração muito 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 por seus próprios valores. Consulte a etapa anterior para mais informações. Deixe os valores de YOUR-GOOGLE-CLIENT-CALLBACK-URL e YOUR-PUBSUB-TOPIC inalterados 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 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 à página do Cloud Functions e clique em auth_init na lista de funções. Na guia Geral, clique em Editar. Clique em Variáveis de ambiente, rede, tempos limite e muito mais e substitua o valor de GOOGLE_CALLBACK_URL pelo URL que você acabou de copiar.

939ca3bd38047282.png

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

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 anteriormente for parecido com

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 seu 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

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 mudanças.

5. Configurar notificações push do Gmail

Se o processo de autorização for bem-sucedido, auth_callback vai 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 inscritos no tópico vão receber notificações de mensagens recebidas automaticamente assim que elas chegarem do 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 dar permissão ao Gmail para enviar 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 a função de Pub/Sub > Editor do Pub/Sub. Por fim, clique em Salvar para aplicar as mudanças.

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 Cloud Functions. 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ê pode autorizar e configurar as notificações push do Gmail. Aguarde até que as novas mudanças sejam concluídas. Depois, volte à página Cloud Functions, selecione auth_init na lista de funções do Cloud e mude para a guia Gatilho. Clique no URL para ser redirecionado à página Fazer login com o Google:

348ab0a7e0c9cd03.png

Faça login com uma conta do Gmail que é sua. Qualquer nova mensagem que chegar à caixa de entrada da conta vai acionar uma notificação push. Depois de fazer login, você vai ver a página abaixo:

cfdad62fd02de004.png

Clique em Permitir para autorizar o acesso. O auth_callback vai concluir o processo de autorização, salvar os tokens de acesso e configurar as notificações push do Gmail para você. A mensagem Successfully set up Gmail push notifications vai aparecer 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 mais informações, consulte o repositório no GitHub.

6. Processar mensagens recebidas

Como mencionamos antes, qualquer assinante do tópico do Pub/Sub que você criou vai 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, vai ler as novas mensagens, categorizar as imagens anexadas e exportar essas categorias para uma planilha 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 associado a ela e um ID de histórico. Para simplificar, neste codelab, você vai pedir à API Gmail a mensagem mais recente quando uma notificação push chegar. Para um resultado melhor, use o ID do histórico para pesquisar 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 vai chamar a API Cloud Vision para fazer anotações na imagem. Neste codelab, você vai pedir à API Cloud Vision para classificar a imagem e retornar várias tags. Por exemplo, se você fornecer uma imagem de um céu azul, a API Cloud Vision poderá retornar as tags azul, céu e natureza.

O watchGmailMessages usa a biblioteca da API Cloud Vision para Node.js a fim de 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 planilha Google

watchGmailMessages exporta os resultados dessa análise para uma planilha 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 o Google Planilhas e clique no modelo Em branco em Iniciar uma nova planilha. Copie o ID da sua planilha. Por exemplo, se o endereço no navegador for assim:

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

O ID da sua planilha é abcdefghij01234567890. No editor de códigos do Cloud Shell, atualize gcf-gmail-codelab/pubsub/env_vars.yaml e substitua YOUR-GOOGLE-SHEET-ID pelo seu 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 por seus próprios valores. Para encontrar esses valores no console do Google Cloud, abra Cloud Functions no menu de navegação à esquerda, selecione auth_init na lista de 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ê deu ao tópico do Cloud Pub/Sub um nome diferente de gmail-watch, substitua gmail-watch no comando acima pelo nome do seu 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 si mesmo com uma imagem anexada. Em alguns segundos, a planilha Google criada será atualizada automaticamente com as informações fornecidas.