1. Einführung
Milliarden Unternehmen und Privatpersonen nutzen Gmail und andere G Suite-Dienste für die Kommunikation und Datenverarbeitung. Google bietet G Suite APIs, mit denen Sie programmatisch auf Informationen in diesen Diensten zugreifen können. Mit den APIs können Sie Ihren täglichen Workflow ganz einfach automatisieren. In diesem Lab erstellen Sie eine leistungsstarke Gmail-Erweiterung, die E‑Mails in eingehenden Nachrichten automatisch kategorisiert und diese Kategorien in einer Google-Tabelle speichert. Für diese Erweiterung werden die RESTful APIs der G Suite, Google Cloud Functions und andere Google Cloud Platform-Dienste verwendet.
Umfang
In diesem Lab erstellen und stellen Sie einige Cloud Functions bereit, die mit G Suite APIs und anderen Google Cloud Platform-Diensten verbunden sind. Diese Funktionen haben folgende Aufgaben:
- Sicheren Zugriff auf Ihre Gmail- und Google Sheets-Daten autorisieren
- Bilder aus Anhängen eingehender E‑Mails extrahieren
- Diese Bilder mit der Cloud Vision API kategorisieren
- Diese Kategorien, die Adresse des Absenders und den Namen des Anhangs in eine Google-Tabelle schreiben
Lerninhalte
- Grundlagen der RESTful APIs der G Suite
- Grundlagen von Google Cloud Functions und anderen Google Cloud Platform-Diensten
- Programmatischer Zugriff auf Gmail mit Google Cloud Functions
Voraussetzungen
- Ein Google-Konto mit Zugriff auf Gmail und Google Sheets. Wenn Sie kein Konto haben, können Sie hier eines erstellen.
- Grundlegende Kenntnisse in JavaScript/Node.js.
2. Das Wichtigste zuerst
APIs aktivieren
In diesem Lab verwenden Sie die folgenden Google-Produkte und ‑Dienste:
- 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 ist die serverlose Functions-as-a-Service-Plattform von Google, mit der Sie einzelne Code-Snippets („Funktionen“) auf einfache und skalierbare Weise ausführen können.
Wenn Sie Google Cloud Functions aktivieren möchten, klicken Sie links oben auf das Dreistrich-Menü, um die linke Navigationsleiste zu öffnen:
Suchen Sie im Navigationsmenü nach Cloud Functions und klicken Sie darauf. Klicken Sie auf API aktivieren , um Google Cloud Functions in Ihrem Projekt zu aktivieren.
Google Cloud Pub/Sub
Google Cloud Pub/Sub ist eine einfache und skalierbare Grundlage für Datenstreaming und Ereignisübermittlung. In diesem Lab dient es als Vermittler zwischen Gmail und Google Cloud Functions.
Wenn Sie Google Cloud Pub/Sub aktivieren möchten, öffnen Sie die linke Navigationsleiste, suchen Sie nach Pub/Sub und klicken Sie darauf. Klicken Sie auf API aktivieren , um Google Cloud Pub/Sub in Ihrem Projekt zu aktivieren.
Google Cloud Datastore
Google Cloud Datastore ist eine serverlose, skalierbare und verteilte Datenbank.
Wenn Sie Google Cloud Datastore aktivieren möchten, suchen Sie in der linken Navigationsleiste nach Datastore und klicken Sie darauf. Klicken Sie auf der neuen Seite auf Datastore-Modus auswählen.
Sie können für dieses Lab einen beliebigen Datenbankstandort verwenden. Klicken Sie auf Datenbank erstellen , um Google Cloud Datastore zu aktivieren. Dieser Vorgang kann einige Minuten dauern.
Google Cloud Vision
Die Google Cloud Vision API ist ein leistungsstarker Machine-Learning-Dienst, der vortrainierte Modelle verwendet, um Erkenntnisse aus Ihren Bildern zu gewinnen.
Informationen zum Aktivieren der Google Cloud Vision API finden Sie in der Anleitung unten.
Gmail API, Google Sheets API und Google Cloud Vision API aktivieren
Öffnen Sie noch einmal die linke Navigationsleiste und suchen Sie nach APIs &Dienste. Klicken Sie auf Bibliothek. Geben Sie im Feld Nach APIs und Diensten suchen die Zeichenfolge Gmail ein. Wählen Sie in den Suchergebnissen Gmail API aus und klicken Sie auf Aktivieren.
Kehren Sie zur Seite „API-Bibliothek“ zurück. Suchen Sie nach Google Sheets API und aktivieren Sie sie.
Wiederholen Sie den Vorgang. Suchen Sie nach Cloud Vision API und aktivieren Sie sie.
Google Cloud Shell öffnen
In diesem Lab verwenden Sie Google Cloud Shell für die meisten Vorgänge. Cloud Shell bietet Ihnen direkt über den Browser Befehlszeilenzugriff auf Ihre Google Cloud Platform-Ressourcen. So können Sie sie verwalten, ohne einen lokalen Computer zu verwenden.
Klicken Sie zum Öffnen von Google Cloud Shell auf die Schaltfläche Cloud Shell aktivieren in der oberen blauen horizontalen Leiste:
Unten auf dem Bildschirm wird ein neuer Bereich angezeigt:
Klicken Sie auf die Schaltfläche Code-Editor starten , um den Cloud Shell-Code-Editor zu starten:
Der Cloud Shell-Code-Editor wird in einem neuen Fenster geöffnet.
Code herunterladen
Führen Sie den folgenden Befehl in Cloud Shell aus, um das Projekt zu klonen:
git clone https://github.com/googlecodelabs/gcf-gmail-codelab.git cd gcf-gmail-codelab
Im Cloud Shell-Code-Editor sollte ein neuer Ordner namens gcf-gmail-codelab angezeigt werden.
3. Architekturübersicht
Im Folgenden wird der Workflow dieses Labs beschrieben:
- Der Nutzer richtet Gmail-Push-Benachrichtigungen ein: Jedes Mal, wenn eine neue Nachricht im Posteingang eingeht, sendet Gmail eine Benachrichtigung an Cloud Pub/Sub.
- Cloud Pub/Sub übermittelt die Benachrichtigung über die neue Nachricht an Google Cloud Functions.
- Nach Eingang der Benachrichtigung über die neue Nachricht stellt eine Cloud Functions-Instanz eine Verbindung zu Gmail her und ruft die neue Nachricht ab.
- Wenn die E‑Mail einen Bildanhang enthält, ruft die Cloud Functions-Instanz die Cloud Vision API auf, um den Anhang zu analysieren.
- Die Cloud Functions-Instanz aktualisiert eine Google-Tabelle Ihrer Wahl und gibt an, wer die Nachricht gesendet hat und wo der Anhang heruntergeladen werden kann.
4. Zugriff auf Gmail autorisieren
Bevor Sie eine Cloud Functions-Funktion einrichten, um Ihre E‑Mails automatisch zu lesen, müssen Sie den Zugriff auf Gmail autorisieren. Dazu müssen Sie einen OAuth-Client bei Google registrieren und eine zugehörige Client-ID erstellen.
OAuth-Client registrieren
Suchen Sie im linken Navigationsmenü der Google Cloud Console nach APIs &Dienste. Klicken Sie auf OAuth-Zustimmungsbildschirm.
Geben Sie im Feld Name der Anwendung einen Namen ein, z. B. GCF + Gmail Codelab. Lassen Sie die anderen Einstellungen unverändert, scrollen Sie auf der Seite nach unten und klicken Sie auf Speichern.
Zugehörige Client-ID erstellen
Wechseln Sie zum Tab Anmeldedaten. Klicken Sie auf Anmeldedaten erstellen und wählen Sie OAuth-Client-ID aus. Wählen Sie den Typ Webanwendung aus, geben Sie einen Namen ein (Sie können hier wieder GCF + Gmail Codelab verwenden) und klicken Sie auf Erstellen. Lassen Sie die Felder für Einschränkungen vorerst leer.
Notieren Sie sich die Client-ID und den Clientschlüssel, die im Pop-up-Fenster zurückgegeben werden. Sie können auf der Seite auf den Namen Ihres Clients klicken, um diese Werte noch einmal aufzurufen:
Autorisierungsprozess durchführen
Im Beispielcode gibt auth/index.js zwei Cloud Functions-Funktionen an, auth_init und auth_callback, die zusammenarbeiten, um den Autorisierungsprozess mithilfe der gerade erstellten Client-ID und des Clientschlüssels durchzuführen.
Wenn Sie den Code prüfen möchten, öffnen Sie auth/index.js im Cloud Shell-Code-Editor.
Der Autorisierungsprozess gibt zwei Arten von Tokens zurück: Zugriffstokens und Aktualisierungstokens.
- Zugriffstokens sind kurzlebige Identitätsnachweise, die jedem, der sie besitzt, eingeschränkten Zugriff auf Ihre Daten gewähren.
auth_callbackspeichert sie in Cloud Datastore. - Aktualisierungstokens werden verwendet, um neue Zugriffstokens abzurufen, und sind deutlich länger gültig.
In der Regel werden sie entweder verschlüsselt und/oder getrennt von Zugriffstokens gespeichert.
Bearbeiten Sie auth/env_vars.yaml im Cloud Shell-Code-Editor. Ersetzen Sie YOUR-GOOGLE-CLIENT-ID und YOUR-GOOGLE-CLIENT-SECRET durch eigene Werte. Weitere Informationen finden Sie im vorherigen Schritt. Lassen Sie die Werte von YOUR-GOOGLE-CLIENT-CALLBACK-URL und YOUR-PUBSUB-TOPIC vorerst unverändert.
Nachdem Sie auth/env_vars.yaml bearbeitet haben, führen Sie den folgenden Befehl in Cloud Shell aus, um die Cloud Functions-Funktionen bereitzustellen:
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
Die Bereitstellung der Cloud Functions-Funktionen kann einige Minuten dauern. Wenn Sie dazu aufgefordert werden, erteilen Sie dem Cloud SDK die Berechtigung, Betabefehle zu installieren.
Rufen Sie als Nächstes die Google Cloud Console auf und klicken Sie im linken Navigationsmenü auf Cloud Functions. Klicken Sie in der Liste der Cloud Functions-Funktionen auf auth_callback und wechseln Sie zum Tab Trigger.
Kopieren Sie die URL auf der Seite. Kehren Sie zur Seite „Cloud Functions“ zurück und klicken Sie in der Liste der Cloud Functions-Funktionen auf auth_init. Klicken Sie auf dem Tab Allgemein auf Bearbeiten. Klicken Sie auf Umgebungsvariablen, Netzwerk, Zeitlimits und mehr und ersetzen Sie den Wert von GOOGLE_CALLBACK_URL durch die gerade kopierte URL.
Klicken Sie auf Bereitstellen , um die Änderungen zu übernehmen. Wiederholen Sie den Vorgang und aktualisieren Sie auch auth_callback.
Öffnen Sie schließlich das linke Navigationsmenü und klicken Sie auf APIs & Dienste > Domainbestätigung. Klicken Sie auf Domain hinzufügen, um eine autorisierte Domain hinzuzufügen. Wenn die zuvor kopierte URL beispielsweise so aussieht:
https://us-central1-my-project.cloudfunctions.net/auth_callback
Fügen Sie Folgendes als autorisierte Domain hinzu:
us-central1-my-project.cloudfunctions.net
Klicken Sie zur Bestätigung auf Domain hinzufügen.
Kehren Sie zur Seite Anmeldedaten zurück. Klicken Sie auf den Namen Ihres OAuth-Clients und fügen Sie die kopierte URL als Autorisierter Weiterleitungs-URI hinzu. Drücken Sie die Eingabetaste , um zu bestätigen.
Entfernen Sie den Teil /auth_callback aus der URL und fügen Sie den Rest als Autorisierte JavaScript-Quelle hinzu. Wenn Ihre URL beispielsweise so aussieht:
https://us-central1-my-project.cloudfunctions.net/auth_callback
Fügen Sie Folgendes als Quelle hinzu:
https://us-central1-my-project.cloudfunctions.net/
Drücken Sie die Eingabetaste , um zu bestätigen, und klicken Sie auf Speichern , um die Änderungen zu übernehmen.
5. Gmail-Push-Benachrichtigungen einrichten
Wenn der Autorisierungsprozess erfolgreich ist, ruft auth_callback automatisch die Gmail API auf, um Push-Benachrichtigungen einzurichten.
Wenn Sie Gmail-Push-Benachrichtigungen erhalten möchten, müssen Sie ein Pub/Sub-Thema erstellen. Alle Abonnenten des Themas erhalten automatisch Benachrichtigungen über eingehende Nachrichten, sobald sie von Gmail eingehen.
Wenn Sie ein Pub/Sub-Thema erstellen möchten, rufen Sie die Google Cloud Console auf und klicken Sie im linken Navigationsmenü auf Pub/Sub > Themen. Klicken Sie auf Thema erstellen. Geben Sie den Namen des Themas ein, z. B. gmail-watch, und klicken Sie auf Erstellen. Außerdem müssen Sie Gmail die Berechtigung erteilen, Nachrichten an Ihr Pub/Sub-Thema zu senden: Klicken Sie auf das Kontextmenü des gerade erstellten Themas (drei vertikale Punkte) und wählen Sie Berechtigungen aus. Klicken Sie auf Mitglieder hinzufügen, geben Sie gmail-api-push@system.gserviceaccount.com als neues Mitglied an und weisen Sie ihm die Rolle Pub/Sub > Pub/Sub-Publisher zu. Klicken Sie abschließend auf Speichern, um die Änderungen zu übernehmen.
Aktualisieren Sie die Cloud Functions-Funktion auth_callback, um anzugeben, welches Pub/Sub-Thema verwendet werden soll. Klicken Sie im linken Navigationsmenü auf Cloud Functions und wählen Sie in der Liste der Cloud Functions-Funktionen auth_callback aus. Klicken Sie auf dem Tab Allgemein auf Bearbeiten. Klicken Sie auf Mehr und ersetzen Sie den Wert von PUBSUB_TOPIC durch den Namen des gerade erstellten Pub/Sub-Themas. Klicken Sie auf Speichern , um die Änderungen zu übernehmen.
Jetzt können Sie Gmail-Push-Benachrichtigungen autorisieren und einrichten. Warten Sie, bis die neuen Änderungen abgeschlossen sind, kehren Sie dann zur Seite Cloud Functions zurück, wählen Sie in der Liste der Cloud Functions-Funktionen auth_init aus und wechseln Sie zum Tab Trigger. Klicken Sie auf die URL. Sie werden zur Seite Über Google anmelden weitergeleitet:
Melden Sie sich mit einem Gmail-Konto an, das Ihnen gehört. Jede neue Nachricht, die im Posteingang des Kontos eingeht, löst eine Push-Benachrichtigung aus. Nach der Anmeldung wird die folgende Seite angezeigt:
Klicken Sie auf Zulassen , um den Zugriff zu autorisieren. auth_callback schließt den Autorisierungsprozess ab, speichert die Zugriffstokens und richtet Gmail-Push-Benachrichtigungen für Sie ein. Wenn dieser Vorgang abgeschlossen ist, sollte in Ihrem Browser die Meldung Successfully set up Gmail push notifications (Gmail-Push-Benachrichtigungen wurden eingerichtet) angezeigt werden.
In diesem Codelab wird das Paket @google-cloud/express-oauth2-handlers verwendet, um den Autorisierungsworkflow für Sie zu automatisieren. Weitere Informationen finden Sie im zugehörigen Repository auf GitHub.
6. Eingehende Nachrichten verarbeiten
Wie bereits erwähnt, erhalten alle Abonnenten des von Ihnen erstellten Pub/Sub-Themas Benachrichtigungen, wenn neue Nachrichten in Ihrem Posteingang eingehen. pubsub/index.js gibt eine Cloud Functions-Funktion an, watchGmailMessages, die nach der Bereitstellung als Abonnent des Themas die neuen Nachrichten liest, angehängte Bilder kategorisiert und diese Kategorien in eine Google-Tabelle exportiert.
Wenn Sie den Code prüfen möchten, öffnen Sie pubsub/index.js im Cloud Shell-Code-Editor.
Nachrichten abrufen
Eine Gmail-Push-Benachrichtigung enthält die E‑Mail-Adresse, mit der die Benachrichtigung verknüpft ist, und eine Verlaufs-ID. Aus Gründen der Einfachheit wird in diesem Codelab einfach die Gmail API nach der neuesten Nachricht gefragt, wenn eine Push-Benachrichtigung eingeht. Um ein besseres Ergebnis zu erzielen, sollten Sie stattdessen die Verlaufs-ID verwenden, um nach Nachrichten zu suchen.
// 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;
Bildanhänge analysieren
Wenn die Nachricht einen Bildanhang enthält, ruft watchGmailMessages die Cloud Vision API auf, um das Bild mit Anmerkungen zu versehen. In diesem Codelab fordern Sie die Cloud Vision API auf, das Bild zu klassifizieren und eine Reihe von Bild-Tags zurückzugeben. Wenn Sie beispielsweise ein Bild eines blauen Himmels bereitstellen, gibt die Cloud Vision API möglicherweise die Tags blau, Himmel und Natur zurück.
watchGmailMessages verwendet die Cloud Vision API-Bibliothek für Node.js, um die Cloud Vision API aufzurufen:
// 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;
};
Google-Tabelle aktualisieren
watchGmailMessages exportiert die Ergebnisse dieser Analyse in eine Google-Tabelle. Dazu gehören der Name des Absenders, der Name des Anhangs und Tags von Bildanhängen (falls vorhanden).
Erstellen Sie zuerst eine Google-Tabelle. Öffnen Sie Google Sheets und klicken Sie unter Neue Tabelle anlegen auf die Vorlage Leer. Kopieren Sie die ID Ihrer Tabelle. Wenn die Adresse in Ihrem Browser beispielsweise so aussieht:
https://docs.google.com/spreadsheets/d/abcdefghij01234567890/edit#gid=0
Die ID Ihrer Tabelle ist abcdefghij01234567890. Aktualisieren Sie im Cloud Shell-Code-Editor gcf-gmail-codelab/pubsub/env_vars.yaml und ersetzen Sie YOUR-GOOGLE-SHEET-ID durch Ihren eigenen Wert.
watchGmailMessages stellt eine Verbindung zur Google Sheets API her, um Informationen anzuhängen:
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)
]
}
});
};
Letzter Schritt
Öffnen Sie im Cloud Shell-Code-Editor gcf-gmail-codelab/pubsub/env_vars.yaml und ersetzen Sie YOUR-GOOGLE-CLIENT-ID, YOUR-GOOGLE-CLIENT-SECRET und YOUR-GOOGLE-CALLBACK-URL durch eigene Werte. Diese Werte finden Sie in der Google Cloud Console: Öffnen Sie im linken Navigationsmenü Cloud Functions , wählen Sie in der Liste der Cloud Functions-Funktionen auth_init aus und suchen Sie nach dem Abschnitt Umgebungsvariablen.
Code bereitstellen
Führen Sie den folgenden Befehl aus, um die Cloud Functions-Funktion bereitzustellen:
cd ~ cd gcf-gmail-codelab/pubsub gcloud functions deploy watchGmailMessages --runtime=nodejs8 --trigger-topic=gmail-watch --env-vars-file=env_vars.yaml
Wenn Sie Ihr Cloud Pub/Sub-Thema anders als gmail-watch benannt haben, ersetzen Sie gmail-watch im obigen Befehl durch den Namen Ihres Themas. Die Bereitstellung der Cloud Functions-Funktion kann einige Sekunden dauern.
7. Jetzt ausprobieren
Das war's schon! Senden Sie sich selbst eine E‑Mail mit einem Bildanhang. Nach einigen Sekunden wird die von Ihnen erstellte Google-Tabelle automatisch mit den von Ihnen angegebenen Informationen aktualisiert.