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.

Push-Benachrichtigungen in der Classroom API

Sie können die Methoden in der Sammlung Registrations verwenden, um Benachrichtigungen zu erhalten, wenn sich Daten in Classroom ändern.

In diesem Artikel erhalten Sie einen konzeptionellen Überblick sowie eine einfache Anleitung dazu, wie Sie Push-Benachrichtigungen erhalten können.

Übersicht über Classroom-Push-Benachrichtigungen

Mit der Push-Benachrichtigungsfunktion der Classroom API können Anwendungen, die die Classroom API verwenden, Benachrichtigungen abonnieren, wenn sich Daten in Classroom ändern. Benachrichtigungen werden in der Regel innerhalb weniger Minuten nach der Änderung an ein Cloud Pub/Sub-Thema gesendet.

Wenn Sie Push-Benachrichtigungen erhalten möchten, müssen Sie ein Cloud Pub/Sub-Thema einrichten und den Namen dieses Themas angeben, wenn Sie eine Registrierung für den entsprechenden Feed mit Benachrichtigungen erstellen.

Im Folgenden finden Sie Definitionen der wichtigsten Konzepte, die in dieser Dokumentation verwendet werden:

Ein Ziel ist ein Ort, an den Benachrichtigungen gesendet werden.
Ein Feed ist eine Art von Benachrichtigungen, die eine Drittanbieteranwendung abonnieren kann. Beispiel: „Änderungen am Teilnehmerverzeichnis für Kurs 1234“
Eine Registrierung ist eine Anweisung an die Classroom API, Benachrichtigungen aus einem bestimmten Feed an ein Ziel zu senden.

Nachdem Sie eine Registrierung für einen Feed erstellt haben, erhält das Cloud Pub/Sub-Thema dieser Registrierung Benachrichtigungen von diesem Feed, bis er abläuft. Ihre Registrierung gilt für eine Woche. Sie können sie aber jederzeit vor Ablauf verlängern, indem Sie eine identische Anfrage an registrations.create() senden.

Ihr Cloud Pub/Sub-Thema erhält nur Benachrichtigungen zu Ressourcen, die Sie mit den Anmeldedaten aufrufen können, die Sie beim Erstellen einer Registrierung angegeben haben. Wenn der Nutzer beispielsweise Ihrer Anwendung die Berechtigung widerruft oder als Lehrkraft entfernt wird, werden Benachrichtigungen länger zugestellt.

Feedarten

Die Classroom API bietet derzeit drei Arten von Feeds:

Für jede Domain gibt es einen Feed für Teilnehmerlistenänderungen für die Domain. Dadurch werden Benachrichtigungen angezeigt, wenn Schüler, Studenten und Lehrkräfte Kursen in dieser Domain beitreten oder sie verlassen.
Für jeden Kurs gibt es einen Feed für Teilnehmerlistenänderungen. Dadurch werden Benachrichtigungen angezeigt, wenn Schüler, Studenten und Lehrkräfte einem Kurs beitreten oder ihn verlassen.
Für jeden Kurs gibt es einen Feed für Änderungen der Kursarbeiten für den Kurs. Dadurch werden Benachrichtigungen angezeigt, wenn in diesem Kurs Kursarbeiten oder von Schülern/Studenten eingereichte Objekte erstellt oder geändert werden.

Cloud Pub/Sub-Thema einrichten

Benachrichtigungen werden an Cloud Pub/Sub-Themen gesendet. Über Cloud Pub/Sub können Sie Benachrichtigungen über einen Web-Hook oder durch Abfragen eines Aboendpunkts erhalten.

So richten Sie ein Cloud Pub/Sub-Thema ein:

Achten Sie darauf, dass Sie die Voraussetzungen für Cloud Pub/Sub erfüllen.
Richte einen Cloud Pub/Sub-Client ein.
Sehen Sie sich die Preise für Cloud Pub/Sub an und aktivieren Sie die Abrechnung für Ihr Developer Console-Projekt.
Sie können ein Cloud Pub/Sub-Thema in der Entwicklerkonsole (am einfachsten), über das Befehlszeilentool (für die einfache programmatische Verwendung) oder mit der Cloud Pub/Sub API erstellen. Beachten Sie, dass Cloud Pub/Sub nur eine begrenzte Anzahl von Themen zulässt. Wenn Sie also alle Ihre Benachrichtigungen an ein Thema erhalten, vermeiden Sie Skalierungsprobleme, wenn Ihre Anwendung beliebt wird.
Erstellen Sie ein Abo in Cloud Pub/Sub, um Cloud Pub/Sub mitzuteilen, wie Ihre Benachrichtigungen zugestellt werden sollen.
Bevor Sie sich für Push-Benachrichtigungen registrieren, müssen Sie dem Dienstkonto für Push-Benachrichtigungen (classroom-notifications@system.gserviceaccount.com) die Berechtigung zum Veröffentlichen in Ihrem Thema erteilen.

HINWEIS: Wenn Sie dem Dienstkonto für Push-Benachrichtigungen die Berechtigung zum Veröffentlichen in Ihrem Cloud Pub/Sub-Thema gewähren, können Nutzer, die Anfragen über Ihr Developer Console-Projekt stellen können, feststellen, dass es existiert, und sich für Benachrichtigungen dazu registrieren. Viele Anwendungen speichern OAuth-Client-IDs auf der Clientseite. Daher können Endnutzer möglicherweise Anfragen über Ihr Entwicklerkonsolenprojekt stellen. Wenn dies auf Sie zutrifft und Sie Bedenken haben, dass Endnutzer unerwünschte Benachrichtigungen an Ihr Cloud Pub/Sub-Thema senden oder die Namen der Cloud Pub/Sub-Themen kennen, die Sie für Push-Benachrichtigungen verwenden, sollten Sie sich für Push-Benachrichtigungen von einem anderen Entwicklerkonsolenprojekt registrieren.

Anwendung für Benachrichtigungen registrieren

Sobald Sie ein Thema haben, für das das Dienstkonto für Push-Benachrichtigungen der Classroom API veröffentlichen kann, können Sie sich mit der Methode registrations.create() für Benachrichtigungen registrieren. Mit der registrations.create()-Methode wird geprüft, ob das angegebene Cloud Pub/Sub-Thema vom Dienstkonto für Push-Benachrichtigungen erreicht werden kann. Die Methode schlägt fehl, wenn das Dienstkonto für Push-Benachrichtigungen das Thema nicht erreichen kann. Das ist beispielsweise der Fall, wenn das Thema nicht existiert oder Sie ihm keine Veröffentlichungsberechtigung für dieses Thema erteilt haben.

Autorisierung

Wie alle Aufrufe der Classroom API müssen auch Aufrufe von registrations.create() mit einem Autorisierungstoken autorisiert werden. Dieses Authentifizierungstoken muss den Bereich für Push-Benachrichtigungen (https://www.googleapis.com/auth/classroom.push-notifications) und alle erforderlichen Bereiche zum Ansehen der Daten enthalten, über die Benachrichtigungen gesendet werden.

Bei Feeds zur Änderung der Teilnehmerliste bedeutet dies den Bereich „Rosters“ (Teilnehmerliste) oder (idealerweise) seine schreibgeschützte Variante (https://www.googleapis.com/auth/classroom.rosters.readonly oder https://www.googleapis.com/auth/classroom.rosters).
Bei Feeds mit Kursarbeiten bedeutet das die Versionen „Schüler/Studenten“ des Kursarbeitsumfangs oder (idealerweise) die schreibgeschützte Variante (https://www.googleapis.com/auth/classroom.coursework.students.readonly oder https://www.googleapis.com/auth/classroom.coursework.students).

Damit Benachrichtigungen zugestellt werden können, muss die Anwendung eine OAuth-Berechtigung vom autorisierten Nutzer mit den erforderlichen Bereichen erhalten. Wenn der Nutzer die Verbindung zur App trennt, werden keine Benachrichtigungen mehr gesendet. Die domainweite Delegierung von Berechtigungen wird derzeit nicht unterstützt. Wenn Sie versuchen, sich nur mit einer domainweiten delegierten Autorität für Benachrichtigungen zu registrieren, erhalten Sie den Fehler @MissingGrant.

Benachrichtigungen erhalten

Benachrichtigungen sind mit JSON codiert und enthalten Folgendes:

Der Name der Sammlung, die die geänderte Ressource enthält. Bei Benachrichtigungen zu Kaderänderungen ist dies entweder courses.students oder courses.teachers. Bei Änderungen an Kursarbeiten ist dies entweder courses.courseWork oder courses.courseWork.studentSubmissions.
IDs für die geänderte Ressource in einer Karte. Mit dieser Zuordnung werden die Argumente der get-Methode der entsprechenden Ressource zugeordnet. Bei Benachrichtigungen zu Änderungen an der Kursliste werden die Felder courseId und userId ausgefüllt und können unverändert an courses.students.get() oder courses.teachers.get() gesendet werden. Bei Änderungen an der Sammlung „courses.courseWork“ werden die Felder courseId und id ausgefüllt und können unverändert an courses.courseWork.get() gesendet werden. Bei Änderungen an der Sammlung „courses.courseWork.studentSubmissions“ werden die Felder courseId, courseWorkId und id ausgefüllt und können unverändert an courses.courseWork.studentSubmissions.get() gesendet werden.

Das folgende Code-Snippet zeigt eine Beispielbenachrichtigung:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

Benachrichtigungen haben außerdem ein registrationId-Nachrichtenattribut, das die ID der Registrierung enthält, die die Benachrichtigung ausgelöst hat. Diese ID kann mit registrations.delete() verwendet werden, um sich von Benachrichtigungen abzumelden.