Push-Benachrichtigungen in der Classroom API

Mit den Methoden der Registrations Sammlung können Sie Benachrichtigungen erhalten, wenn sich Daten in Classroom ändern.

In diesem Artikel finden Sie eine konzeptionelle Übersicht sowie eine einfache Anleitung, wie Sie Push-Benachrichtigungen erhalten.

Übersicht über Classroom-Push-Benachrichtigungen

Mit der Funktion für Push-Benachrichtigungen 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 von 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 von einer Drittanbieteranwendung abonniert werden kann. Beispiel: „Änderungen an der Teilnehmerliste für Kurs 1234“.
• Eine Registrierung ist eine Anweisung an die Classroom API, Benachrichtigungen aus einem bestimmten Feed an ein bestimmtes Ziel zu senden.

Sobald Sie eine Registrierung für einen Feed erstellt haben, werden Benachrichtigungen aus diesem Feed an das Cloud Pub/Sub-Thema dieser Registrierung gesendet, bis die Registrierung abläuft. Ihre Registrierung ist eine Woche lang gültig. Sie können sie jedoch 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 angeben. Wenn der Nutzer beispielsweise die Berechtigung für Ihre Anwendung widerruft oder als Lehrkraft entfernt wird, werden keine Benachrichtigungen mehr gesendet.

Feedarten

Die Classroom API bietet drei Arten von Feeds:

• Jede Domain hat einen Feed Änderungen an der Teilnehmerliste für die Domain , der Benachrichtigungen sendet, wenn Schüler/Studenten und Lehrkräfte Kursen in dieser Domain beitreten oder sie verlassen.
• Jeder Kurs hat einen Feed Änderungen an der Teilnehmerliste für den Kurs , der Benachrichtigungen sendet, wenn Schüler/Studenten und Lehrkräfte Kursen in diesem Kurs beitreten oder sie verlassen.
• Jeder Kurs hat einen Feed Änderungen an Kursaufgaben für den Kurs , der Benachrichtigungen sendet, wenn in diesem Kurs Kursaufgaben oder von Schülern/Studenten eingereichte Aufgaben erstellt oder geändert werden.

Hinweis: Wir sind uns eines Problems bewusst, bei dem keine Benachrichtigungen für Änderungen in Kursen gesendet werden, deren Inhaber nicht Teil einer Google Workspace for Education-Domain ist. Wenn Sie mit Kursen arbeiten, die nicht mit einer Google Workspace for Education-Domain verknüpft sind, funktionieren Benachrichtigungen für den feedType COURSE_ROSTER_CHANGES möglicherweise nicht.

Cloud Pub/Sub-Thema einrichten

Benachrichtigungen werden an Cloud Pub/Sub-Themen gesendet. Über Cloud Pub/Sub können Sie Benachrichtigungen über einen Webhook oder durch Abrufen eines Abo-Endpunkts erhalten.

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

1. Prüfen Sie, ob Sie die Voraussetzungen für Cloud Pub/Sub erfüllen.
2. Richten Sie einen Cloud Pub/Sub-Client ein.
3. Prüfen Sie die Cloud Pub/Sub-Preise, und aktivieren Sie die Abrechnung für Ihr Developer Console-Projekt.

4. Erstellen Sie ein Cloud Pub/Sub-Thema in der Developer Console (am einfachsten), über das Befehlszeilen tool (für die einfache programmatische Verwendung) oder mit der Cloud Pub/Sub API. Cloud Pub/Sub lässt nur eine begrenzte Anzahl von Themen zu. Wenn Sie ein Thema verwenden, um alle Benachrichtigungen zu erhalten, vermeiden Sie Skalierungsprobleme, falls Ihre Anwendung beliebt wird.

5. Erstellen Sie ein Abo in Cloud Pub/Sub, um Cloud Pub/Sub mitzuteilen, wie Benachrichtigungen gesendet werden sollen.

6. Bevor Sie sich für Push-Benachrichtigungen registrieren, müssen Sie dem Dienstkonto für Push-Benachrichtigungen ([e-mail]) 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 erteilen, können Nutzer, die Anfragen von Ihrem Developer Console-Projekt aus senden können, feststellen, dass es vorhanden ist, und sich für Benachrichtigungen registrieren. Viele Anwendungen speichern OAuth-Client-IDs auf der Clientseite, sodass Endnutzer möglicherweise Anfragen von Ihrem Developer Console-Projekt aus senden können. Wenn dies auf Sie zutrifft und Sie Bedenken haben, dass Endnutzer unerwünschte Benachrichtigungen an Ihr Cloud Pub/Sub-Thema senden oder die Namen von Cloud Pub/Sub-Themen kennen, die Sie für Push-Benachrichtigungen verwenden, sollten Sie sich für Push-Benachrichtigungen von einem anderen Developer Console-Projekt aus registrieren.

Anwendung für Benachrichtigungen registrieren

Sobald Sie ein Thema haben, in dem das Dienstkonto für Push-Benachrichtigungen der Classroom API veröffentlichen kann, können Sie sich mit der registrations.create() Methode für Benachrichtigungen registrieren. Die Methode registrations.create() prü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, z. B. wenn das Thema nicht vorhanden ist oder Sie ihm keine Berechtigung zum Veröffentlichen in diesem Thema erteilt haben.

Autorisierung

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

• Für Feeds mit Änderungen an der Teilnehmerliste bedeutet dies den Bereich „Teilnehmerlisten“ oder (idealerweise) die schreibgeschützte Variante (https://www.googleapis.com/auth/classroom.rosters.readonly oder https://www.googleapis.com/auth/classroom.rosters).
• Für Feeds mit Änderungen an Kursaufgaben bedeutet dies die Versionen des Bereichs „Kursaufgaben“ für Schüler/Studenten 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 gesendet werden können, muss die Anwendung eine OAuth-Berechtigung vom autorisierten Nutzer mit den erforderlichen Bereichen beibehalten. Wenn der Nutzer die Verbindung zur Anwendung trennt, werden keine Benachrichtigungen mehr gesendet. Derzeit wird die domainweite Berechtigungsübertragung für diesen Zweck nicht unterstützt. Wenn Sie versuchen, sich nur mit der domainweiten Berechtigungsübertragung für Benachrichtigungen zu registrieren, erhalten Sie den Fehler @MissingGrant.

Benachrichtigungen erhalten

Benachrichtigungen werden mit JSON codiert und enthalten Folgendes:

• Der Name der Sammlung, die die geänderte Ressource enthält. Bei Benachrichtigungen zu Änderungen an der Teilnehmerliste ist dies entweder courses.students oder courses.teachers. Bei Änderungen an Kursaufgaben ist dies entweder courses.courseWork oder courses.courseWork.studentSubmissions.
• Kennungen für die geänderte Ressource in einer Zuordnung. Diese Zuordnung entspricht den Argumenten der Methode get der entsprechenden Ressource. Bei Benachrichtigungen zu Änderungen an der Teilnehmerliste werden die Felder courseId und userId ausgefüllt und können unverändert an courses.students.get() oder courses.teachers.get()gesendet werden. Änderungen an der Sammlung „courses.courseWork“ enthalten die Felder courseId und id, die unverändert an courses.courseWork.get()gesendet werden können. Änderungen an der Sammlung „courses.courseWork.studentSubmissions“ enthalten die Felder courseId, courseWorkId und id, die unverändert an courses.courseWork.studentSubmissions.get()gesendet werden können.

Das folgende Code-Snippet zeigt eine Beispielbenachrichtigung:

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

Benachrichtigungen haben auch ein registrationId Nachrichtenattribut mit der Kennung für die Registrierung, die die Benachrichtigung ausgelöst hat. Dieses Attribut kann mit registrations.delete() verwendet werden, um die Registrierung für Benachrichtigungen aufzuheben.