Google Classroom-Add-ons sind jetzt allgemein für Entwickler verfügbar. Weitere Informationen finden Sie in der Dokumentation zu Add-ons.

Diese Seite wurde von der Cloud Translation API übersetzt.

Schritt-für-Schritt-Anleitungen

In dieser Reihe von Schritt-für-Schritt-Anleitungen werden alle Bestandteile eines funktionierenden Classroom-Add-ons veranschaulicht. In jedem Schritt der Schritt-für-Schritt-Anleitung werden bestimmte Konzepte behandelt und in einer einzelnen Webanwendung implementiert. Ziel ist es, Ihnen beim Einrichten, Konfigurieren und Starten eines funktionsfähigen Add-ons zu helfen.

Das Add-on muss mit einem Google Cloud-Projekt interagieren. Wenn Sie mit Google Cloud nicht vertraut sind, empfehlen wir Ihnen, die Anleitungen 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 Hilfeseite Google Workspace Marketplace-Eintrag.

In dieser Anleitung werden folgende Themen behandelt:

Mit Google Cloud eine Seite erstellen, die in einem IFrame in Classroom angezeigt werden soll
Fügen Sie die Einmalanmeldung (SSO) von Google hinzu und erlauben Sie Nutzern die Anmeldung.
Führen Sie API-Aufrufe aus, um Ihr Add-on an eine Aufgabe anzuhängen.
Beachten Sie die wichtigsten Anforderungen an die Einreichung von Add-ons und die erforderlichen Funktionen.

In diesem Leitfaden wird davon ausgegangen, dass Sie mit Programmieren 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 ist in Python verfügbar. Teilweise Implementierungen sind auch in Java und Node.js verfügbar. Diese Implementierungen sind die Quellen für den Beispielcode auf den folgenden Seiten.

Hier herunterladen

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

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

Node.js-Archiv

Vorbereitung

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

HTTPS-Zertifikat

Sie können Ihre App 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 App bereitzustellen oder 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öchten, können Sie mkcert verwenden.

Google Cloud-Projekt

Sie müssen ein Google Cloud-Projekt für die Verwendung mit diesen Beispielen konfigurieren. In der Anleitung Google Cloud-Projekt erstellen finden Sie eine Übersicht über die erforderlichen Schritte. Im Abschnitt Google Cloud-Projekt einrichten der ersten Schritt-für-Schritt-Anleitung werden auch die erforderlichen Konfigurationsschritte erläutert.

Laden Sie zum Schluss Ihre OAuth 2.0-Client-ID als JSON-Datei herunter. Sie müssen diese Anmeldedatendatei dem entpackten Beispielverzeichnis hinzufügen. Unter Dateien finden Sie Informationen zu den einzelnen Standorten.

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.
Auf der nächsten Seite:
- Legen Sie als Anwendungstyp 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 oder https://localhost:5000/callback. Diese Route erstellen und verarbeiten Sie später in dieser Anleitung. Sie können diese Routen jederzeit bearbeiten oder weitere hinzufügen.
- Klicke auf ERSTELLEN.
Daraufhin 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 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

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 Unterverzeichnis der heruntergeladenen Beispiele befindet sich ein requirements.txt. Mit pip können Sie die erforderlichen Bibliotheken schnell 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 angegebenen Links herunterladen.

Für dieses Beispiel ist Node.js v16.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.

Für Spring Boot-Anwendungen können Gradle oder Maven zum Verwalten von Builds und Abhängigkeiten verwendet werden. Dieses Beispiel enthält den Maven-Wrapper, der einen erfolgreichen Build ermöglicht, ohne dass Sie Maven selbst installieren müssen.

Führen Sie im Verzeichnis, in das 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

Auf Windows:

java -version
mvnw.cmd --version

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 in der Anleitung. 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 Anleitung zum Erstellen eines Add-ons.

Verzeichnisinhalt

Der Inhalt des Verzeichnisses variiert je nach Implementierungssprache:

Python

Das Verzeichnisverzeichnis enthält die folgenden Dateien:
- main.py ist der Einstiegspunkt der Python-Anwendung. Geben Sie die gewünschte Serverkonfiguration in dieser Datei an und führen Sie sie aus, um den Server zu starten.
- requirements.txt: Die Python-Module, die zum Ausführen der Webanwendung erforderlich sind. Sie können mit pip install -r requirements.txt automatisch installiert werden.
- client_secret.json: die Clientschlüsseldatei, die aus Google Cloud heruntergeladen wurde. Beachten Sie, dass dies nicht im Beispielarchiv enthalten ist. Sie sollten die heruntergeladene Datei mit den Anmeldedaten umbenennen und in jedes Verzeichnisstammverzeichnis 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 Flask-Server.
Das Verzeichnis webapp enthält die Inhalte der Webanwendung. Folgende Angaben sind enthalten:
Das Verzeichnis /templates/ 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 Initiator für das webapp-Modul. Dieser Initializer 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 Unterordner von <step>. Jeder Schritt enthält Folgendes:

Statische Dateien wie JavaScript, CSS und Bilder befinden sich im Ordner ./<step>/public.
Expressrouter befinden sich in den Ordnern ./<step>/routes.
HTML-Vorlagen finden Sie 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: + java.com.addons.spring-Verzeichnis mit den 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. Außerdem enthält es die Datei application.properties, in der der Port zum Ausführen des Servers, der Pfad zur Keystore-Datei und der Pfad zum Verzeichnis templates angegeben sind. In diesem Beispiel ist die Schlüsselspeicherdatei im Verzeichnis resources enthalten. Sie können sie an einem beliebigen Ort speichern. Achten Sie aber darauf, die Datei application.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. Fügen Sie in diesem .gitignore den Pfad zu Ihrem Schlüsselspeicher hinzu. Im Beispiel ist das secrets/*.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 Datei client_secret.json angeben, damit Ihre Secrets nicht in ein Remote-Repository aufgenommen werden. Ab Schritt 3 sollten Sie den Pfad zur H2-Datenbankdatei und zur Dateidatenspeicher-Fabrik hinzufügen. Weitere Informationen zur Einrichtung dieser Datenspeicher finden Sie in der dritten Schritt-für-Schritt-Anleitung zum Umgang mit wiederholten Besuchen.
- mvnw und mvnw.cmd sind die ausführbaren Maven-Wrapper 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

Sie müssen Ihren Server starten, um ihn zu testen. So führen Sie den Beispielserver in der gewünschten Sprache aus:

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 Serverstartdatei Ihrer Anwendung.

Server konfigurieren

Es gibt mehrere Möglichkeiten, den Webserver auszuführen. Fügen Sie am Ende der Python-Datei eines der folgenden Elemente hinzu:

Ungesicherte localhost. Hinweis: Diese Methode eignet sich nur für den direkten Test 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)

localhost sperren 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)

Gunicorn-Server Dies eignet sich für eine produktionsreife Server- oder Cloud-Bereitstellung. Wir empfehlen, eine Umgebungsvariable vom Typ 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 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 selbstsigniertes Zertifikat erstellen, das zum Ausführen der Anwendung über HTTPS verwendet 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 Ihrem OS-Schlüsselbund 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 in Git committen möchten.

Server starten

Sie können die Anwendung mit dem folgenden Befehl ausführen. Ersetzen Sie dabei step01 durch den Schritt, 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.

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.

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>

In diesem Beispiel befindet sich die Keystore-Datei im Ressourcenverzeichnis. 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 in Git committen 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 entweder 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 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 unter dem in application.properties angegebenen Port gestartet.