Schritt-für-Schritt-Anleitungen

In dieser Reihe von Anleitungen werden alle Komponenten eines funktionierenden Classroom-Add-ons veranschaulicht. Jeder Schritt der Anleitung behandelt bestimmte Konzepte und implementiert sie in einer einzelnen Webanwendung. Ziel ist es, Sie beim Einrichten, Konfigurieren und Starten eines funktionierenden Add-ons zu unterstützen.

Ihr Add-on muss mit einem Google Cloud-Projekt interagieren. Wenn Sie mit Google Cloud nicht vertraut sind, empfehlen wir Ihnen, die Leitfäden für den Einstieg zu lesen. Sie verwalten Anmeldedaten, API-Zugriff und das Google Workspace Marketplace SDK in der Google Cloud Console. Weitere Informationen zum Marketplace SDK finden Sie auf der Seite Leitfaden für Einträge im Google Workspace Marketplace .

In dieser Anleitung werden folgende Themen behandelt:

  • Mit Google Cloud eine Seite erstellen, die in einem iFrame in Classroom angezeigt werden soll
  • Google-Einmalanmeldung (SSO) hinzufügen und Nutzern die Anmeldung ermöglichen
  • API-Aufrufe senden, um Ihr Add-on an eine Aufgabe anzuhängen
  • Die wichtigsten Anforderungen für die Add-on-Einreichung und die erforderlichen Funktionen berücksichtigen

In dieser Anleitung wird davon ausgegangen, dass Sie mit der Programmierung und den grundlegenden Konzepten der Webentwicklung vertraut sind. Wir empfehlen dringend, vor Beginn der Anleitungen den Leitfaden zur Projektkonfiguration zu lesen. Diese Seite enthält wichtige Konfigurationsdetails, die in den Anleitungen nicht vollständig behandelt werden.

Beispielimplementierungen

Ein vollständiges Referenzbeispiel ist in Python verfügbar. Teilweise Implementierungen sind auch in Java und Node.js verfügbar. Diese Implementierungen sind die Quellen des Beispielcodes auf den folgenden Seiten.

Download

Die Python- und Java-Beispiele sind in GitHub-Repositories verfügbar:

Das Node.js-Beispiel kann als ZIP-Datei heruntergeladen werden:

Vorbereitung

Lesen Sie die folgenden Abschnitte, um ein neues Add-on-Projekt vorzubereiten.

HTTPS-Zertifikat

Sie können Ihre App zwar in jeder Entwicklungsumgebung hosten, Ihr Classroom-Add-on ist aber nur über https:// verfügbar. Daher benötigen Sie einen Server mit SSL-Verschlüsselung, um Ihre App bereitzustellen oder sie im Add-on-iFrame zu testen.

Sie können localhost mit einem SSL-Zertifikat verwenden. Wenn Sie ein Zertifikat für die lokale Entwicklung erstellen müssen, sollten Sie mkcert verwenden.

Google Cloud-Projekt

Sie müssen ein Google Cloud-Projekt für die Verwendung mit diesen Beispielen konfigurieren. Eine Übersicht über die erforderlichen Schritte für den Einstieg finden Sie im Leitfaden zum Erstellen eines Google Cloud-Projekts. Im Abschnitt Google Cloud-Projekt einrichten in der ersten Anleitung werden auch die spezifischen Konfigurations aktionen beschrieben.

Laden Sie nach Abschluss die OAuth 2.0-Client-ID als JSON-Datei herunter. Sie müssen diese Anmeldedatendatei dem entzippten Beispielverzeichnis hinzufügen. Spezifische Speicherorte finden Sie unter Informationen zu den Dateien.

OAuth-Anmeldedaten

So erstellen Sie neue OAuth-Anmeldedaten:

  • Rufen Sie die Google Cloud-Seite Anmeldedaten auf. Achten Sie darauf, dass oben auf dem Bildschirm das richtige Projekt ausgewählt ist.
  • Klicken Sie auf ANMELDEDATEN ERSTELLEN und wählen Sie im Drop-down-Menü OAuth-Client-ID aus.
  • Auf der nächsten Seite:
    • Setzen Sie den Anwendungstyp auf Webanwendung.
    • Klicken Sie unter Autorisierte Weiterleitungs-URIs auf URI HINZUFÜGEN. Fügen Sie den vollständigen Pfad für eine Callback-Route für Ihre Anwendung hinzu. Beispiele: https://my.domain.com/auth-callback oder https://localhost:5000/callback. Sie erstellen und verarbeiten diese Route später in dieser Anleitung. Sie können solche Routen jederzeit bearbeiten oder weitere hinzufügen.
    • Klicken Sie auf ERSTELLEN.
  • Anschließend wird ein Dialogfeld mit den neu erstellten Anmeldedaten angezeigt. Wählen Sie die Option JSON HERUNTERLADEN aus. Kopieren Sie die heruntergeladene JSON-Datei in Ihr Serververzeichnis.

Sprachspezifische Voraussetzungen

Die aktuellste Liste der Voraussetzungen finden Sie in der README-Datei in jedem Repository.

Python

In unserem Python-Beispiel wird das Flask-Framework verwendet. Sie können den vollständigen Quellcode über die angegebenen Links herunterladen.

Installieren Sie bei Bedarf Python 3.7 oder höher und prüfen Sie, ob pip verfügbar ist.

python3 -m ensurepip --upgrade

Wir empfehlen außerdem, eine neue virtuelle Python-Umgebung einzurichten und zu aktivieren.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

In jedem Unterverzeichnis der Anleitung in den heruntergeladenen Beispielen befindet sich eine requirements.txt-Datei. Sie können die erforderlichen Bibliotheken schnell mit pip installieren. Verwenden Sie die folgenden Befehle, um die erforderlichen Bibliotheken für die erste Anleitung zu installieren.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

In unserem Node.js-Beispiel wird das Express-Framework verwendet. Sie können den vollständigen Quellcode über die angegebenen Links herunterladen.

Für dieses Beispiel ist Node.js Version 16.13 oder höher erforderlich.

Installieren Sie die erforderlichen Node-Module mit npm.

npm install

Java

In unserem Java-Beispiel wird das Spring Boot-Framework verwendet. Sie können den vollständigen Quellcode über die angegebenen Links herunterladen.

Installieren Sie Java 11 oder höher, falls es noch nicht auf Ihrem Computer installiert ist.

Spring Boot-Anwendungen können Gradle oder Maven verwenden, um Builds zu verarbeiten und Abhängigkeiten zu verwalten. Dieses Beispiel enthält den Maven-Wrapper, der einen erfolgreichen Build gewährleistet, ohne dass Sie Maven selbst installieren müssen.

Führen Sie in dem Verzeichnis, in dem Sie das Projekt heruntergeladen oder geklont haben, die folgenden Befehle aus, um sicherzustellen, dass Sie die Voraussetzungen für die Ausführung des Projekts erfüllen.

java --version
./mvnw --version

Unter Windows:

java -version
mvnw.cmd --version

Informationen zu den Dateien

In den folgenden Abschnitten wird das Layout der Beispielverzeichnisse beschrieben.

Verzeichnisnamen

Jedes Repository enthält mehrere Verzeichnisse, deren Namen mit einer Zahl beginnen, z. B. /01-basic-app/. Die Zahlen entsprechen bestimmten Schritten der Anleitung. Jedes Verzeichnis enthält eine voll funktionsfähige Webanwendung, die die in einer bestimmten Anleitung beschriebenen Funktionen implementiert. Das /01-basic-app/ Verzeichnis enthält beispielsweise die endgültige Implementierung für die Anleitung Add-on erstellen.

Verzeichnisinhalt

Der Verzeichnisinhalt variiert je nach Implementierungssprache:

Python

  • Das Stammverzeichnis enthält die folgenden Dateien:

    • main.py – der Einstiegspunkt der Python-Anwendung. Geben Sie in dieser Datei die Serverkonfiguration an, die Sie verwenden möchten, und führen Sie sie dann aus, um den Server zu starten.
    • requirements.txt – die Python-Module, die zum Ausführen der Webanwendung erforderlich sind. Diese können automatisch mit pip install -r requirements.txt installiert werden.

    • client_secret.json – die Clientschlüsseldatei, die von Google Cloud heruntergeladen wurde. Diese Datei ist nicht im Beispielarchiv enthalten. Sie sollten Ihre heruntergeladene Anmeldedatendatei umbenennen und in jedes Stammverzeichnis kopieren.

  • config.py – Konfigurationsoptionen für den Flask-Server.

  • Das Verzeichnis webapp enthält den Inhalt für die Webanwendung. Folgende Angaben sind enthalten:

  • Das /templates/ Verzeichnis mit Jinja Vorlagen für verschiedene Seiten.

  • Das Verzeichnis /static/ mit Bildern, CSS und zusätzlichen JavaScript-Dateien.

  • routes.py – die Handler-Methoden für die Routen der Webanwendung.

  • __init__.py – der Initialisierer für das Modul webapp. Dieser Initialisierer startet den Flask-Server und lädt die in config.py festgelegten Konfigurationsoptionen.

  • Zusätzliche Dateien, die für einen bestimmten Schritt der Anleitung erforderlich sind.

Node.js

Jeder Schritt der Anleitung befindet sich in einem eigenen <step> Unterordner. Jeder Schritt enthält Folgendes:

  • Statische Dateien wie JavaScript, CSS und Bilder befinden sich im ./<step>/public Ordner.
  • Express-Router finden Sie in den ./<step>/routes Ordnern.
  • HTML-Vorlagen finden Sie in den ./<step>/views Ordnern.
  • Die Serveranwendung ist ./<step>/app.js.

Java

Das Projektverzeichnis enthält Folgendes:

  • Das Verzeichnis src.main enthält den Quellcode und die Konfiguration, die für die erfolgreiche Ausführung der Anwendung erforderlich sind. Dieses Verzeichnis enthält Folgendes: + Das Verzeichnis java.com.addons.spring enthält die Dateien Application.java und Controller.java. Die Datei Application.java ist für die Ausführung des Anwendungsservers verantwortlich, während die Datei Controller.java die Endpunktlogik verarbeitet. + Das Verzeichnis resources enthält das Verzeichnis templates mit HTML- und JavaScript-Dateien. Es enthält auch die application.properties Datei, in der der Port für die Ausführung des Servers, der Pfad zur Keystore-Datei und der Pfad zum templates Verzeichnis angegeben sind. Dieses Beispiel enthält die Keystore-Datei im resources Verzeichnis. Sie können sie an einem beliebigen Ort speichern, müssen aber die Datei application.properties entsprechend mit dem Pfad aktualisieren.
    • pom.xml enthält die Informationen, die zum Erstellen des Projekts und zum Definieren der erforderlichen Abhängigkeiten benötigt werden.
    • .gitignore enthält Dateinamen, die nicht in Git hochgeladen werden sollen. Fügen Sie in dieser Datei .gitignore den Pfad zu Ihrem Keystore hinzu. Im angegebenen Beispiel ist das secrets/*.p12. Der Zweck des Keystores wird im folgenden Abschnitt erläutert. Für Anleitung 2 und höher sollten Sie auch den Pfad zu Ihrer Datei client_secret.json angeben, damit Ihre Secrets nicht in einem Remote-Repository enthalten sind. Für Anleitung 3 und höher sollten Sie den Pfad zur H2-Datenbankdatei und zur Datenspeicher-Factory für Dateien hinzufügen. Weitere Informationen zum Einrichten dieser Datenspeicher finden Sie in der dritten Anleitung zur Verarbeitung wiederholter Besuche.
    • mvnw und mvnw.cmd sind die ausführbaren Maven-Wrapper für Unix bzw. Windows. Wenn Sie beispielsweise unter Unix ./mvnw --version ausführen, wird unter anderem die Apache Maven-Version ausgegeben.
    • Das Verzeichnis .mvn enthält die Konfiguration für den Maven-Wrapper.

Beispielserver ausführen

Sie müssen Ihren Server starten, um ihn zu testen. Folgen Sie dieser Anleitung, um den Beispielserver in Ihrer bevorzugten Sprache auszuführen:

Python

OAuth-Anmeldedaten

Erstellen und laden Sie Ihre OAuth-Anmeldedaten wie zuvor beschrieben herunter. Platzieren Sie die JSON-Datei im Stammverzeichnis neben der Serverstartdatei Ihrer Anwendung.

Server konfigurieren

Sie haben mehrere Möglichkeiten, den Webserver auszuführen. Fügen Sie am Ende Ihrer Python-Datei eine der folgenden Optionen hinzu:

  1. Nicht gesichertes localhost. Diese Option eignet sich nur für direkte Tests in einem Browserfenster. Nicht gesicherte Domains können nicht im iFrame des Classroom-Add-ons geladen werden.

    if __name__ == "__main__":
  # Disable OAuthlib's HTTPs verification.
  os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"

  # Run the web app at http://localhost:5000.
  app.run(debug=True)

  2. Gesichertes localhost. Sie müssen ein Tupel von SSL-Schlüsseldateien für das Argument ssl_context angeben.

    if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

  3. Gunicorn-Server. Diese Option eignet sich für einen produktionsbereiten Server oder die Cloudbereitstellung. Wir empfehlen, eine Umgebungsvariable PORT für die Verwendung mit dieser Startoption festzulegen.

    if __name__ == "__main__":
  # Run the web app at https://<your domain>:<server_port>.
  # Defaults to https://<your domain>:8080.
  server_port = os.environ.get("PORT", "8080")
  app.run(debug=True, port=server_port, host="0.0.0.0")

Server starten

Führen Sie Ihre Python-Anwendung aus, um den Server wie im vorherigen Schritt konfiguriert zu starten.

python main.py

Klicken Sie auf die URL, die angezeigt wird, um Ihre Webanwendung in einem Browser aufzurufen und zu prüfen, ob sie ordnungsgemäß ausgeführt wird.

Node.js

Server konfigurieren

Um den Server über HTTPS auszuführen, müssen Sie ein selbst signiertes Zertifikat erstellen, mit dem die Anwendung über HTTPS ausgeführt wird. Diese Anmeldedaten sollten als sslcert/cert.pem und sslcert/key.pem im Stammordner des Repositorys gespeichert werden. Möglicherweise müssen Sie diese Schlüssel Ihrem Betriebssystem-Schlüsselbund hinzufügen, damit Ihr Browser sie akzeptiert.

Achten Sie darauf, dass *.pem in Ihrer Datei .gitignore enthalten ist, da Sie die Datei nicht in Git übertragen möchten.

Server starten

Sie können die Anwendung mit dem folgenden Befehl ausführen und dabei step01 durch den korrekten Schritt ersetzen, den Sie als Server ausführen möchten (z. B. step01 für 01-basic-app und step02 für 02-sign-in).

npm run step01

oder

npm run step02

Dadurch wird der Webserver unter https://localhost:5000 gestartet.

Sie können den Server mit Control + C im Terminal beenden.

Java

Server konfigurieren

Um den Server über HTTPS auszuführen, müssen Sie ein selbst signiertes Zertifikat erstellen, mit dem die Anwendung über HTTPS ausgeführt wird.

Verwenden Sie für die lokale Entwicklung mkcert. Nachdem Sie mkcert installiert haben, generieren die folgenden Befehle ein lokal gespeichertes Zertifikat, das über HTTPS ausgeführt wird.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Dieses Beispiel enthält die Keystore-Datei im Verzeichnis „resources“. Sie können sie an einem beliebigen Ort speichern, müssen aber die Datei application.properties entsprechend mit dem Pfad aktualisieren. Der Domainname ist die Domain, auf der Sie das Projekt ausführen (z. B. localhost).

Achten Sie darauf, dass *.p12 in Ihrer Datei .gitignore enthalten ist, da Sie die Datei nicht in Git übertragen möchten.

Server starten

Starten Sie den Server, indem Sie die Methode main in der Datei Application.java ausführen. In IntelliJ können Sie beispielsweise mit der rechten Maustaste auf Application.java > Run 'Application' im Verzeichnis src/main/java/com/addons/spring klicken oder die Datei Application.java öffnen und auf den grünen Pfeil links neben der main(String[] args) Methodensignatur klicken. Alternativ können Sie das Projekt in einem Terminalfenster ausführen:

./mvnw spring-boot:run

Unter Windows:

mvnw.cmd spring-boot:run

Dadurch wird der Server unter https://localhost:5000 oder an dem in application.properties angegebenen Port gestartet.