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 in modo programmatico e puoi utilizzare le API per automatizzare facilmente il tuo workflow 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 Platform.

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 Platform. Queste funzioni:

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

Cosa imparerai a fare

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

Di cosa avrai bisogno

  • Un Account Google con accesso a Gmail e Fogli Google. Se non ne hai uno, crealo 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 abilitare Google Cloud Functions, fai clic sul menu hamburger in alto a sinistra dello schermo per aprire la barra laterale di navigazione a sinistra:

f457988e33594bb6.png

Trova Cloud Functions nel menu di navigazione e fai clic su di esso. 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 abilitare Google Cloud Pub/Sub, apri la barra laterale di navigazione a sinistra, trova Pub/Sub e fai clic su di esso. 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 abilitare Google Cloud Datastore, nella barra laterale di navigazione a sinistra, trova Datastore e fai clic su di esso. Fai clic su Seleziona modalità Datastore nella nuova pagina.

98012c91fd4080d4.png

Per questo lab puoi utilizzare qualsiasi località del database. Fai clic su Crea database per abilitare Google Cloud Datastore. La procedura potrebbe richiedere alcuni minuti.

Google Cloud Vision

L'API Cloud Vision di Google è un potente servizio di machine learning che utilizza modelli pre-addestrati per ricavare insight dalle immagini.

Per informazioni su come abilitare l'API Cloud Vision di Google, consulta le istruzioni riportate di seguito.

Abilitare l'API Gmail, l'API Google Sheets e l'API Cloud Vision di Google

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

Torna alla pagina Libreria API. Cerca API Google Sheets e abilitala.

Il processo si ripete Cerca 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 Platform 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 Cloud Shell si aprirà in una nuova finestra.

Scarica il codice

Esegui il comando in basso in Cloud Shell per clonare il progetto:

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

cd gcf-gmail-codelab

Dovresti vedere 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 di Cloud Functions chiama l'API Cloud Vision per analizzare l'allegato.
  5. L'istanza di Cloud Functions aggiorna un foglio Google di tua scelta, specificando chi invia il messaggio e dove scaricare l'allegato.

4. Autorizza l'accesso a Gmail

Prima di configurare una funzione Cloud Functions 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.

Registra 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 nella pagina e fai clic su Salva.

Crea 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 Restrizioni.

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

1160d8027ea52d90.png

Esegui la procedura di autorizzazione

Nel codice campione, auth/index.js specifica due Cloud Functions, auth_init e auth_callback, che funzionano insieme 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 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 li possieda l'accesso con ambito 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 il momento, lascia invariati i valori di YOUR-GOOGLE-CLIENT-CALLBACK-URL e YOUR-PUBSUB-TOPIC.

a2b4853c39a78bc6.png

Dopo aver modificato auth/env_vars.yaml, esegui il comando seguente in Cloud Shell per eseguire il deployment di 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 alla console Google Cloud 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 nella pagina. Torna alla pagina Cloud Functions e fai clic su auth_init nell'elenco di Cloud Functions. Nella scheda Generale, fai clic su Modifica. Fai clic su Variabili di ambiente, networking, timeout e altro e sostituisci il valore di GOOGLE_CALLBACK_URL con l'URL 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 copiato in precedenza è simile a

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 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 l'URL è simile a

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. Configura 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 quando arrivano 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 per 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 di 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 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 verrai reindirizzato alla pagina Accedi con Google:

348ab0a7e0c9cd03.png

Accedi con un account Gmail di tua proprietà. Qualsiasi nuovo messaggio che arriva 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. Elabora i messaggi in arrivo

Come abbiamo detto in precedenza, tutti gli abbonati all'argomento Pub/Sub creato riceveranno notifiche quando arrivano nuovi messaggi nella Posta in arrivo. pubsub/index.js specifica una funzione Cloud Functions, watchGmailMessages, che, una volta eseguito il deployment 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 Cloud Shell.

Recupera i messaggi

Una notifica push di Gmail include l'indirizzo email a cui è associata 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;

Analizza 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 è simile a questo:

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

L'ID del foglio di lavoro è abcdefghij01234567890. Nell'editor di codice Cloud Shell, 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 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 in basso per eseguire il deployment di 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 di Cloud Functions potrebbe richiedere alcuni secondi.

7. Prova

Congratulazioni, hai finito. Invia un'email con un allegato immagine. Tra qualche secondo vedrai che il foglio Google creato si aggiorna automaticamente con le informazioni che fornisci.