Schritt-für-Schritt-Anleitungen

In dieser Reihe von Schritt-für-Schritt-Anleitungen werden alle Komponenten eines funktionierenden Classroom-Add-ons veranschaulicht. In jedem Schritt werden bestimmte Konzepte behandelt und in einer einzigen Webanwendung implementiert. Das Ziel ist es, Ihnen bei der Einrichtung, Konfiguration und Einführung eines funktionalen Add-ons zu helfen.

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

In dieser Anleitung werden folgende Themen behandelt:

• Erstellen Sie mit Google Cloud eine Seite, die in einem iFrame in Classroom angezeigt werden soll.
• Fügen Sie die Einmalanmeldung (SSO) von Google hinzu und ermöglichen Sie Nutzern die Anmeldung.
• Führen Sie API-Aufrufe aus, um das Add-on an eine Aufgabe anzuhängen.
• Gehen Sie auf die wichtigsten Anforderungen für das Einreichen von Add-ons und die erforderlichen Funktionen ein.

In diesem Leitfaden wird davon ausgegangen, dass Sie mit der Programmierung und grundlegenden Konzepten der Webentwicklung vertraut sind. Wir empfehlen Ihnen dringend, den Leitfaden zur Projektkonfiguration zu lesen, bevor Sie mit den Schritt-für-Schritt-Anleitungen beginnen. Diese Seite enthält wichtige Konfigurationsdetails, die in den Schritt-für-Schritt-Anleitungen nicht vollständig behandelt werden.

Beispielimplementierungen

Vollständige Referenzbeispiele sind in JavaScript, Python und Java verfügbar. Diese Implementierungen sind die Quellen des Beispielcodes, die auf den nachfolgenden Seiten zu finden sind.

Downloadverzeichnis

Vollständige Archive unserer Beispiele können über die folgenden Links heruntergeladen werden.

• Python-Archiv
• Node.js-Archiv
• Java-Archiv

Voraussetzungen

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

HTTPS-Zertifikat

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

localhost kann mit einem SSL-Zertifikat verwendet werden. Verwenden Sie mkcert, wenn Sie ein Zertifikat für die lokale Entwicklung erstellen müssen.

Google Cloud-Projekt

Sie müssen ein Google Cloud-Projekt für diese Beispiele konfigurieren. In der Anleitung zum Erstellen von Google Cloud-Projekten finden Sie einen Überblick über die erforderlichen Schritte. Im Abschnitt Google Cloud-Projekt einrichten der ersten Schritt-für-Schritt-Anleitung werden auch die spezifischen Konfigurationsaktionen beschrieben, die ausgeführt werden müssen.

Wenn Sie fertig sind, laden Sie Ihre OAuth 2.0-Client-ID als JSON-Datei herunter. Sie müssen diese Datei mit den Anmeldedaten dem entpackten Beispielverzeichnis hinzufügen. Informationen zu den einzelnen Speicherorten finden Sie unter Informationen zu den Dateien.

OAuth-Anmeldedaten

Wichtiger Hinweis :Ihre Webanwendung muss OAuth 2.0-Anmeldedaten verwenden, die in Google Cloud verwaltet werden.

So erstellen Sie neue OAuth-Anmeldedaten:

• Rufen Sie die Seite Google Cloud-Anmeldedaten auf. Prüfen Sie, ob Sie oben auf dem Bildschirm das richtige Projekt ausgewählt haben.
• Klicken Sie auf ANMELDEDATEN ERSTELLEN und wählen Sie im Drop-down-Menü die Option OAuth-Client-ID aus.
• Gehen Sie auf der nächsten Seite so vor:
  • 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. Beispiel: https://my.domain.com/auth-callback oder https://localhost:5000/callback. Sie erstellen und verarbeiten diese Route später in dieser Schritt-für-Schritt-Anleitung. Sie können solche Routen jederzeit bearbeiten oder weitere hinzufügen.
  • Klicke auf ERSTELLEN.
• Es wird ein Dialogfeld mit Ihren neu erstellten Anmeldedaten angezeigt. Wählen Sie die Option JSON HERUNTERLADEN aus. Kopieren Sie die heruntergeladene Datei .json in Ihr Serververzeichnis.

Sprachspezifische Voraussetzungen

In der README-Datei in jedem Archiv finden Sie eine aktuelle Liste der Voraussetzungen.

Python

In unserem Python-Beispiel wird das gcloud-Framework verwendet. Den vollständigen Quellcode können Sie über den Link oben herunterladen.

Installieren Sie gegebenenfalls 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 den heruntergeladenen Beispielen befindet sich in jedem Schritt-für-Schritt-Unterverzeichnis ein requirements.txt. Mit pip können Sie die erforderlichen Bibliotheken schnell installieren. Mit den folgenden Befehlen installieren Sie die erforderlichen Bibliotheken für die erste Schritt-für-Schritt-Anleitung.

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

Node.js

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

Für dieses Beispiel ist Node.js v16.13 oder höher erforderlich.

Installieren Sie die erforderlichen Knotenmodule mit npm.

npm install

Java

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

Installieren Sie Java 11+, wenn diese 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 ermöglicht, ohne dass Sie Maven selbst installieren müssen.

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

java --version
./mvnw --version

Auf Windows:

java -version
mvnw.cmd --version

Dateien verstehen

In den folgenden Abschnitten wird das Layout der Beispielverzeichnisse beschrieben.

Verzeichnisnamen

Jedes Archiv enthält mehrere Verzeichnisse, deren Namen mit einer Zahl beginnen, z. B. /01-basic-app/. Die Nummern entsprechen bestimmten Schritt-für-Schritt-Anleitungen. Jedes Verzeichnis enthält eine voll funktionsfähige Webanwendung, in der die in einer bestimmten Schritt-für-Schritt-Anleitung beschriebenen Funktionen implementiert sind. Beispielsweise enthält das Verzeichnis /01-basic-app/ die endgültige Implementierung der Schritt-für-Schritt-Anleitung Add-on erstellen.

Verzeichnisinhalt

Der Inhalt des Verzeichnisses unterscheidet sich je nach Implementierungssprache:

Python

• Der Verzeichnisstamm enthält die folgenden Dateien:

  • main.py ist der Einstiegspunkt der Python-Anwendung. Geben Sie die Serverkonfiguration an, die Sie in dieser Datei 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 ist die von Google Cloud heruntergeladene Clientschlüsseldatei. Beachten Sie, dass diese Datei nicht im Beispielarchiv enthalten ist. Sie sollten die heruntergeladene Datei mit den Anmeldedaten umbenennen und in die einzelnen Verzeichnisstammverzeichnisse kopieren.

    Wichtig :Sie müssen die Clientschlüsseldatei aus Ihrem Google Cloud-Projekt angeben, bevor Sie die Beispiele ausführen können.

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

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

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

• Das Verzeichnis /static/ mit Bildern, CSS und ergänzenden 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 Prometheus-Server und lädt die in config.py festgelegten Konfigurationsoptionen.

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

Node.js

Jeder Schritt der Schritt-für-Schritt-Anleitung befindet sich in einem eigenen Unterordner <step>. Jeder Schritt umfasst Folgendes:

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

Java

Das Projektverzeichnis umfasst Folgendes:

• Das Verzeichnis src.main enthält den Quellcode und die Konfiguration für die erfolgreiche Ausführung der Anwendung. 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 das Ausführen 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. Außerdem enthält es die Datei application.properties, die den Port zum Ausführen des Servers, den Pfad zur Schlüsselspeicherdatei und den Pfad zum Verzeichnis templates angibt. Dieses Beispiel enthält die Schlüsselspeicherdatei im Verzeichnis resources. Sie können ihn an einem beliebigen Speicherort speichern, müssen aber in der Datei application.properties den entsprechenden Pfad angeben.
  • pom.xml enthält die Informationen, die zum Erstellen des Projekts und zum Definieren der erforderlichen Abhängigkeiten erforderlich sind.
  • .gitignore enthält Dateinamen, die nicht in Git hochgeladen werden sollen. Achten Sie darauf, den Pfad zu Ihrem Schlüsselspeicher in dieser .gitignore hinzuzufügen. Im angegebenen Beispiel ist dies secrets/*.p12 (der Zweck des Schlüsselspeichers wird im folgenden Abschnitt erläutert). Für Schritt-für-Schritt-Anleitung 2 und darüber hinaus sollten Sie auch den Pfad zu Ihrer client_secret.json-Datei angeben, damit Ihre Secrets nicht in einem Remote-Repository enthalten sind. Bei Schritt-für-Schritt-Anleitung 3 und höher sollten Sie den Pfad zur H2-Datenbankdatei und zum Dateispeicher Factory hinzufügen. Weitere Informationen zur Einrichtung dieser Datenspeicher finden Sie in der dritten Schritt-für-Schritt-Anleitung zum Umgang mit wiederkehrenden Besuchen.
  • mvnw und mvnw.cmd sind die ausführbaren Maven-Wrapper-Dateien für Unix bzw. Windows. Wenn Sie beispielsweise ./mvnw --version unter Unix 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

Wichtig :Ihre Webanwendung kann in Google Classroom nur über HTTPS geöffnet werden. Weitere Informationen finden Sie oben im Abschnitt HTTPS-Zertifikat.

Du musst deinen Server starten, um ihn zu testen. Folgen Sie der Anleitung unten, um den Beispielserver in Ihrer gewünschten Sprache auszuführen:

Python

OAuth-Anmeldedaten

Erstellen Sie Ihre OAuth-Anmeldedaten und laden Sie sie wie oben beschrieben herunter. Platzieren Sie die Datei .json im Stammverzeichnis neben der Datei zum Serverstart 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. localhost nicht gesichert. Diese Methode eignet sich nur für direkte Tests in einem Browserfenster. Ungesicherte Domains können nicht in den 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. localhost sichern. 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 Dies eignet sich für eine produktionsbereite Server- oder Cloud-Bereitstellung. Wir empfehlen, für diese Startoption die Umgebungsvariable PORT 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

Warnung: Bevor Sie den Server starten, müssen Sie ein Google Cloud-Projekt einrichten, um auf die Classroom API und die erforderlichen Anmeldedaten zugreifen zu können.

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

python main.py

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

Node.js

Server konfigurieren

Damit Sie den Server über HTTPS ausführen können, müssen Sie ein Selbstzertifikat erstellen, mit dem die Anwendung über HTTPS ausgeführt wird. Diese Anmeldedaten sollten als sslcert/cert.pem und sslcert/key.pem im Stammverzeichnis des Repositorys gespeichert werden. Möglicherweise müssen Sie diese Schlüssel dem Schlüsselbund Ihres Betriebssystems hinzufügen, damit Ihr Browser sie akzeptiert.

Achten Sie darauf, dass sich *.pem in Ihrer .gitignore-Datei befindet, da Sie die Datei nicht per Commit an Git übergeben möchten.

Server starten

Warnung :Bevor Sie den Server starten, müssen Sie ein Google Cloud-Projekt einrichten, um auf die Classroom API und die erforderlichen Anmeldedaten zugreifen zu können.

Sie können die Anwendung mit dem folgenden Befehl ausführen und dabei step01 durch den richtigen 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:3000 gestartet.

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

Java

Server konfigurieren

Damit Sie den Server über HTTPS ausführen können, müssen Sie ein Selbstzertifikat erstellen, mit dem die Anwendung über HTTPS ausgeführt wird.

Sie sollten mkcert für die lokale Entwicklung verwenden. Nach der Installation von mkcert generieren die folgenden Befehle ein lokal gespeichertes Zertifikat zur Ausführung über HTTPS.

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

Dieses Beispiel enthält die Schlüsselspeicherdatei im Ressourcenverzeichnis. Sie können sie an einem beliebigen Ort speichern. Achten Sie aber darauf, die Datei application.properties entsprechend mit dem Pfad zu aktualisieren. Der Domainname ist die Domain, in der Sie das Projekt ausführen (z. B. localhost).

Achten Sie darauf, dass sich *.p12 in Ihrer .gitignore-Datei befindet, da Sie die Datei nicht per Commit an Git übergeben möchten.

Server starten

Warnung :Bevor Sie den Server starten, müssen Sie ein Google Cloud-Projekt einrichten, um auf die Classroom API und die erforderlichen Anmeldedaten zugreifen zu können.

Starten Sie den Server, indem Sie die Methode main in der Datei Application.java ausführen. In IntelliJ können Sie beispielsweise entweder mit der rechten Maustaste im Verzeichnis src/main/java/com/addons/spring auf Application.java > Run 'Application' klicken oder die Datei Application.java öffnen und auf den grünen Pfeil links neben der Methodensignatur main(String[] args) 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 am Port gestartet, den Sie in application.properties angegeben haben.