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

1. Wprowadzenie

Miliardy firm i osób prywatnych korzystają z Gmaila i innych usług G Suite do komunikacji i przetwarzania danych. Google udostępnia interfejsy G Suite API, które umożliwiają programowy dostęp do informacji w tych usługach. Możesz ich używać do łatwego automatyzowania codziennych zadań. W tym module utworzysz zaawansowane rozszerzenie Gmaila, które automatycznie kategoryzuje e-maile w wiadomościach przychodzących i zapisuje te kategorie w arkuszu Google. To rozszerzenie będzie korzystać z interfejsów API RESTful G Suite, Google Cloud Functions i innych usług Google Cloud Platform.

Co utworzysz

W tym module utworzysz i wdrożysz kilka funkcji Cloud Functions połączonych z interfejsami API G Suite i innymi usługami Google Cloud Platform. Funkcje te:

Autoryzowanie bezpiecznego dostępu do danych Gmaila i Arkuszy Google
wyodrębniać obrazy załączone do dowolnego e-maila przychodzącego;
kategoryzować te obrazy za pomocą Cloud Vision API.
Zapisz te kategorie, adres nadawcy i nazwę załącznika w arkuszu Google.

Czego się nauczysz

Podstawy interfejsów API REST G Suite
Podstawy Google Cloud Functions i innych usług Google Cloud Platform
Jak uzyskać dostęp do Gmaila za pomocą Google Cloud Functions

Co będzie potrzebne

Konto Google z dostępem do Gmaila i Arkuszy Google. Jeśli nie masz konta, utwórz je tutaj.
ma podstawową wiedzę o JavaScript/Node.js;

2. Zacznijmy od początku

Włączanie interfejsów API

W tym module użyjesz tych usług i produktów 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 bezserwerowa platforma „funkcje jako usługa” od Google, która umożliwia uruchamianie pojedynczych fragmentów kodu („funkcji”) 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ć pasek nawigacyjny po lewej stronie:

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

Google Cloud Pub/Sub

Google Cloud Pub/Sub to prosta i skalowalna platforma do przesyłania strumieniowego danych i dostarczania zdarzeń. W tym module pełni rolę kuriera między Gmailem a funkcjami w Cloud Functions.

Aby włączyć Google Cloud Pub/Sub, otwórz pasek nawigacyjny po lewej stronie, znajdź Pub/Sub i kliknij tę usługę. Aby włączyć Google Cloud Pub/Sub w projekcie, kliknij Włącz interfejs API.

Google Cloud Datastore

Google Cloud Datastore to bezserwerowa baza danych, która jest skalowalna i rozproszona.

Aby włączyć Google Cloud Datastore, na pasku nawigacyjnym po lewej stronie znajdź i kliknij Datastore. Na nowej stronie kliknij Select Datastore Mode (Wybierz tryb Datastore).

Na potrzeby tego modułu możesz użyć dowolnej lokalizacji bazy danych. Kliknij Utwórz bazę danych, aby włączyć Google Cloud Datastore. Może to potrwać kilka minut.

Google Cloud Vision

Google Cloud Vision API to zaawansowana usługa uczenia maszynowego, która korzysta z wytrenowanych modeli do wyodrębniania informacji z obrazów.

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

Włączanie interfejsów Gmail API, Google Sheets API i Google Cloud Vision API

Ponownie otwórz pasek nawigacyjny po lewej stronie i kliknij Interfejsy API i usługi. Kliknij Biblioteka. W polu Wyszukaj interfejsy API i usługi wpisz Gmail. W wynikach wyszukiwania wybierz Gmail API i kliknij Włącz.

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

Powtórz ten proces. Wyszukaj 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 daje Ci dostęp do zasobów Google Cloud Platform bezpośrednio z przeglądarki, dzięki czemu możesz nimi zarządzać bez używania komputera lokalnego.

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

U dołu ekranu pojawi się nowy panel:

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

Edytor kodu Cloud Shell otworzy się w nowym oknie.

Pobieranie kodu

Aby sklonować projekt, uruchom w Cloud Shell to polecenie:

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. Omówienie architektury

Ten moduł obejmuje:

Użytkownik konfiguruje powiadomienia push w Gmailu: za każdym razem, gdy w skrzynce odbiorczej pojawi się nowa wiadomość, Gmail wyśle powiadomienie do Cloud Pub/Sub.
Cloud Pub/Sub dostarcza powiadomienie o nowej wiadomości do Google Cloud Functions.
Gdy pojawi się powiadomienie o nowej wiadomości, instancja Cloud Functions łączy się z Gmailem i pobiera nową wiadomość.
Jeśli e-mail zawiera obraz jako załącznik, instancja Cloud Functions wywołuje Cloud Vision API, aby przeanalizować załącznik.
Instancja Cloud Functions aktualizuje wybrany Arkusz Google, podając, kto wysłał wiadomość i gdzie można pobrać załącznik.

4. Autoryzowanie dostępu do Gmaila

Zanim skonfigurujesz funkcję w Cloud Functions do 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.

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

Utwórz powiązany identyfikator klienta

Przejdź na kartę Dane logowania. Kliknij Utwórz dane logowania i wybierz Identyfikator klienta OAuth. Wybierz typ Aplikacja internetowa, nadaj mu nazwę (możesz ponownie użyć nazwy GCF + Gmail Codelab) i kliknij Utwórz. Pola Restrictions (Ograniczenia) pozostaw na razie puste.

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

Przeprowadź proces autoryzacji.

W przykładowym kodzie auth/index.js określa 2 funkcje Cloud Functions, auth_init i auth_callback, które współpracują ze sobą w procesie autoryzacji, używając utworzonego właśnie identyfikatora klienta i tajnego klucza klienta.

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

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

Tokeny dostępu to krótkotrwałe potwierdzenia tożsamości, które przyznają każdemu, kto je posiada, ograniczony dostęp do Twoich danych. auth_callback zapisuje je w Cloud Datastore.
Tokeny odświeżania służą do uzyskiwania nowych tokenów dostępu i mają znacznie dłuższy okres ważności.

Zazwyczaj są one szyfrowane 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.

Po edycji auth/env_vars.yaml uruchom w Cloud Shell to polecenie, aby wdrożyć 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 Cloud Functions może potrwać kilka minut. Jeśli pojawi się pytanie o uprawnienia, przyznaj Cloud SDK uprawnienia do instalowania poleceń w wersji beta.

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

Skopiuj adres URL na stronie. Wróć na stronę Cloud Functions i na liście funkcji Cloud Functions kliknij auth_init. Na karcie Ogólne kliknij Edytuj. Kliknij Zmienne środowiskowe, sieć, czasy oczekiwania i nie tylko i zastąp wartość GOOGLE_CALLBACK_URL adresem URL, który został przed chwilą skopiowany.

Aby zastosować zmiany, kliknij Wdróż. Powtórz ten proces i zaktualizuj też urządzenie auth_callback.

Na koniec otwórz menu nawigacyjne po lewej stronie i kliknij Interfejsy API i 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ę należy dodać:

us-central1-my-project.cloudfunctions.net

Aby potwierdzić, kliknij Dodaj domenę.

Wróć na stronę Dane logowania. Kliknij nazwę klienta OAuth i dodaj skopiowany adres URL jako Autoryzowany identyfikator URI przekierowania. Naciśnij Enter, aby potwierdzić.

Usuń z adresu URL część /auth_callback i dodaj pozostałą część jako autoryzowane źródło JavaScript. Jeśli na przykład Twój 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/

Naciśnij Enter, aby potwierdzić, a następnie kliknij Zapisz, aby zastosować zmiany.

5. Konfigurowanie powiadomień push w Gmailu

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

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

Aby utworzyć temat Pub/Sub, otwórz konsolę Google Cloud i w menu nawigacyjnym po lewej stronie kliknij Pub/Sub > Tematy. Kliknij Utwórz temat. Wpisz nazwę tematu, np. gmail-watch, i kliknij Utwórz. Musisz też przyznać Gmailowi uprawnienia do wysyłania wiadomości do tematu Pub/Sub: kliknij menu kontekstowe utworzonego tematu (3 kropki w pionie) i wybierz Uprawnienia; kliknij Dodaj członków, jako nowego członka podaj gmail-api-push@system.gserviceaccount.com i przyznaj mu rolę Pub/Sub > Wydawca Pub/Sub; na koniec kliknij Zapisz, aby zastosować zmiany.

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

Możesz teraz autoryzować i skonfigurować powiadomienia push w Gmailu. Poczekaj, aż nowe zmiany zostaną wprowadzone, a następnie wróć na stronę Cloud Functions, wybierz auth_init na liście funkcji w Cloud Functions i przejdź na kartę Wywoływanie. Kliknij adres URL, a nastąpi przekierowanie na stronę Zaloguj się przez Google:

Zaloguj się na konto Gmail, które należy do Ciebie. Każda nowa wiadomość, która pojawi się w skrzynce odbiorczej konta, spowoduje wysłanie powiadomienia push. Po zalogowaniu się zobaczysz stronę poniżej:

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

W tym samouczku używamy pakietu @google-cloud/express-oauth2-handlers, aby zautomatyzować proces autoryzacji. Więcej informacji znajdziesz w repozytorium 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 o nowych wiadomościach w Twojej skrzynce odbiorczej. pubsub/index.js określa funkcję Cloud Function watchGmailMessages, która po wdrożeniu jako subskrybent tematu będzie odczytywać nowe wiadomości, kategoryzować załączone obrazy i eksportować te kategorie do arkusza Google.

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

Pobieranie wiadomości

Powiadomienie push Gmaila zawiera adres e-mail, z którym jest powiązane, oraz identyfikator historii. W tym samouczku uprościmy sobie zadanie i po otrzymaniu powiadomienia push po prostu poprosimy interfejs Gmail API o najnowszą wiadomość. 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 w postaci obrazu, watchGmailMessages wywoła interfejs Cloud Vision API, aby dodać adnotacje do obrazu. W tym laboratorium dowiesz się, jak poprosić interfejs Cloud Vision API o sklasyfikowanie obrazu i zwrócenie kilku tagów obrazu. Na przykład w przypadku obrazu przedstawiającego niebieskie niebo interfejs Cloud Vision API może zwrócić tagi niebieski, niebo i przyroda.

watchGmailMessages korzysta z biblioteki Cloud Vision API dla Node.js do wywoływania interfejsu 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;
};

Aktualizowanie arkusza Google

watchGmailMessages eksportuje wyniki tej analizy do Arkusza Google. Zawiera imię i nazwisko nadawcy, nazwę załącznika i tagi załączników z obrazami (jeśli występują).

Najpierw utwórz arkusz Google. Otwórz Arkusze Google i kliknij Pusty szablon w sekcji Utwórz nowy arkusz kalkulacyjny. 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 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 Sheets API, aby dołączyć 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 wartości YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET i YOUR-GOOGLE-CALLBACK-URL własnymi wartościami. Te wartości znajdziesz w konsoli Google Cloud: w menu nawigacyjnym po lewej stronie otwórz Cloud Functions, na liście Cloud Functions wybierz auth_init i poszukaj sekcji Zmienne środowiskowe.

Wdrażanie kodu

Aby wdrożyć funkcję w Cloud Functions, uruchom to polecenie:

cd ~

cd gcf-gmail-codelab/pubsub

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

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

7. Wypróbuj

Gratulacje, wszystko gotowe! Wyślij do siebie e-maila z załączonym obrazem. Po kilku sekundach zobaczysz, że utworzony przez Ciebie arkusz Google został automatycznie zaktualizowany o podane przez Ciebie informacje.