In dieser Reihe von Schritt-für-Schritt-Anleitungen werden alle Bestandteile eines funktionierenden Classroom-Add-ons veranschaulicht. Jede Schritt-für-Schritt-Anleitung behandelt bestimmte Konzepte und implementiert sie in einer einzelnen Webanwendung. Ziel ist es, Sie beim Einrichten, Konfigurieren und Starten eines funktionalen Add-ons zu unterstützen.
Das Add-on muss mit einem Google Cloud-Projekt interagieren. Wenn Sie mit Google Cloud nicht vertraut sind, empfehlen wir Ihnen, die Startleitfäden zu lesen. In der Google Cloud Console verwalten Sie Anmeldedaten, den API-Zugriff und das Google Workspace Marketplace SDK. Weitere Informationen zum Marketplace SDK finden Sie auf der Seite mit der Anleitung zu Google Workspace Marketplace-Einträgen.
In dieser Anleitung werden folgende Themen behandelt:
- Mit Google Cloud eine Seite erstellen, die in einem iFrame in Classroom angezeigt wird.
- Fügen Sie die Einmalanmeldung (SSO) von Google hinzu und erlauben Sie Nutzern, sich anzumelden.
- Führen Sie API-Aufrufe aus, um Ihr Add-on an eine Aufgabe anzuhängen.
- Erläutern Sie die Anforderungen für das Einreichen von Add-ons und die erforderlichen Funktionen.
In diesem Leitfaden wird davon ausgegangen, dass Sie mit der Programmierung und den 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
Ein vollständiges Referenzbeispiel finden Sie in Python. Teilweise Implementierungen sind auch in Java und Node.js verfügbar. Diese Implementierungen sind die Quellen des Beispielcodes, der auf den nachfolgenden Seiten zu finden ist.
Hier herunterladen
Die Beispiele für Python und Java sind in GitHub-Repositories verfügbar:
Das Node.js-Beispiel kann als ZIP-Datei heruntergeladen werden:
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, das 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 iFrame des Add-ons 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. Im Leitfaden zur Google Cloud-Projekterstellung finden Sie eine Übersicht über die erforderlichen Schritte. Im Abschnitt Google Cloud-Projekt einrichten in der ersten Schritt-für-Schritt-Anleitung werden auch die spezifischen erforderlichen Konfigurationsaktionen beschrieben.
Laden Sie anschließend Ihre OAuth 2.0-Client-ID als JSON-Datei herunter. Diese Datei muss dem entpackten Beispielverzeichnis hinzugefügt werden. Spezifische Speicherorte finden Sie unter Dateien interpretieren.
OAuth-Anmeldedaten
So erstellen Sie neue OAuth-Anmeldedaten:
- Rufen Sie die Seite Google Cloud-Anmeldedaten auf. Prüfen Sie, ob Sie oben im 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:
- Legen Sie Anwendungstyp auf Webanwendung fest.
- 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
oderhttps://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. - Klicken Sie auf Erstellen.
- Es wird ein Dialogfeld mit Ihren neu erstellten Anmeldedaten angezeigt. Wählen Sie die Option JSON HERUNTERLADEN aus. Kopieren Sie die heruntergeladene JSON-Datei in Ihr Serververzeichnis.
Sprachspezifische Voraussetzungen
Die aktuelle 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 bereitgestellten Links herunterladen.
Installieren Sie bei Bedarf Python 3.7+ und achten Sie darauf, dass pip
verfügbar ist.
python3 -m ensurepip --upgrade
Außerdem empfehlen wir Ihnen, eine neue virtuelle Python-Umgebung einzurichten und zu aktivieren.
python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate
In jedem Schritt-für-Schritt-Unterverzeichnis in den heruntergeladenen Beispielen gibt es einen requirements.txt
. Sie können die erforderlichen Bibliotheken schnell mit pip
installieren. Verwenden Sie die folgenden Befehle, um die erforderlichen Bibliotheken für die erste Schritt-für-Schritt-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 bereitgestellten Links 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. Sie können den vollständigen Quellcode über die bereitgestellten Links herunterladen.
Installieren Sie Java 11 oder höher, falls dies 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 für einen erfolgreichen Build sorgt, 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
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 Nummern beziehen sich auf die einzelnen Schritt-für-Schritt-Anleitungen.
Jedes Verzeichnis enthält eine voll funktionsfähige Webanwendung, die die in einer bestimmten Schritt-für-Schritt-Anleitung beschriebenen Funktionen implementiert. Das Verzeichnis /01-basic-app/
enthält beispielsweise die endgültige Implementierung für die Schritt-für-Schritt-Anleitung Add-on erstellen.
Verzeichnisinhalt
Der Verzeichnisinhalt unterscheidet sich je nach Implementierungssprache:
Python
Das Stammverzeichnis 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 aus, um den Server zu starten.requirements.txt
: die zum Ausführen der Webanwendung erforderlichen Python-Module. Sie können automatisch mitpip install -r requirements.txt
installiert werden.client_secret.json
: die von Google Cloud heruntergeladene Clientschlüsseldatei. Beachten Sie, dass dies nicht im Beispielarchiv enthalten ist. Sie sollten die heruntergeladene Datei mit den Anmeldedaten umbenennen und in jedes Verzeichnisstammverzeichnis 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 Verzeichnis
/templates/
mit Jinja-Vorlagen für verschiedene SeitenDas 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 Modulwebapp
. Dieser Initialisierer startet den Flask-Server und lädt die inconfig.py
festgelegten Konfigurationsoptionen.Zusätzliche Dateien, die für einen bestimmten Schritt der Anleitung erforderlich sind.
Node.js
Jeder Schritt der Schritt-für-Schritt-Anleitung befindet sich in einem eigenen <step>
-Unterordner. Jeder Schritt enthält Folgendes:
- Statische Dateien wie JavaScript, CSS und Bilder befinden sich im Ordner
./<step>/public
. - Express-Router befinden sich in den
./<step>/routes
-Ordnern. - HTML-Vorlagen befinden sich in den Ordnern „
./<step>/views
“. - Die Serveranwendung ist
./<step>/app.js
.
Java
Das Projektverzeichnis enthält 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 Verzeichnisjava.com.addons.spring
enthält die DateienApplication.java
undController.java
. Die DateiApplication.java
ist für die Ausführung des Anwendungsservers verantwortlich, während die DateiController.java
die Endpunktlogik verarbeitet. Das Verzeichnisresources
enthält das Verzeichnistemplates
mit HTML- und JavaScript-Dateien. Außerdem enthält sie die Dateiapplication.properties
, die den Port zum Ausführen des Servers, den Pfad zur Keystore-Datei und den Pfad zum Verzeichnistemplates
angibt. In diesem Beispiel ist die Schlüsselspeicherdatei im Verzeichnisresources
enthalten. Sie können ihn an einem beliebigen Ort speichern. Achten Sie aber darauf, die Dateiapplication.properties
mit dem entsprechenden Pfad zu aktualisieren.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 sollten. Achten Sie darauf, dass Sie den Pfad zu Ihrem Schlüsselspeicher in diesem.gitignore
hinzufügen. Im vorliegenden Beispiel ist diessecrets/*.p12
. Der Zweck des Schlüsselspeichers wird im folgenden Abschnitt erläutert. Für Schritt 2 und darüber hinaus sollten Sie auch den Pfad zur Dateiclient_secret.json
angeben, damit Ihre Secrets nicht in ein Remote-Repository aufgenommen werden. Für Schritt 3 und höher sollten Sie den Pfad zur H2-Datenbankdatei und zur Dateispeicherfabrik hinzufügen. Weitere Informationen zur Einrichtung dieser Datenspeicher finden Sie in der dritten Schritt-für-Schritt-Anleitung zum Umgang mit wiederholten Besuchen.mvnw
undmvnw.cmd
sind die ausführbaren Maven-Wrapper für Unix bzw. Windows. Wenn Sie beispielsweise./mvnw --version
unter Unix ausführen, wird neben anderen Informationen 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 der Sprache Ihrer Wahl auszuführen:
Python
OAuth-Anmeldedaten
Erstellen Sie Ihre OAuth-Anmeldedaten wie oben beschrieben und laden Sie sie herunter. Platzieren Sie die JSON-Datei im Stammverzeichnis neben der Datei für den Start des Servers Ihrer Anwendung.
Server konfigurieren
Sie haben mehrere Möglichkeiten, den Webserver auszuführen. Fügen Sie am Ende der Python-Datei eines der folgenden Elemente hinzu:
localhost
ungesichert. Diese Methode eignet sich nur für direkte Tests in einem Browserfenster. Ungesicherte 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)
localhost
sichern. Sie müssen ein Tupel von SSL-Schlüsseldateien für das Argumentssl_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)
Gunicorn-Server. Sie eignet sich für eine produktionsreife Server- oder Cloudbereitstellung. 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
Führen Sie Ihre Python-Anwendung aus, um den Server wie im vorherigen Schritt konfiguriert zu starten.
python main.py
Klicken Sie auf die angezeigte URL, um die Webanwendung in einem Browser aufzurufen und zu prüfen, ob sie korrekt ausgeführt wird.
Node.js
Server konfigurieren
Wenn Sie den Server über HTTPS ausführen möchten, 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 sie von Ihrem Browser akzeptiert werden.
Achten Sie darauf, dass sich *.pem
in der Datei .gitignore
befindet, da Sie die Datei nicht per Commit an Git übertragen möchten.
Server starten
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 ein
npm run step02
Dadurch wird der Webserver unter https://localhost:5000
gestartet.
Du kannst den Server mit Control + C
in deinem Terminal beenden.
Java
Server konfigurieren
Wenn Sie den Server über HTTPS ausführen möchten, müssen Sie ein Selbstzertifikat erstellen, mit dem die Anwendung über HTTPS ausgeführt wird.
Sie können mkcert für die lokale Entwicklung verwenden. Nach der Installation von mkcert
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>
In diesem Beispiel ist die Schlüsselspeicherdatei im Ressourcenverzeichnis enthalten. Sie können sie an einem beliebigen Ort speichern. Achten Sie aber darauf, die Datei application.properties
mit dem entsprechenden Pfad zu aktualisieren. Der Domainname ist die Domain, auf der Sie das Projekt ausführen (z. B. localhost
).
Achten Sie darauf, dass sich *.p12
in der Datei .gitignore
befindet, da Sie die Datei nicht per Commit an 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 im Verzeichnis src/main/java/com/addons/spring
mit der rechten Maustaste 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 an dem in application.properties
angegebenen Port gestartet.