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:
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.
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:
Na dole ekranu pojawi się nowy panel:
Kliknij przycisk Uruchom edytor kodu, aby uruchomić edytor kodu Cloud Shell:
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:
- 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.
- Cloud Pub/Sub dostarcza do Google Cloud Functions powiadomienie o nowej wiadomości.
- Po otrzymaniu powiadomienia o nowej wiadomości instancja Cloud Functions łączy się z Gmailem i pobiera nową wiadomość.
- Jeśli wiadomość zawiera obraz jako załącznik, instancja Cloud Functions wywołuje interfejs Cloud Vision API, aby przeanalizować załącznik.
- 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.
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:
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.
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.
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.
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ść.
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/
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:
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:
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.