Classroom-Add-on erstellen

Dies ist die erste Schritt-für-Schritt-Anleitung der Reihe zu Classroom-Add-ons.

In dieser Schritt-für-Schritt-Anleitung legen Sie den Grundstein für die Entwicklung einer Webanwendung und deren Veröffentlichung als Classroom-Add-on. Zukünftige Schritt-für-Schritt-Anleitungen erweitern diese App.

Im Verlauf dieser Schritt-für-Schritt-Anleitung führen Sie Folgendes aus:

• Erstellen Sie ein neues Google Cloud-Projekt für Ihre Webanwendung.
• Eine grundlegende Webanwendung mit Platzhalterschaltflächen für die Anmeldung erstellen.
• Veröffentlichen Sie einen privaten Google Workspace Marketplace (GWM)-Store-Eintrag für Ihre Webanwendung.

Anschließend können Sie das Add-on installieren und in den iFrame von Classroom-Add-ons laden.

Wichtig :Bevor Sie mit diesen Schritt-für-Schritt-Anleitungen fortfahren, lesen Sie den Leitfaden zur Projektkonfiguration und führen Sie die Schritte 1–6 des Prozesses als Entwickler aus.

Voraussetzungen

Wählen Sie unten eine Sprache aus, um die entsprechenden Voraussetzungen zu sehen:

Python

In unserem Python-Beispiel wird das gcloud-Framework verwendet. Sie können den vollständigen Quellcode für alle Schritt-für-Schritt-Anleitungen auf der Übersichtsseite herunterladen. Den Code für diese Schritt-für-Schritt-Anleitung finden Sie im Verzeichnis /flask/01-basic-app/.

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

python -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

Jedes Unterverzeichnis der Schritt-für-Schritt-Anleitung in den heruntergeladenen Beispielen enthält ein requirements.txt. Mit pip können Sie die erforderlichen Bibliotheken schnell installieren. So installieren Sie die erforderlichen Bibliotheken für diese 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. Sie können den vollständigen Quellcode für alle Schritt-für-Schritt-Anleitungen auf der Übersichtsseite herunterladen.

Installieren Sie bei Bedarf NodeJS v16.13 oder höher.

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 für alle Schritt-für-Schritt-Anleitungen auf der Übersichtsseite 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.

Um unser Beispiel ausführen zu können, müssen Sie die folgenden Befehle in dem Verzeichnis ausführen, in das Sie das Projekt heruntergeladen haben. So prüfen Sie, ob Sie die Voraussetzungen zum Ausführen des Projekts haben.

java --version
./mvnw --version

Auf Windows:

java -version
mvnw.cmd --version

Google Cloud-Projekt einrichten

Der Zugriff auf die Classroom API und die erforderlichen Authentifizierungsmethoden werden von Google Cloud-Projekten gesteuert. In der folgenden Anleitung erfahren Sie, wie Sie ein neues Projekt zur Verwendung mit Ihrem Add-on erstellen und konfigurieren.

Projekt erstellen

Erstellen Sie auf der Seite zur Projekterstellung ein neues Google Cloud-Projekt. Sie können einen beliebigen Namen für das neue Projekt angeben. Klicken Sie auf Erstellen.

Es dauert einen Moment, bis das neue Projekt vollständig erstellt ist. Wählen Sie anschließend das Projekt aus. Sie können es oben auf dem Bildschirm im Drop-down-Menü zur Projektauswahl auswählen oder oben rechts im Benachrichtigungsmenü auf PROJEKT AUSWÄHLEN klicken.

Wichtig :Achten Sie darauf, dass Sie das richtige Projekt ausgewählt haben, bevor Sie fortfahren.

Hängen Sie das GWM SDK an das Google Cloud-Projekt an

Öffnen Sie den Browser API Library (API-Bibliothek). Suchen Sie nach Google Workspace Marketplace SDK. Das SDK sollte in der Ergebnisliste angezeigt werden.

Wählen Sie die Karte „Google Workspace Marketplace SDK“ aus und klicken Sie auf Aktivieren.

GWM SDK konfigurieren

GWM stellt eine Liste bereit, über die Nutzer und Administratoren Ihr Add-on installieren. Konfigurieren Sie den OAuth-Zustimmungsbildschirm und die App-Konfiguration und den Store-Eintrag des GWM SDK, um fortzufahren.

OAuth-Zustimmungsbildschirm

Der OAuth-Zustimmungsbildschirm wird angezeigt, wenn Nutzer Ihre Anwendung zum ersten Mal autorisieren. Sie werden aufgefordert, der Anwendung den Zugriff auf ihre personenbezogenen Daten und Kontoinformationen gemäß den von Ihnen aktivierten Bereichen zu erlauben.

Rufen Sie die Seite zum Erstellen des OAuth-Zustimmungsbildschirms auf. Gib folgende Informationen an:

• Setzen Sie Nutzertyp auf Extern. Klicken Sie auf Erstellen.
• Geben Sie auf der nächsten Seite die erforderlichen App-Details und Kontaktdaten ein. Geben Sie unter Autorisierte Domains alle Domains an, die Ihre App hosten. Klicke auf SPEICHERN UND FORTFAHREN.

• Fügen Sie alle OAuth-Bereiche hinzu, die für Ihre Web-App erforderlich sind. Im OAuth-Konfigurationsleitfaden finden Sie eine ausführliche Beschreibung der Bereiche und ihres Zwecks.

  Sie müssen mindestens einen der folgenden Bereiche anfordern, damit Google den Abfrageparameter login_hint senden kann. Eine ausführlichere Erläuterung dieses Verhaltens finden Sie in unserem OAuth-Konfigurationsleitfaden:

  • https://www.googleapis.com/auth/userinfo.email (bereits enthalten)
  • https://www.googleapis.com/auth/userinfo.profile (bereits enthalten)

  Die folgenden Umfänge gelten speziell für Classroom-Add-ons:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

  Schließen Sie auch alle anderen Google API-Bereiche ein, die Ihre Anwendung von Endnutzern verlangt.

  Klicken Sie auf SPEICHERN UND FORTFAHREN.

• Listen Sie auf der Seite Testnutzer die E-Mail-Adressen aller Testkonten auf. Klicke auf SPEICHERN UND FORTFAHREN.

Prüfen Sie, ob Ihre Einstellungen korrekt sind, und kehren Sie dann zum Dashboard zurück.

Anwendungskonfiguration

Rufen Sie die Seite App-Konfiguration des GWM SDK auf. Gib folgende Informationen an:

• Legen Sie die Sichtbarkeit der App auf Private fest. Diese Einstellung ist für Test- und Entwicklungszwecke geeignet und die richtige Wahl für diese Schritt-für-Schritt-Anleitungen. Wählen Sie Public nur dann aus, wenn Ihr Add-on für die Allgemeinheit verwendet werden soll.

  Warnung: Prüfen Sie vor dem Speichern, ob die Einstellung für die App-Sichtbarkeit korrekt ist. Sie können die App-Sichtbarkeit nicht mehr ändern, nachdem sie festgelegt wurde. Sie müssen ein neues Google Cloud-Projekt erstellen, um eine andere Anwendungssichtbarkeit festzulegen.

• Setzen Sie Installationseinstellungen auf Admin Only install, wenn Sie die Installation auf Domainadministratoren beschränken möchten.

• Wählen Sie unter App-Integration die Option Classroom-Add-on aus. Sie werden aufgefordert, den sicheren URI für die Anhangeinrichtung einzugeben. Das ist die URL, die geladen werden soll, wenn ein Nutzer Ihr Add-on öffnet. Für diese Schritt-für-Schritt-Anleitung sollte https://<your domain>/addon-discovery verwendet werden.

• Die Zulässigen Präfixe für Anhangs-URIs werden verwendet, um die in AddOnAttachment festgelegten URIs mithilfe der Methoden courses.*.addOnAttachments.create und courses.*.addOnAttachments.patch zu validieren. Die Validierung erfolgt über eine Übereinstimmung mit dem Präfix des Literalstrings und die Verwendung von Platzhaltern ist derzeit nicht zulässig. Sie können diese Felder vorerst leer lassen.

• Fügen Sie dieselben OAuth-Bereiche hinzu, die im vorherigen Schritt auf Ihrem OAuth-Zustimmungsbildschirm angegeben wurden.

  Warnung :Ihr Add-on kann nicht veröffentlicht werden, wenn in der App-Konfiguration andere Bereiche als im OAuth-Zustimmungsbildschirm aufgeführt sind.

• Füllen Sie die für Ihre Organisation passenden Felder unter Entwickler-Links aus.

Store-Eintrag

Gehen Sie im GWM SDK zur Seite Store-Eintrag. Gib folgende Informationen an:

• Fügen Sie unter App-Details eine Sprache hinzu oder maximieren Sie das Drop-down-Menü neben der bereits aufgeführten Sprache. Geben Sie einen Anwendungsnamen und Beschreibungen an. Diese werden auf der Seite des GWM-Store-Eintrags des Add-ons angezeigt. Klicken Sie zum Speichern auf Fertig.
• Wählen Sie eine Kategorie für das Add-on aus.
• Stellen Sie unter Grafikinhalte Bilder für die Pflichtfelder bereit. Sie können später geändert werden und können Platzhalter sein, wenn Sie die App-Sichtbarkeit im vorherigen Schritt auf Privat gesetzt haben.
• Geben Sie unter Supportlinks die angeforderten URLs an. Hierbei kann es sich um Platzhalter handeln, wenn Sie im vorherigen Schritt die Sichtbarkeit der Anwendung auf Privat gesetzt haben.

Klicke auf VERÖFFENTLICHEN, um deine Einstellungen zu speichern. Wenn Sie die Sichtbarkeit der Anwendung im vorherigen Schritt auf Privat gesetzt haben, kann die Anwendung sofort installiert werden. Wenn Sie die Sichtbarkeit der Anwendung auf Öffentlich setzen, wird Ihre Anwendung vom GWM-Team zur Überprüfung gesendet, bevor sie für die Installation zur Verfügung gestellt werden kann.

Add-on installieren

Sie können das Add-on jetzt über den Link oben auf der Seite Store-Eintrag des GWM SDK installieren. Klicken Sie oben auf der Seite auf die App-URL, um den Eintrag aufzurufen, und wählen Sie dann Installieren aus.

Hinweis: Du kannst das Add-on nur installieren, wenn du mit einem Konto angemeldet bist, das du beim Konfigurieren des OAuth-Zustimmungsbildschirms als Testnutzer angegeben hast.

Einfache Webanwendung erstellen

Richten Sie eine grundlegende Webanwendung mit zwei Routen ein. In zukünftigen Schritt-für-Schritt-Anleitungen wird diese Anwendung erweitert. Erstellen Sie also vorerst nur eine Landingpage für das Add-on /addon-discovery und eine simulierte Indexseite / für unsere „Unternehmenswebsite“.

Implementieren Sie diese beiden Endpunkte:

• /: Zeigt eine Willkommensnachricht und eine Schaltfläche zum Schließen des aktuellen Tabs und des Add-on-iFrames an.
• /addon-discovery: zeigt eine Willkommensnachricht und zwei Schaltflächen an: eine zum Schließen des Add-on-iFrames und eine zum Öffnen einer Website in einem neuen Tab.

Beachten Sie, dass wir Schaltflächen zum Erstellen und Schließen von Fenstern oder dem iFrame hinzufügen. Damit wird eine Methode gezeigt, mit der der Nutzer in der nächsten Schritt-für-Schritt-Anleitung sicher in einem neuen Tab zur Autorisierung aufgerufen werden kann.

Dienstprogrammskript erstellen

Erstellen Sie ein static/scripts-Verzeichnis. Erstellen Sie eine neue Datei (addon-utils.js). Fügen Sie die folgenden beiden Funktionen hinzu.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function above, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Routen erstellen

Implementieren Sie die Endpunkte /addon-discovery und /.

Python

Anwendungsverzeichnis einrichten

Strukturieren Sie für dieses Beispiel die Anwendungslogik als Python-Modul. Dies ist in unserem Beispiel das Verzeichnis webapp.

Erstellen Sie ein Verzeichnis für das Servermodul, z. B. webapp. Verschieben Sie das Verzeichnis static in das Modulverzeichnis. Erstellen Sie auch im Modulverzeichnis ein template-Verzeichnis. Ihre HTML-Dateien werden hier gespeichert.

Servermodul erstellen*

Erstellen Sie die Datei __init__.py in Ihrem Modulverzeichnis und fügen Sie die folgenden Importe und Deklarationen hinzu.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Erstellen Sie dann eine Datei zur Verarbeitung der Routen der Webanwendung. In unserem Beispiel ist dies webapp/routes.py. Implementieren Sie die beiden Routen in dieser Datei.

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Beachten Sie, dass unsere Routen beide eine message-Variable an ihre jeweiligen Jinja-Vorlagen übergeben. Dies ist hilfreich, um zu ermitteln, auf welche Seite der Nutzer gelangt ist.

Konfigurations- und Startdateien erstellen

Erstellen Sie die Dateien main.py und config.py im Stammverzeichnis Ihrer Anwendung. Konfigurieren Sie Ihren geheimen Schlüssel in config.py.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

Importieren Sie das Modul in die Datei main.py und starten Sie den Prometheus-Server.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

Routen sind in der Datei app.js mit den folgenden Zeilen registriert.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/classroom-addon', addonRouter);

Öffnen Sie /01-basic-app/routes/index.js und prüfen Sie den Code. Diese Route wird erreicht, wenn der Endnutzer die Unternehmenswebsite besucht. Die Route rendert eine Antwort mit der Vorlage index-Handlebars und übergibt der Vorlage ein Datenobjekt, das title- und message-Variablen enthält.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

Öffnen Sie die zweite Route /01-basic-app/routes/classroom-addon.js und prüfen Sie den Code. Diese Route wird erreicht, wenn der Endnutzer das Add-on besucht. Bei dieser Route werden die Vorlage discovery Lenker und zusätzlich das Layout addon.hbs verwendet, um die Seite anders als die Unternehmenswebsite zu rendern.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
});
});

Java

Im Java-Codebeispiel werden Module verwendet, um die sequenziellen Schritt-für-Schritt-Anleitungen zu bündeln. Da dies die erste Schritt-für-Schritt-Anleitung ist, befindet sich der Code im Modul step_01_basic_app. Es ist nicht zu erwarten, dass Sie Ihr Projekt mithilfe von Modulen implementieren. Stattdessen sollten Sie auf einem einzelnen Projekt aufbauen, wenn Sie die einzelnen Schritte in der Schritt-für-Schritt-Anleitung ausführen.

Erstellen Sie in diesem Beispielprojekt die Controller-Klasse Controller.java, um die Endpunkte zu definieren. Importieren Sie in dieser Datei die Annotation @GetMapping aus der Abhängigkeit spring-boot-starter-web.

import org.springframework.web.bind.annotation.GetMapping;

Fügen Sie über der Klassendefinition die Spring Framework-Controller-Annotation ein, um den Zweck der Klasse anzugeben.

@org.springframework.stereotype.Controller
public class Controller {

Implementieren Sie dann die beiden Routen und eine zusätzliche Route für die Fehlerbehandlung.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Add-on testen

Wichtig :Sie können Ihre Anwendung zwar direkt über einen Webbrowser testen, sollten sie aber hauptsächlich in den iFrames der Classroom-Add-ons testen. Das Laden der Webanwendung in einem iFrame kann zu untypischen Verhaltensweisen führen. Eine Beschreibung der einzelnen iFrames finden Sie auf der Seite Leitfaden zu iFrame- und Abfrageparametern. Bei allen Anleitungen in dieser Schritt-für-Schritt-Anleitung wird davon ausgegangen, dass das Add-on im Kontext eines iFrames verwendet werden kann.

Starten Sie den Server. Melden Sie sich dann als einer Ihrer Teacher-Testnutzer in Google Classroom an. Gehen Sie zum Tab Kursaufgaben und erstellen Sie eine neue Aufgabe. Klicken Sie unter dem Textbereich auf die Schaltfläche Add-ons und wählen Sie das Add-on aus. Der iFrame wird geöffnet und das Add-on lädt den URI für die Anhangeinrichtung, den Sie im GWM SDK auf der Seite App-Konfiguration angegeben haben.

Glückwunsch! Sie können nun mit dem nächsten Schritt fortfahren: Nutzer mit Google SSO anmelden.