Google Cloud-Projektkonfiguration

Auf dieser Seite finden Sie Informationen zum Erstellen und Konfigurieren von Google Cloud-Projekten für Classroom-Add-ons. Google Cloud-Projekte werden verwendet, um die Google-Einmalanmeldung (SSO) über OAuth 2.0 zu implementieren, Anfragen Ihres Add-ons zu autorisieren und das Add-on im Google Workspace Marketplace zu verwalten.

Allgemeinere Informationen zum Veröffentlichen eines Add-ons im Marketplace finden Sie unter App veröffentlichen.

Google Cloud-Projekt erstellen

Es gibt zwei Arten von Projekten: ein privates Projekt für die Entwicklung und ein öffentliches Projekt, das für Endnutzer erreichbar ist. Die Labels „öffentlich“ und „privat“ beziehen sich auf die Sichtbarkeit Ihrer Anwendung im Google Workspace Marketplace. Eine private Marketplace-Anwendung kann nur von Nutzern in der Domain installiert werden, in der sie erstellt wurde. Eine öffentliche Marketplace-Anwendung ist für jede Google Workspace-Domain verfügbar. Es muss sich um zwei separate Anwendungen handeln, da ein Projekt nicht gleichzeitig öffentlich und privat sein kann. Öffentliche Anwendungen müssen überprüft und genehmigt werden, bevor sie auf dem Marketplace verfügbar sind.

Allgemeine Informationen zum Erstellen von Google Cloud-Projekten finden Sie unter Google Cloud-Projekt erstellen.

Öffentliches Google Cloud-Projekt erstellen

Dieses Projekt stellt die Add-on-Anwendung dar, auf die Administratoren, Lehrkräfte und Schüler/Studenten zugreifen können. Ein öffentliches Projekt muss vom Google Workspace Marketplace-Team überprüft und genehmigt werden, bevor es gestartet oder installiert werden kann.

1. Erstellen Sie ein neues Google Cloud-Projekt in Ihrer Produktionsdomain.

   Google Cloud-Projekt erstellen

2. Aktivieren Sie die Classroom API in Ihrem Cloud-Projekt.

   Classroom API aktivieren

3. Aktivieren Sie das Google Workspace Marketplace SDK in Ihrem Cloud-Projekt.

   Google Workspace Marketplace SDK aktivieren

4. Setzen Sie die App-Konfiguration des Marketplace SDK App-Sichtbarkeit auf Öffentlich und aktivieren Sie das Kästchen Nicht gelistet.

5. Füllen Sie die Pflichtfelder auf der Seite Store-Eintrag des Marketplace SDK aus und klicken Sie auf VERÖFFENTLICHEN.

6. Ihre App wird vom Google Workspace Marketplace-Team überprüft. Sie werden über die im Marketplace SDK angegebene E‑Mail-Adresse des Entwicklers mit Ihnen kommunizieren. Nachdem die App genehmigt wurde, entfernen Sie das Häkchen aus dem Feld Nicht aufgeführt, damit Lehrkräfte und Administratoren sie im Marketplace finden können.

Privates Google Cloud-Projekt erstellen

Dieses private Projekt stellt die Add-on-Anwendung dar, die für die Entwicklung verwendet wird. Sie ist für Nutzer außerhalb der Domain, in der sie erstellt wurde, nicht zugänglich, muss aber vor der Installation nicht genehmigt werden. Google empfiehlt daher, dieses Projekt zu verwenden, um Ihr Add-on in einer kontrollierten Umgebung zu entwickeln und zu testen.

Sie benötigen Zugriff auf eine Google Workspace for Education-Domain mit der Teaching and Learning- oder Plus-Lizenz, um ein privates Projekt zu erstellen. Wenn Sie noch keinen Zugriff auf eine solche Domain haben, gehen Sie so vor, um eine Google Workspace for Education-Demodomäne einzurichten, sie auf eine Plus-Lizenz zu upgraden und den Zugriff auf die Classroom-Add-ons-API zu ermöglichen:

1. Führen Sie die Schritte aus, um eine Entwickler-Testdomain zu erhalten.

2. Erstellen Sie ein neues Google Cloud-Projekt, während Sie als Administrator in der Demodomäne angemeldet sind.

   Google Cloud-Projekt erstellen

   Wenn Sie nicht auf die Google Cloud Console zugreifen oder Cloud-Projekte erstellen können, prüfen Sie Folgendes in der Admin-Konsole:

   • Rufen Sie die Seite Kontoeinstellungen > Einstellungen für altersabhängigen Zugriff auf und wählen Sie die Option Alle Nutzer in dieser Gruppe oder Organisationseinheit sind mindestens 18 Jahre alt aus.
   • Unter Apps > Zusätzliche Google-Dienste:
   • Die Google Cloud Platform ist für alle aktiviert.
   • Die Einstellungen für die Projekterstellung sind Nutzern erlauben, Projekte zu erstellen.
   • Die Cloud Shell-Zugriffseinstellungen sind Zugriff auf Cloud Shell erlauben.

3. Füllen Sie das Antragsformular für das Upgrade einer Demodomäne aus und senden Sie es ab. Wenn Sie dieses Formular einreichen, beantragen Sie, dass Google Ihre Demodomäne auf Google Workspace for Education Plus mit zehn Lizenzen aktualisiert und Ihr Cloud-Projekt für die Classroom-Add-ons-API freigibt.

   Sie erhalten eine E-Mail, wenn die Prozesse für das Upgrade und die Zulassungsliste abgeschlossen sind. Weisen Sie Ihren Testlehrerkonten in der Admin-Konsole Plus-Lizenzen zu. Erstellen oder wählen Sie unter Verzeichnis > Nutzer Ihre Testlehrerkonten aus. Prüfen Sie in den Lizenzen jedes Lehrers, ob Google Workspace for Education Plus zugewiesen ist.

4. Aktivieren Sie die Classroom API in Ihrem Cloud-Projekt.

   Classroom API aktivieren

5. Aktivieren Sie das Google Workspace Marketplace SDK in Ihrem Cloud-Projekt.

   Google Workspace Marketplace SDK aktivieren

6. Legen Sie für das Marketplace SDK unter App-Konfiguration Sichtbarkeit der App die Option Privat fest.

7. Füllen Sie die Pflichtfelder auf der Seite Store-Eintrag des Marketplace SDK aus und klicken Sie auf VERÖFFENTLICHEN. Nachdem der App-Eintrag veröffentlicht wurde, können Nutzer in der Domain die App im Google Workspace Marketplace finden und installieren oder die App-URL auf der Seite „Store-Eintrag“ aufrufen.

oauth 2.0

Für den Zugriff auf die Classroom API ist die Einwilligung zum Zugriff auf Nutzerdaten erforderlich. Diese werden abgerufen, indem Google-Zugriff auf OAuth-Bereiche für den angemeldeten Nutzer angefordert und ein Token empfangen wird, das anschließend für API-Aufrufe an Google Classroom verwendet werden kann. Bereiche müssen im Google Workspace Marketplace-Eintrag konfiguriert werden, damit der Domainadministrator im Namen seiner Domainnutzer die Einwilligung erteilen kann, wenn er das Add-on installiert.

Da Classroom-Bereiche vertraulich sind, müssen Sie die OAuth-Überprüfung beantragen, bevor Sie Ihr Add‑on aktivieren. Andernfalls sehen Nutzer eine Warnmeldung, dass die Anwendung nicht überprüft ist, und nur eine kleine Anzahl von Nutzern kann auf Ihr Produkt zugreifen. Weitere Informationen zur Überprüfung finden Sie in der Übersicht über den Überprüfungsablauf.

Eine detaillierte Liste aller verfügbaren Bereiche und ihrer Verwendung finden Sie auf der Seite OAuth-Bereiche für Google APIs. Allgemeine Informationen zur OAuth-Konfiguration finden Sie in der Workspace-Dokumentation unter OAuth-Seite konfigurieren.

Nutzerberechtigungen

Ihre Web-App sollte mindestens einen der folgenden Bereiche anfordern:

• https://www.googleapis.com/auth/userinfo.email, mit der eine Anwendung die E-Mail-Adresse des Nutzers aufrufen kann.
• https://www.googleapis.com/auth/userinfo.profile, wodurch eine Anwendung personenbezogene Daten wie Porträt, Vor- und Nachname sowie andere personenbezogene Daten sehen kann, die der Nutzer öffentlich zugänglich gemacht hat.

Nachdem ein Nutzer einen dieser Bereiche in Ihrem Add-on autorisiert hat, wird er durch den Abfrageparameter login_hint identifiziert. Dieser Parameter wird an alle URLs Ihrer Web-App übergeben, wenn ein iFrame geöffnet wird. Wenn ein Nutzer keinen dieser Bereiche autorisiert hat, wird login_hint nicht gesendet.

login_hint ist ein Standardparameter für OpenID Connect, den Sie optional an Google übergeben können, wenn Sie Google Log-in verwenden oder ein OAuth-Token anfordern. Dadurch soll die Autorisierung für den Endnutzer reibungsloser ablaufen.

Bereiche für Classroom-Add‑ons

Die folgenden Bereiche sind spezifisch für Classroom-Add-ons:

• https://www.googleapis.com/auth/classroom.addons.teacher, die Zugriff auf alle API-Methoden ermöglicht.
• https://www.googleapis.com/auth/classroom.addons.student, die den Zugriff auf Startvalidierungs- und Anhanglesevorgänge ermöglicht.

Auch mit einem gültigen OAuth-Zugriffstoken, das die Anmeldedaten des Nutzers angibt, unterliegen API-Aufrufe zusätzlichen Anforderungen:

• Für alle Methoden muss der Nutzer eine Lehrkraft oder ein Schüler/Student im Kurs sein, der durch die courseId in der Anfrage angegeben wird.
• Für das Erstellen, Aktualisieren und Löschen von Anhängen sowie für die Rückgabe von Noten muss der Nutzer eine Lehrkraft sein.
• Aufrufe eines bestimmten Google Classroom-Beitrags unterliegen den folgenden Prüfungen.
  • Wenn ein Add-on bereits mindestens einen Anhang in einem Beitrag hat, kann es Anfragen für Folgendes stellen:
    • Validierung des iFrame-Starts
    • Vorgänge zum Lesen, Aktualisieren und Löschen von Anhängen
    • Notenaktualisierungen für diesen Beitrag
  • Wenn das Attachment Discovery-iFrame zum ersten Mal geöffnet wird, ist möglicherweise noch kein Anhang im Beitrag vorhanden. Es wird ein addOnToken-Abfrageparameter bereitgestellt, mit dem Anfragen für Folgendes gestellt werden können:
    • Anhang unter dem Beitrag erstellen (addOnToken erforderlich)
    • Startvalidierung (addOnToken wird validiert, falls angegeben, und ist erforderlich, wenn das Add-on keinen vorhandenen Anhang im Beitrag hat)

OAuth-Überprüfung

Ein Classroom-Add-on verwendet Google APIs, um auf die Daten von Google-Nutzern zuzugreifen.

• Markenidentität bestätigen
• Vertrauliche OAuth-Bereiche bestätigen

Weitere Informationen zum Überprüfungsprozess

Google Workspace Marketplace-Eintrag

Allgemeine Informationen zur Konfiguration des Google Workspace Marketplace SDK finden Sie unter Google Workspace Marketplace SDK aktivieren und konfigurieren und Google Workspace Marketplace-Eintrag erstellen.

Überlegungen zur Auflistung

Im Marketplace SDK-Store-Eintrag Ihres öffentlichen Google Cloud-Projekts werden der Name und die Beschreibungen Ihrer Anwendung für Endnutzer angegeben. Sie können diese Details unter App-Details in mehreren Sprachen angeben.

Beachten Sie bei Ihren Einträgen die folgenden Richtlinien:

• Unter App-Details:
  • Vermeiden Sie die Verwendung von Satzzeichen im Anwendungsnamen. Verwenden Sie beispielsweise Mein Add-on von Mein Unternehmen anstelle von „Mein Unternehmen: Mein Add-on“ oder „Mein Add-on von Mein Unternehmen“.
  • Die Kurzbeschreibung und die Ausführliche Beschreibung dürfen nicht denselben Text enthalten.
  • Achten Sie darauf, dass Sie einen Wert für das Feld Preise ausgewählt haben. Dieses Feld enthält Optionen für die Preisgestaltung Kostenlos, Kostenpflichtig mit kostenlosem Testzeitraum, Kostenpflichtig mit kostenlosen Funktionen und Kostenpflichtig. Sie müssen den Kostenbetrag nicht im Marketplace-Eintrag angeben.
  • Achten Sie darauf, dass Sie einen Wert für das Feld Kategorie ausgewählt haben. Akademische Ressourcen oder Tools für Lehrkräfte und Administratoren sind möglicherweise eine gute Wahl für ein Classroom-Add-on.
  • Weitere Informationen finden Sie in der Beschreibung der App-Details im Marketplace.

• Unter Grafik-Assets:
  • Die bereitgestellten Grafiken sind nicht unscharf und entsprechen den in den Google Workspace Marketplace-Standards angegebenen Größen.
  • Alle bereitgestellten Screenshots bilden die Nutzung Ihres Add-ons korrekt ab.
• Unter Support-Links:
  • Achten Sie darauf, dass Sie einen Link zu den Nutzungsbedingungen Ihrer Anwendung angegeben haben.
• Achten Sie darauf, dass Sie die Branding-Richtlinien für Google-APIs einhalten, in denen zulässige Namen und Beschreibungen aufgeführt sind.
• Wenn Sie in Ihrem Eintrag auf Google-Produkte verweisen, verwenden Sie den Namen im Format, das in der Markenliste angegeben ist. Fügen Sie das Markensymbol (™) ein, falls angegeben. Verwenden Sie „Google Docs™“ und nicht „Google Docs“.

In die Lizenzierungs- und Abrechnungsdienste von Google einbinden

Wenn Sie Ihre Google Workspace Marketplace-Anwendungen in die Lizenzierungs- und Abrechnungsdienste von Google einbinden möchten, besuchen Sie die Marketplace API.

Installationseinstellungen

Add-ons können neben der Administratorinstallation auch die einzelne Installation ermöglichen. Auf dieser Seite werden einige Unterschiede zwischen den beiden Installationstypen beschrieben. Es soll kein Installationstyp beworben werden. Sie können auf der Seite App-Konfiguration des Google Workspace Marketplace SDK festlegen, ob die individuelle Installation zulässig sein soll.

Installation durch Administrator

Bei Administratorinstallationen kann ein Administrator ein Add‑on allen Konten in einer Domain oder bestimmten Zugriffsgruppen oder Organisationseinheiten hinzufügen. Nur ein Domainadministrator kann eine Administratorinstallation durchführen. Der Administrator kann optional im Namen aller Nutzer in der Domain allen Zugriffsbereichen zustimmen. In diesem Fall werden Nutzer nicht aufgefordert, Zugriffsbereichen zuzustimmen.

Im Folgenden finden Sie einige Hinweise zur Installation durch Administratoren.

• Strengere Kontrollen Administratoren können einschränken, welche Nutzer auf ein Add-on zugreifen können.
• Kompatibilität mit der Lizenzierung: Wenn für Ihre Anwendung eine Lizenz erforderlich ist, kann es sinnvoll sein, Installationen über einen Administrator zu leiten, um sicherzustellen, dass Lizenzen angemessen an die entsprechende Bildungseinrichtung verteilt und von dieser verwendet werden.
• Geringere Belastung für Endnutzer: Durch die Installation durch einen Administrator wird der Einrichtungsaufwand für Lehrkräfte sowie Schüler und Studenten reduziert. Das könnte zu einer reibungsloseren Nutzererfahrung mit weniger Klicks und weniger Verwirrung führen.

Weitere Informationen zur Administratorinstallation finden Sie unter Marketplace-Apps in Ihrer Domain installieren. Informationen zu Organisationseinheiten und Zugriffsgruppen finden Sie unter Funktionsweise der Organisationsstruktur.

Individuelle Installation

Bei individuellen Installationen wird ein Add-on dem Konto des Nutzers hinzugefügt. Der Nutzer wird bei der Installation aufgefordert, den Zugriffsbereichen des Add-ons zuzustimmen.

Im Folgenden finden Sie einige Aspekte, die Sie bei der individuellen Installation berücksichtigen sollten.

• Einführung erleichtern: Mehr Nutzer können Ihr Add-on im Google Workspace Marketplace sehen und installieren. Wenn Sie die individuelle Installation zulassen, werden möglicherweise mehr Lehrkräfte Ihr Produkt verwenden oder empfehlen.
• Administratortests: Ein Administrator kann ein Add-on einzeln installieren, um es zu testen oder zu bewerten, bevor er es für eine größere Gruppe genehmigt oder installiert.

Administratoren können nicht nur Add-ons im Namen von Nutzern installieren, sondern auch eine Zulassungsliste führen, damit Nutzer Add-ons installieren können, die eine individuelle Installation ermöglichen. Wenn ein Add-on nicht auf der Zulassungsliste steht, können Nutzer den Eintrag des Add-ons im Google Workspace Marketplace weiterhin sehen, es aber nicht installieren. Stattdessen wird eine Meldung angezeigt, in der erklärt wird, dass die Installation des Add-ons von einem Domainadministrator nicht zugelassen wurde. Weitere Informationen zu diesem Verhalten finden Sie im Hilfeartikel Google Workspace Marketplace-Apps auf die Zulassungsliste setzen.

Weitere Informationen finden Sie in der Dokumentation zu den Installationseinstellungen für den Google Workspace Marketplace.

App-Einbindung

Sie müssen im Feld Attachment Setup URI eine Start-Iframe-URL angeben. Diese URL wird als src-Wert des iFrames für das Attachment Discovery-iFrame verwendet. Das iframe „Attachment Discovery“ wird von Lehrkräften verwendet, um Inhalte oder Aktivitäten zu finden, die sie an ihre Aufgabe anhängen möchten. Sie kann in der Google Cloud-Projektkonsole festgelegt werden.

Die zulässigen Präfixe für Anhangs-URIs werden verwendet, um die in einem AddOnAttachment festgelegten URIs mit den Methoden *.addOnAttachments.create und *.addOnAttachments.patch zu validieren. Die Validierung erfolgt durch einen exakten String-Präfixabgleich und lässt keine Verwendung von Platzhaltern zu.

Sie müssen auch alle URI-Präfixe angeben, von denen Anhänge in Ihrem Add-on zulässig sind. Diese Funktion erhöht die Sicherheit, da Anhänge aus nicht autorisierten Quellen verhindert werden.

Legen Sie beide Werte auf der Seite App-Konfiguration des Marketplace SDK für Ihr Google Cloud-Projekt fest.

Testkonten

Erstellen Sie Testkonten in Ihrer Demodomäne, um das korrekte Verhalten Ihres privaten Add-ons zu überprüfen. Sie benötigen zwei Schülerkonten, um das Wechseln zwischen Schülern im iframe „Schülerarbeiten überprüfen“ zu testen.

Vorgeschlagene Testkonten:

• Frau Schmitt, frau.schmitt@<Ihre Demodomäne>
• Sam Student, sam.student@<your demo domain>
• Sally Student, sally.student@<your demo domain>

So erstellen Sie ein neues Testkonto:

1. Melden Sie sich in der Admin-Konsole an.
2. Gehen Sie zu Nutzer.
3. Klicken Sie auf Neuen Nutzer hinzufügen (siehe Abbildung 1).
4. Geben Sie die Daten des Nutzers ein und weisen Sie die entsprechenden Rollen zu.

Abbildung 1: Position des Links Neuen Nutzer hinzufügen in der Admin-Konsole.

So erstellen Sie eine neue Testgruppe:

1. Melden Sie sich in der Admin-Konsole an.
2. Rufen Sie Gruppen auf.
3. Klicken Sie auf Gruppe erstellen (siehe Abbildung 2).
4. Geben Sie die Mitglieder und Inhaber der Gruppe ein.

Abbildung 2 Position des Links Gruppe erstellen in der Admin-Konsole.