Zwiększ możliwości skrzynki odbiorczej Gmaila dzięki Google Cloud Functions

1. Wprowadzenie

Miliardy firm i osób fizycznych korzystają z Gmaila oraz innych usług G Suite do komunikacji i przetwarzania danych. Google oferuje interfejsy API G Suite, które ułatwiają programowy dostęp do informacji w tych usługach. Za pomocą tych interfejsów API możesz łatwo zautomatyzować codzienne przepływy pracy. W tym module utworzysz zaawansowane rozszerzenie do Gmaila, które automatycznie kategoryzuje wiadomości przychodzące i zapisuje te kategorie w arkuszu Google. To rozszerzenie będzie korzystać z interfejsów API typu REST G Suite, funkcji Google Cloud Functions i innych usług Google Cloud Platform.

Co utworzysz

W tym module utworzysz i wdrożysz kilka funkcji w Cloud Functions połączonych z interfejsami API G Suite i innymi usługami Google Cloud Platform. Te funkcje będą:

  • Autoryzacja bezpiecznego dostępu do danych w Gmailu i Arkuszach Google
  • Wyodrębnij obrazy dołączone do wszystkich przychodzących e-maili
  • Kategoryzowanie tych obrazów za pomocą interfejsu Cloud Vision API
  • Zapisz te kategorie, adres nadawcy i nazwę załącznika w arkuszu Google.

Czego się nauczysz

  • Podstawowe informacje o interfejsach API typu REST w G Suite
  • Podstawy Google Cloud Functions i innych usług Google Cloud Platform
  • Jak uzyskać programowy dostęp do Gmaila za pomocą Google Cloud Functions

Co będzie potrzebne

  • Mieć konto Google z dostępem do Gmaila i Arkuszy Google. Jeśli nie masz konta, utwórz je tutaj.
  • Podstawowa znajomość języka JavaScript/Node.js.

2. Zacznijmy od początku

Włączanie interfejsów API

W tym module dowiesz się, jak korzystać z tych usług Google:

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

Google Cloud Functions

Google Cloud Functions to opracowana przez Google platforma bezserwerowa typu „funkcje jako usługa”, która umożliwia uruchamianie poszczególnych fragmentów kodu („funkcje”) w prosty i skalowalny sposób.

Aby włączyć Google Cloud Functions, kliknij menu z 3 kreskami w lewym górnym rogu ekranu, aby otworzyć lewy pasek nawigacyjny:

f457988e33594bb6.png

W menu nawigacyjnym znajdź Cloud Functions i kliknij ją. Kliknij Włącz API, aby włączyć Google Cloud Functions w projekcie.

Google Cloud Pub/Sub

Google Cloud Pub/Sub to prosta i skalowalna podstawa strumieniowania danych i dostarczania zdarzeń. W tym module pełni on rolę pośrednika między Gmailem a Google Cloud Functions.

Aby włączyć Google Cloud Pub/Sub, otwórz lewy pasek nawigacyjny, znajdź Pub/Sub i kliknij tę usługę. Kliknij Włącz API, aby włączyć Google Cloud Pub/Sub w swoim projekcie.

Google Cloud Datastore

Google Cloud Datastore to skalowalna i rozproszona bezserwerowa baza danych.

Aby włączyć Google Cloud Datastore, na lewym pasku bocznym nawigacji znajdź Datastore i kliknij ją. Na nowej stronie kliknij Wybierz tryb Datastore.

98012c91fd4080d4.png

W tym module możesz użyć dowolnej lokalizacji bazy danych. Kliknij Utwórz bazę danych, aby włączyć Google Cloud Datastore. może potrwać kilka minut.

Google Cloud Vision,

Interfejs Google Cloud Vision API to zaawansowana usługa systemów uczących się, która używa już wytrenowanych modeli do wyciągania statystyk z Twoich obrazów.

Poniżej znajdziesz instrukcje włączania Google Cloud Vision API.

Włączam interfejsy Gmail API, Google Arkusze API i Google Cloud Vision API

Ponownie otwórz lewy pasek nawigacyjny i znajdź Interfejsy API Usługi. Kliknij Biblioteka. Sekcja Wyszukaj interfejsy API i Usługi, wpisz Gmail. Z poziomu wyników wyszukiwania wybierz Gmail API i kliknij Włącz.

Wróć na stronę Biblioteka interfejsów API. Wyszukaj Google Arkusze API i włącz go.

Powtórzenie procesu. Wyszukaj interfejs Cloud Vision API i włącz go.

Otwórz Google Cloud Shell

W tym module do wykonywania większości operacji będziesz używać Google Cloud Shell. Wiersz poleceń Cloud Shell zapewnia dostęp do zasobów Google Cloud Platform bezpośrednio z przeglądarki, dzięki czemu możesz nimi zarządzać bez użycia komputera lokalnego.

Aby otworzyć Google Cloud Shell, kliknij przycisk Aktywuj Cloud Shell na górnym niebieskim poziomym pasku:

fd5c2925ca9cdfdd.png

Na dole ekranu pojawi się nowy panel:

34f498402e910802.png

Kliknij przycisk Uruchom edytor kodu, aby uruchomić edytor kodu Cloud Shell:

10f8631ef48bed22.png

W nowym oknie otworzy się edytor kodu Cloud Shell.

Pobieranie kodu

Aby skopiować projekt, uruchom poniższe polecenie w Cloud Shell:

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

cd gcf-gmail-codelab

W edytorze kodu Cloud Shell powinien pojawić się nowy folder gcf-gmail-codelab.

3. Przegląd architektury

Poniżej przedstawiamy przepływ pracy w tym module:

79c5d3e43f674b33.png

  1. Użytkownik konfiguruje powiadomienia push w Gmailu: za każdym razem, gdy w skrzynce odbiorczej pojawi się nowa wiadomość, Gmail wysyła powiadomienie do Cloud Pub/Sub.
  2. Cloud Pub/Sub dostarcza do Google Cloud Functions powiadomienie o nowej wiadomości.
  3. Po otrzymaniu powiadomienia o nowej wiadomości instancja Cloud Functions łączy się z Gmailem i pobiera nową wiadomość.
  4. Jeśli wiadomość zawiera obraz jako załącznik, instancja Cloud Functions wywołuje interfejs Cloud Vision API, aby przeanalizować załącznik.
  5. Instancja Cloud Functions aktualizuje wybrany przez Ciebie arkusz Google, określając, kto wysyła wiadomość i skąd pobrać załącznik.

4. Autoryzuj dostęp do Gmaila

Zanim skonfigurujesz funkcję w Cloud Functions pod kątem automatycznego odczytywania e-maili, musisz autoryzować jej dostęp do Gmaila. Musisz zarejestrować klienta OAuth w Google i utworzyć powiązany identyfikator klienta.

Rejestrowanie klienta OAuth

W menu nawigacyjnym po lewej stronie konsoli Google Cloud znajdź Interfejsy API i Usługi. Kliknij Ekran zgody OAuth.

91b2a3bac30bb2c5.png

Wpisz nazwę w polu Nazwa aplikacji, na przykład GCF + Gmail Codelabs. Pozostaw inne ustawienia bez zmian, przewiń stronę w dół i kliknij Zapisz.

Utwórz powiązany identyfikator klienta

Otwórz kartę Dane logowania. Kliknij Utwórz dane logowania i wybierz Identyfikator klienta OAuth. Wybierz typ Aplikacja internetowa, nadaj jej nazwę (możesz użyć ponownie GCF i Gmail Codelabs) i kliknij Utwórz. Na razie pozostaw pola Ograniczenia puste.

Zapisz identyfikator klienta i klucz tajny klienta zwrócony w wyskakującym okienku. Możesz kliknąć na stronie nazwę klienta, aby ponownie wyświetlić te wartości:

1160d8027ea52d90.png

Przeprowadź proces autoryzacji

W przykładowym kodzie auth/index.js określa 2 funkcje w Cloud Functions (auth_init i auth_callback), które współpracują przy wykonywaniu procesu autoryzacji przy użyciu identyfikatora klienta i utworzonego właśnie tajnego klucza klienta.

Aby sprawdzić kod, otwórz auth/index.js w edytorze kodu Cloud Shell.

Proces autoryzacji zwraca 2 typy tokenów: tokeny dostępu i tokeny odświeżania.

  • Tokeny dostępu to ważne dokumenty tożsamości, które na krótki czas dają każdej osobie w ich imieniu dostęp do Twoich danych w zakresie ograniczonym. auth_callback zapisuje je w Cloud Datastore.
  • Tokeny odświeżania służą do uzyskiwania nowych tokenów dostępu i są znacznie dłuższe.

Zwykle są one zaszyfrowane lub przechowywane oddzielnie od tokenów dostępu.

Edytuj auth/env_vars.yaml w edytorze kodu Cloud Shell. Zastąp YOUR-GOOGLE-CLIENT-ID i YOUR-GOOGLE-CLIENT-SECRET własnymi wartościami. Więcej informacji znajdziesz w poprzednim kroku. Na razie pozostaw wartości YOUR-GOOGLE-CLIENT-CALLBACK-URL i YOUR-PUBSUB-TOPIC bez zmian.

a2b4853c39a78bc6.png

Po wprowadzeniu zmian w obiekcie auth/env_vars.yaml uruchom w Cloud Shell to polecenie, aby wdrożyć funkcje w 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

Wdrożenie funkcji w Cloud Functions może potrwać kilka minut. Jeśli pojawi się taka prośba, przyznaj Cloud SDK uprawnienia do instalowania poleceń beta.

Następnie otwórz konsolę Google Cloud i w menu nawigacyjnym po lewej stronie kliknij Cloud Functions. Kliknij auth_callback na liście funkcji w Cloud Functions i przejdź na kartę Aktywator.

cb094bd341f9b299.png

45678a327c80e0f1.png

Skopiuj adres URL ze strony. Wróć do strony Cloud Functions, kliknij auth_init na liście Cloud Functions. Na karcie Ogólne kliknij Edytuj. Kliknij Zmienne środowiskowe, sieć, limity czasu i inne ustawienia i zastąp wartość GOOGLE_CALLBACK_URL skopiowanym właśnie adresem URL.

939ca3bd38047282.png

Kliknij Wdróż, aby zastosować zmiany. Powtórz ten proces i zaktualizuj też auth_callback.

Na koniec otwórz menu nawigacyjne po lewej stronie i kliknij Interfejsy API Usługi > Weryfikacja domeny Aby dodać autoryzowaną domenę, kliknij Dodaj domenę. Jeśli na przykład skopiowany wcześniej adres URL wygląda tak:

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

Jako autoryzowaną domenę dodaj:

us-central1-my-project.cloudfunctions.net

Kliknij Dodaj domenę, aby potwierdzić tę czynność.

4348748f232ceb87.png

Wróć na stronę Dane logowania. Kliknij nazwę klienta OAuth i dodaj skopiowany adres URL w polu Autoryzowany identyfikator URI przekierowania. Aby potwierdzić, naciśnij Enter.

Usuń część /auth_callback z adresu URL i dodaj pozostałą część jako Autoryzowane źródło JavaScriptu. Jeśli na przykład adres URL wygląda tak:

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

Jako źródło dodaj:

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

159bad719432582c.png

Naciśnij Enter, aby potwierdzić, i kliknij Zapisz, aby zastosować zmiany.

5. Konfigurowanie powiadomień push w Gmailu

Jeśli proces autoryzacji się uda, auth_callback automatycznie wywoła interfejs Gmail API, aby skonfigurować powiadomienia push.

Aby otrzymywać powiadomienia push z Gmaila, musisz utworzyć temat Pub/Sub. Każdy subskrybent danego tematu będzie automatycznie otrzymywać powiadomienia o nowych wiadomościach przychodzących z Gmaila.

Aby utworzyć temat Pub/Sub, otwórz konsolę Google Cloud i kliknij Pub/Sub > Tematy w menu nawigacyjnym po lewej stronie. Kliknij Utwórz temat. Wpisz nazwę tematu, na przykład gmail-watch, i kliknij Utwórz. Musisz też przyznać Gmailowi uprawnienia do wysyłania wiadomości do tematu Pub/Sub. W tym celu kliknij menu kontekstowe tworzonego tematu (3 pionowe kropki) i wybierz Uprawnienia. kliknij Dodaj użytkowników, określ użytkownika gmail-api-push@system.gserviceaccount.com jako nowego użytkownika i nadaj mu rolę Pub/Sub > wydawca Pub/Sub; na koniec kliknij Zapisz, aby zastosować zmiany.

Zaktualizuj funkcję w Cloud Functions auth_callback, aby określić temat Pub/Sub, którego chcesz użyć. W menu nawigacyjnym po lewej stronie kliknij Cloud Functions, a następnie na liście funkcji w Cloud Functions wybierz auth_callback. Na karcie Ogólne kliknij Edytuj. Kliknij More (Więcej) i zastąp wartość PUBSUB_TOPIC nazwą nowo utworzonego tematu Pub/Sub. Aby zastosować zmiany, kliknij Zapisz.

Teraz możesz autoryzować i skonfigurować powiadomienia push w Gmailu. Poczekaj, aż nowe zmiany zostaną wprowadzone, a potem wróć na stronę Cloud Functions, wybierz auth_init na liście Cloud Functions i przejdź na kartę Aktywator. Kliknij adres URL, aby przejść na stronę Zaloguj się przez Google:

348ab0a7e0c9cd03.png

Zaloguj się na konto Gmail, którego jesteś właścicielem. Każda nowa wiadomość, która pojawi się w skrzynce odbiorczej konta, będzie powodować wysłanie powiadomienia push. Po zalogowaniu się zobaczysz stronę poniżej:

cfdad62fd02de004.png

Kliknij Zezwól, aby autoryzować dostęp. auth_callback ukończy proces autoryzacji, zapisze tokeny dostępu i skonfiguruje za Ciebie powiadomienia push w Gmailu. Po zakończeniu tego procesu w przeglądarce powinien pojawić się komunikat Successfully set up Gmail push notifications.

W ramach tego ćwiczenia w Codelabs używany jest pakiet @google-cloud/express-oauth2-handlers, aby zautomatyzować proces autoryzacji. Więcej informacji znajdziesz w repozytorium tej usługi na GitHubie.

6. Przetwarzanie wiadomości przychodzących

Jak wspomnieliśmy wcześniej, każdy subskrybent utworzonego przez Ciebie tematu Pub/Sub będzie otrzymywać powiadomienia, gdy w Twojej skrzynce odbiorczej pojawią się nowe wiadomości. pubsub/index.js określa funkcję w Cloud Functions (watchGmailMessages), która po wdrożeniu jako subskrybenta tematu będzie odczytywać nowe wiadomości, kategoryzować dołączone obrazy i eksportować te kategorie do Arkuszy Google.

Aby sprawdzić kod, otwórz pubsub/index.js w edytorze kodu Cloud Shell.

Pobieram wiadomości

Powiadomienie push w Gmailu zawiera adres e-mail, z którym jest powiązane powiadomienie, oraz identyfikator historii. Dla uproszczenia podczas tego ćwiczenia z programowania po prostu zapytasz interfejs Gmail API o najnowszą wiadomość, gdy otrzymasz powiadomienie push. Aby uzyskać lepszy wynik, użyj identyfikatora historii do wyszukiwania wiadomości.

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

Analizowanie załączników graficznych

Jeśli wiadomość zawiera załącznik ze zdjęciem, watchGmailMessages wywoła interfejs Cloud Vision API, aby dodać adnotację do obrazu. W ramach tego ćwiczenia w programie poprosisz Cloud Vision API o sklasyfikowanie obrazu i zwrócenie liczby tagów obrazów. Jeśli na przykład udostępnisz obraz błękitnego nieba, Cloud Vision API może zwrócić tagi niebieskie, niebo i przyroda.

watchGmailMessages używa biblioteki Cloud Vision API dla Node.js do wywoływania Cloud Vision API:

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

Zaktualizuj Arkusz Google

watchGmailMessages eksportuje wyniki tej analizy do Arkuszy Google. Zawiera ona nazwę nadawcy, nazwę załącznika i tagi załączników graficznych (jeśli występują).

Najpierw utwórz plik Arkuszy Google. Otwórz Arkusze Google i w sekcji Rozpocznij nowy arkusz kalkulacyjny kliknij szablon Pusty. Skopiuj identyfikator arkusza. Jeśli na przykład adres w przeglądarce wygląda tak:

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

Identyfikator Twojego arkusza kalkulacyjnego to abcdefghij01234567890. W edytorze kodu Cloud Shell zaktualizuj gcf-gmail-codelab/pubsub/env_vars.yaml i zastąp YOUR-GOOGLE-SHEET-ID własną wartością.

watchGmailMessages łączy się z interfejsem Google Arkuszy API, aby dołączać informacje:

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

Ostatnia czynność

W edytorze kodu Cloud Shell otwórz plik gcf-gmail-codelab/pubsub/env_vars.yaml i zastąp YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET oraz YOUR-GOOGLE-CALLBACK-URL własnymi wartościami. Te wartości znajdziesz w konsoli Google Cloud: otwórz Cloud Functions w menu nawigacyjnym po lewej stronie, wybierz auth_init na liście funkcji w Cloud Functions i odszukaj sekcję Zmienne środowiskowe.

Wdrażanie kodu

Uruchom poniższe polecenie, aby wdrożyć funkcję w Cloud Functions:

cd ~

cd gcf-gmail-codelab/pubsub

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

Jeśli nazwa tematu Cloud Pub/Sub jest inna niż gmail-watch, zastąp gmail-watch w powyższym poleceniu nazwą tematu. Wdrożenie funkcji w Cloud Functions może potrwać kilka sekund.

7. Wypróbuj

Gratulacje, to już wszystko! Wyślij do siebie e-maila z załączonym obrazem. Po kilku sekundach utworzony przez Ciebie arkusz Google zostanie automatycznie zaktualizowany na podstawie podanych przez Ciebie informacji.