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 dati. Google offre le API di G Suite per aiutarti ad accedere alle informazioni in questi servizi in modo programmatico; puoi utilizzare le API per automatizzare facilmente il tuo flusso di lavoro giornaliero. 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 della piattaforma Google Cloud.

Cosa creerai

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

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

Cosa imparerai a fare

  • Nozioni di base sulle API RESTful di G Suite
  • Nozioni di base su Google Cloud Functions e altri servizi della piattaforma Google Cloud
  • Accedere a Gmail in modo programmatico con Google Cloud Functions

Che cosa ti serve

  • 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 serverless Functions as a Service di Google che 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 sinistra:

f457988e33594bb6.png

Trova Cloud Functions nel menu di navigazione e fai clic su questa opzione. 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 il flusso 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 sulla barra. 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 e fai clic su questa opzione nella barra laterale di navigazione a sinistra. 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 abilitare Google Cloud Datastore. il completamento potrebbe richiedere alcuni minuti.

Visione artificiale di Google Cloud

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

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

Abilitazione dell'API Gmail, dell'API Fogli Google e dell'API Google Cloud Vision

Apri di nuovo la barra laterale di navigazione a sinistra e trova API e Servizi. Fai clic su Libreria. Nella sezione Cerca API e Services, digita Gmail. Nei risultati di ricerca, seleziona API Gmail e fai clic su Abilita.

Torna alla pagina della Libreria API. Cerca API Fogli Google e abilitala.

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 tramite riga di comando alle risorse Google Cloud Platform direttamente dal tuo browser, consentendoti di gestirle senza utilizzare una macchina locale.

Per aprire Google Cloud Shell, fai clic sul pulsante Attiva Cloud Shell sulla 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 di Cloud Shell:

10f8631ef48bed22.png

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

Scarica il codice

Esegui il comando seguente 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 di 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, Gmail invia una notifica a Cloud Pub/Sub.
  2. Cloud Pub/Sub consegna 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 la posta 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 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 la lettura automatica delle 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 consenso OAuth.

91b2a3bac30bb2c5.png

Digita un nome nel campo Nome applicazione, ad esempio GCF + Codelab Gmail. Lascia invariate le altre impostazioni, scorri la pagina verso il basso 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 di Applicazione web, assegnagli un nome (qui potresti usare di nuovo GCF + Gmail Codelab), quindi fai clic su Crea. Per il momento, lascia vuoti i campi delle restrizioni.

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

1160d8027ea52d90.png

Eseguire il processo di autorizzazione

Nel codice di esempio, auth/index.js specifica due funzioni Cloud Functions, auth_init e auth_callback, che operano in sinergia per eseguire il processo di autorizzazione utilizzando l'ID client e il client secret appena creato.

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

Il processo 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 di accedere ai tuoi dati con ambito. auth_callback li salva in Cloud Datastore.
  • I token di aggiornamento vengono utilizzati per ottenere nuovi token di accesso e hanno una durata molto più lunga.

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

Modifica auth/env_vars.yaml nell'editor di codice di Cloud Shell. Sostituisci YOUR-GOOGLE-CLIENT-ID e YOUR-GOOGLE-CLIENT-SECRET con i tuoi valori. Per saperne di più, 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 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 delle funzioni Cloud Functions potrebbe richiedere alcuni minuti. Se richiesto, concedi a Cloud SDK l'autorizzazione a installare i comandi beta.

Quindi, 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 ancora 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 il seguente dominio 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 la parte restante come origine JavaScript autorizzata. Ad esempio, se il tuo 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. Configurare le notifiche push di Gmail

Se il processo di autorizzazione ha esito positivo, 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. Qualsiasi sottoscrittore all'argomento riceverà automaticamente le notifiche dei messaggi in arrivo non appena 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 autorizzare Gmail a inviare messaggi all'argomento Pub/Sub: fai clic sul menu contestuale dell'argomento che hai 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 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 che hai appena creato. Fai clic su Salva per applicare le modifiche.

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

348ab0a7e0c9cd03.png

Accedi con un account Gmail di tua proprietà. Ogni nuovo messaggio che arriva nella Posta in arrivo dell'account attiverà una notifica push. Una volta effettuato l'accesso, vedrai la pagina seguente:

cfdad62fd02de004.png

Fai clic su Consenti per autorizzare l'accesso. auth_callback completerà il processo di autorizzazione, salverà i token di accesso e configurerà le notifiche push di Gmail per te. Al termine del processo dovresti visualizzare il messaggio Successfully set up Gmail push notifications nel browser.

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. Elaborazione dei messaggi in arrivo

Come accennato in precedenza, qualsiasi sottoscrittore all'argomento Pub/Sub che hai creato riceverà notifiche quando arrivano nuovi messaggi nella tua posta in arrivo. pubsub/index.js specifica una funzione Cloud Functions, watchGmailMessages, che, dopo aver eseguito il deployment come sottoscrittore dell'argomento, leggerà i nuovi messaggi, classificherà le immagini allegate ed esporterà queste categorie in un foglio Google.

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

Recupero dei messaggi in corso...

Una notifica push di Gmail include l'indirizzo email a cui è associata la notifica e un ID cronologia. Per motivi di semplicità, in questo codelab ti basterà chiedere all'API Gmail l'ultimo messaggio quando arriva una notifica push. Per un risultato migliore, utilizza invece 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 le immagini allegate

Se il messaggio ha un'immagine allegata, 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 l'immagine di un cielo azzurro, l'API Cloud Vision potrebbe restituire i tag blu, cielo e natura.

watchGmailMessages utilizza la libreria 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 foglio Google

watchGmailMessages esporta i risultati di questa analisi in un foglio Google. Sono inclusi il nome del mittente, il nome dell'allegato e gli eventuali tag degli allegati immagine.

Per prima cosa, crea un foglio Google. Apri Fogli Google e fai clic sul modello Vuoto sotto Crea un nuovo foglio di lavoro. Copia l'ID del foglio. Ad esempio, se l'indirizzo nel browser è simile al seguente:

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

L'ID del foglio di lavoro è abcdefghij01234567890. Nell'editor di codice di 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 Fogli Google 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 questo comando 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 Functions potrebbe richiedere alcuni secondi.

7. Prova

Congratulazioni, hai terminato. Inviati un'email con un'immagine allegata. In pochi secondi vedrai il foglio Google che hai creato, che verrà aggiornato automaticamente con le informazioni da te fornite.