Potenzia la tua Posta in arrivo di Gmail con Google Cloud Functions

1. Introduzione

Miliardi di aziende e privati utilizzano Gmail e altri servizi G Suite per comunicare ed elaborare i dati. Google offre le API G Suite per aiutarti ad accedere alle informazioni in questi servizi a livello di programmazione e puoi utilizzare le API per automatizzare facilmente il tuo flusso di lavoro quotidiano. In questo lab, creerai una potente estensione di Gmail che classifica automaticamente le email nei messaggi in arrivo e salva queste categorie in un foglio Google. Questa estensione utilizzerà le API RESTful di G Suite, Google Cloud Functions e altri servizi Google Cloud.

Cosa creerai

In questo lab creerai ed eseguirai il deployment di alcune Cloud Functions connesse alle API G Suite e ad altri servizi Google Cloud. Queste funzioni:

  • Autorizzare l'accesso sicuro ai dati di Gmail e Google Fogli
  • Estrai le immagini allegate a qualsiasi email in arrivo
  • Categorizza queste immagini utilizzando l'API Cloud Vision
  • Scrivi queste categorie, l'indirizzo del mittente e il nome dell'allegato in un foglio Google.

Cosa imparerai a fare

  • Nozioni di base delle API RESTful di G Suite
  • Nozioni di base di Google Cloud Functions e di altri servizi Google Cloud Platform
  • Come accedere a Gmail in modo programmatico utilizzando Google Cloud Functions

Che cosa ti serve

  • Un Account Google con accesso a Gmail e Fogli Google. Se non ne hai uno, creane uno qui.
  • Conoscenza di base di JavaScript/Node.js.

2. Partiamo dall'inizio

Abilita le API

In questo lab utilizzerai i seguenti prodotti/servizi Google:

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

Google Cloud Functions

Google Cloud Functions è la piattaforma Functions-as-a-Service serverless di Google che ti consente di eseguire singoli snippet di codice ("funzioni") in modo semplice e scalabile.

Per attivare Google Cloud Functions, fai clic sul menu a tre linee in alto a sinistra dello schermo per aprire la barra laterale di navigazione a sinistra:

f457988e33594bb6.png

Individua Cloud Functions nel menu di navigazione e fai clic. Fai clic su Abilita API per abilitare Google Cloud Functions nel tuo progetto.

Google Cloud Pub/Sub

Google Cloud Pub/Sub è una base semplice e scalabile per lo streaming di dati e la distribuzione di eventi. In questo lab funge da corriere tra Gmail e Google Cloud Functions.

Per attivare Google Cloud Pub/Sub, apri la barra di navigazione laterale a sinistra, individua Pub/Sub e fai clic. Fai clic su Abilita API per abilitare Google Cloud Pub/Sub nel tuo progetto.

Google Cloud Datastore

Google Cloud Datastore è un database serverless scalabile e distribuito.

Per attivare Google Cloud Datastore, individua Datastore nella barra di navigazione a sinistra e fai clic. Fai clic su Seleziona modalità Datastore nella nuova pagina.

98012c91fd4080d4.png

Per questo lab puoi utilizzare qualsiasi posizione del database. Fai clic su Crea database per attivare Google Cloud Datastore. L'operazione potrebbe richiedere alcuni minuti.

Google Cloud Vision

L'API Google Cloud Vision è un potente servizio di machine learning che utilizza modelli preaddestrati per ricavare informazioni dalle tue immagini.

Consulta le istruzioni riportate di seguito per informazioni su come attivare l'API Google Cloud Vision.

Attivazione dell'API Gmail, dell'API Google Sheets e dell'API Google Cloud Vision

Apri di nuovo la barra laterale di navigazione a sinistra e trova API e servizi. Fai clic su Raccolta. Nel campo Cerca API e servizi, digita Gmail. Nei risultati di ricerca, seleziona API Gmail e fai clic su Attiva.

Torna alla pagina Libreria API. Cerca l'API Google Sheets e attivala.

Ripeti la procedura. Cerca l'API Cloud Vision e abilitala.

Apri Google Cloud Shell

In questo lab utilizzerai Google Cloud Shell per eseguire la maggior parte delle operazioni. Cloud Shell fornisce l'accesso da riga di comando alle risorse Google Cloud direttamente dal browser, consentendoti di gestirle senza utilizzare una macchina locale.

Per aprire Google Cloud Shell, fai clic sul pulsante Attiva Cloud Shell nella barra orizzontale blu in alto:

fd5c2925ca9cdfdd.png

Nella parte inferiore dello schermo verrà visualizzato un nuovo riquadro:

34f498402e910802.png

Fai clic sul pulsante Avvia editor di codice per avviare l'editor di codice Cloud Shell:

10f8631ef48bed22.png

L'editor di codice di Cloud Shell si aprirà in una nuova finestra.

Scarica il codice

Esegui il comando riportato di seguito in Cloud Shell per clonare il progetto:

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

cd gcf-gmail-codelab

Dovresti visualizzare una nuova cartella, gcf-gmail-codelab, nell'editor di codice Cloud Shell.

3. Panoramica dell'architettura

Di seguito è riportato il flusso di lavoro di questo lab:

79c5d3e43f674b33.png

  1. L'utente configura le notifiche push di Gmail: ogni volta che arriva un nuovo messaggio nella posta in arrivo, Gmail invia una notifica a Cloud Pub/Sub.
  2. Cloud Pub/Sub invia la notifica del nuovo messaggio a Google Cloud Functions.
  3. All'arrivo della notifica del nuovo messaggio, un'istanza di Cloud Functions si connette a Gmail e recupera il nuovo messaggio.
  4. Se l'email ha un'immagine come allegato, l'istanza Cloud Functions chiama l'API Cloud Vision per analizzare l'allegato.
  5. L'istanza Cloud Functions aggiorna un foglio Google a tua scelta, specificando chi invia il messaggio e dove scaricare l'allegato.

4. Autorizzare l'accesso a Gmail

Prima di configurare una Cloud Function per leggere automaticamente le tue email, devi autorizzarne l'accesso a Gmail. Dovrai registrare un client OAuth con Google e creare un ID client associato.

Registrare un client OAuth

Nel menu di navigazione a sinistra della console Google Cloud, trova API e servizi. Fai clic su Schermata per il consenso OAuth.

91b2a3bac30bb2c5.png

Digita un nome nel campo Nome applicazione, ad esempio GCF + Gmail Codelab. Lascia invariate le altre impostazioni, scorri verso il basso della pagina e fai clic su Salva.

Creare un ID client associato

Passa alla scheda Credenziali. Fai clic su Crea credenziali e scegli ID client OAuth. Scegli il tipo Applicazione web, assegnagli un nome (puoi utilizzare di nuovo GCF + Gmail Codelab) e fai clic su Crea. Per il momento, lascia vuoti i campi Limitazioni.

Prendi nota dell'ID client e del client secret restituiti nella finestra popup. Puoi fare clic sul nome del cliente nella pagina per visualizzare di nuovo questi valori:

1160d8027ea52d90.png

Eseguire la procedura di autorizzazione

Nel codice di esempio, auth/index.js specifica due Cloud Functions, auth_init e auth_callback, che collaborano per eseguire la procedura di autorizzazione utilizzando l'ID client e il client secret appena creati.

Per esaminare il codice, apri auth/index.js nell'editor di codice di Cloud Shell.

La procedura di autorizzazione restituisce due tipi di token: token di accesso e token di aggiornamento.

  • I token di accesso sono prove di identità di breve durata che concedono a chiunque ne sia in possesso un accesso limitato ai tuoi dati; auth_callback li salva in Cloud Datastore.
  • I token di aggiornamento vengono utilizzati per ottenere nuovi token di accesso e hanno una durata significativamente più lunga.

In genere, sono criptati e/o archiviati separatamente dai token di accesso.

Modifica auth/env_vars.yaml nell'editor di codice Cloud Shell. Sostituisci YOUR-GOOGLE-CLIENT-ID e YOUR-GOOGLE-CLIENT-SECRET con i tuoi valori. Per maggiori informazioni, consulta il passaggio precedente. Per ora lascia invariati i valori di YOUR-GOOGLE-CLIENT-CALLBACK-URL e YOUR-PUBSUB-TOPIC.

a2b4853c39a78bc6.png

Dopo aver modificato auth/env_vars.yaml, esegui questo comando in Cloud Shell per eseguire il deployment delle funzioni 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

Il deployment di Cloud Functions potrebbe richiedere alcuni minuti. Se richiesto, concedi a Cloud SDK l'autorizzazione per installare i comandi beta.

Poi, vai a Google Cloud Console e fai clic su Cloud Functions nel menu di navigazione a sinistra. Fai clic su auth_callback nell'elenco di Cloud Functions e passa alla scheda Trigger.

cb094bd341f9b299.png

45678a327c80e0f1.png

Copia l'URL della pagina. Torna alla pagina Cloud Functions e fai clic su auth_init nell'elenco delle funzioni Cloud. Nella scheda Generale, fai clic su Modifica. Fai clic su Variabili ambientali, networking, timeout e altro ancora e sostituisci il valore di GOOGLE_CALLBACK_URL con l'URL che hai appena copiato.

939ca3bd38047282.png

Fai clic su Esegui il deployment per applicare le modifiche. Ripeti la procedura e aggiorna anche auth_callback.

Infine, apri il menu di navigazione a sinistra e fai clic su API e servizi > Verifica del dominio. Per aggiungere un dominio autorizzato, fai clic su Aggiungi dominio. Ad esempio, se l'URL che hai copiato in precedenza ha il seguente aspetto:

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

Devi aggiungere quanto segue come dominio autorizzato:

us-central1-my-project.cloudfunctions.net

Premi Aggiungi dominio per confermare.

4348748f232ceb87.png

Torna alla pagina Credenziali. Fai clic sul nome del client OAuth e aggiungi l'URL che hai copiato come URI di reindirizzamento autorizzato. Premi Invio per confermare.

Rimuovi la parte /auth_callback dall'URL e aggiungi il resto come origine JavaScript autorizzata. Ad esempio, se il tuo URL ha il seguente aspetto:

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

Devi aggiungere quanto segue come origine:

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

159bad719432582c.png

Premi Invio per confermare e fai clic su Salva per applicare le modifiche.

5. Configurare le notifiche push di Gmail

Se la procedura di autorizzazione va a buon fine, auth_callback chiamerà automaticamente l'API Gmail per configurare le notifiche push.

Per ricevere le notifiche push di Gmail, devi creare un argomento Pub/Sub. Tutti gli abbonati all'argomento riceveranno automaticamente le notifiche dei messaggi in arrivo non appena arriveranno da Gmail.

Per creare un argomento Pub/Sub, vai alla console Google Cloud e fai clic su Pub/Sub > Argomenti nel menu di navigazione a sinistra. Fai clic su Crea argomento. Digita il nome dell'argomento, ad esempio gmail-watch, e fai clic su Crea. Inoltre, devi concedere a Gmail l'autorizzazione a inviare messaggi all'argomento Pub/Sub: fai clic sul menu contestuale dell'argomento appena creato (tre puntini verticali) e scegli Autorizzazioni; fai clic su Aggiungi membri, specifica gmail-api-push@system.gserviceaccount.com come nuovo membro e assegnagli il ruolo di Pub/Sub > Publisher Pub/Sub; infine, fai clic su Salva per applicare le modifiche.

Aggiorna la funzione Cloud Functions auth_callback per specificare quale argomento Pub/Sub utilizzare. Fai clic su Cloud Functions nel menu di navigazione a sinistra e seleziona auth_callback nell'elenco delle Cloud Functions. Nella scheda Generale, fai clic su Modifica. Fai clic su Altro e sostituisci il valore di PUBSUB_TOPIC con il nome dell'argomento Pub/Sub che hai appena creato. Fai clic su Salva per applicare le modifiche.

Ora puoi autorizzare e configurare le notifiche push di Gmail. Attendi il completamento delle nuove modifiche, poi torna alla pagina Cloud Functions, seleziona auth_init nell'elenco di Cloud Functions e passa alla scheda Trigger. Fai clic sull'URL e verrà visualizzata la pagina Accedi con Google:

348ab0a7e0c9cd03.png

Accedi con un account Gmail di tua proprietà. Qualsiasi nuovo messaggio in arrivo nella Posta in arrivo dell'account attiverà una notifica push. Dopo aver eseguito l'accesso, vedrai la pagina seguente:

cfdad62fd02de004.png

Fai clic su Consenti per autorizzare l'accesso. auth_callback completerà la procedura di autorizzazione, salverà i token di accesso e configurerà le notifiche push di Gmail per te. Al termine della procedura, nel browser dovrebbe essere visualizzato il messaggio Successfully set up Gmail push notifications.

Questo codelab utilizza il pacchetto @google-cloud/express-oauth2-handlers per automatizzare il flusso di lavoro di autorizzazione. Per maggiori informazioni, consulta il repository su GitHub.

6. Elaborare i messaggi in arrivo

Come abbiamo detto in precedenza, tutti gli iscritti all'argomento Pub/Sub che hai creato riceveranno notifiche quando arrivano nuovi messaggi nella tua posta in arrivo. pubsub/index.js specifica una funzione Cloud Functions, watchGmailMessages, che, una volta implementata come abbonato all'argomento, leggerà i nuovi messaggi, classificherà le immagini allegate ed esporterà queste categorie in un foglio Google.

Per esaminare il codice, apri pubsub/index.js nell'editor di codice di Cloud Shell.

Recupero dei messaggi

Una notifica push di Gmail include l'indirizzo email a cui è associata la notifica e un ID cronologia. Per semplicità, in questo codelab chiederai semplicemente all'API Gmail l'ultimo messaggio quando arriva una notifica push. Per un risultato migliore, utilizza l'ID cronologia per cercare i messaggi.

// 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;

Analizzare gli allegati immagine

Se il messaggio ha un allegato immagine, watchGmailMessages chiamerà l'API Cloud Vision per annotare l'immagine. In questo codelab, chiederai all'API Cloud Vision di classificare l'immagine e restituire una serie di tag immagine. Ad esempio, se viene fornita un'immagine di un cielo blu, l'API Cloud Vision potrebbe restituire i tag blu, cielo e natura.

watchGmailMessages utilizza la libreria dell'API Cloud Vision per Node.js per chiamare l'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;
};

Aggiorna il foglio Google

watchGmailMessages esporta i risultati di questa analisi in un foglio Google. Include il nome del mittente, il nome dell'allegato e i tag degli allegati immagine (se presenti).

Innanzitutto, crea un foglio Google. Apri Fogli Google e fai clic sul modello Vuoto in Crea un nuovo foglio di lavoro. Copia l'ID del foglio. Ad esempio, se l'indirizzo nel browser ha il seguente aspetto:

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

L'ID del tuo foglio di lavoro è abcdefghij01234567890. Nell'editor di Cloud Shell Code, aggiorna gcf-gmail-codelab/pubsub/env_vars.yaml e sostituisci YOUR-GOOGLE-SHEET-ID con il tuo valore.

watchGmailMessages si connette all'API Google Sheets per aggiungere informazioni:

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)
      ]
    }
  });
};

Un ultimo passaggio

Nell'editor di codice di Cloud Shell, apri gcf-gmail-codelab/pubsub/env_vars.yaml e sostituisci YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET e YOUR-GOOGLE-CALLBACK-URL con i tuoi valori. Puoi trovare questi valori nella console Google Cloud: apri Cloud Functions nel menu di navigazione a sinistra, seleziona auth_init nell'elenco di Cloud Functions e cerca la sezione Variabili di ambiente.

Esegui il deployment del codice

Esegui il comando riportato di seguito per eseguire il deployment della funzione Cloud Functions:

cd ~

cd gcf-gmail-codelab/pubsub

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

Se hai assegnato all'argomento Cloud Pub/Sub un nome diverso da gmail-watch, sostituisci gmail-watch nel comando precedente con il nome dell'argomento. Il deployment della funzione cloud potrebbe richiedere alcuni secondi.

7. Prova

Congratulazioni, hai finito. Inviati un'email con un allegato immagine. In pochi secondi vedrai il foglio Google che hai creato aggiornarsi automaticamente con le informazioni che fornisci.