Push-Benachrichtigungen in der Classroom API

Mit den Methoden der Sammlung Registrations können Sie Benachrichtigungen 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.

Push-Benachrichtigungen in Classroom

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 Benachrichtigung, die eine Drittanbieter-App 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 die Registrierung 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 die Berechtigung für Ihre App widerruft oder als Lehrkraft entfernt wird, werden keine Benachrichtigungen mehr gesendet.

Feedarten

Die Classroom API bietet derzeit drei Arten von Feeds:

  • Jede Domain hat einen Feed Personenliste – Änderungen für Domain, über den Benachrichtigungen angezeigt werden, wenn Schüler/Studenten und Lehrkräfte Kursen in dieser Domain beitreten oder sie verlassen.
  • Jeder Kurs hat einen Feed mit Änderungen am Teilnehmerverzeichnis für den Kurs, über den Benachrichtigungen angezeigt werden, wenn Schüler, Studenten und Lehrkräfte Kurse in diesem Kurs betreten oder verlassen.
  • Jeder Kurs hat einen Feed vom Typ Änderungen an Kursarbeiten für Kurs, in dem Benachrichtigungen angezeigt werden, wenn Kursarbeiten oder von Schülern/Studenten eingereichte Objekte in diesem Kurs 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 Webhook oder durch Abfragen eines Aboendpunkts erhalten.

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

  1. Achten Sie darauf, dass Sie die Voraussetzungen für Cloud Pub/Sub erfüllen.
  2. Richte einen Cloud Pub/Sub-Client ein.
  3. Sehen Sie sich die Preise für Cloud Pub/Sub an und aktivieren Sie die Abrechnung für Ihr Developer Console-Projekt.

  4. 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. Hinweis: In Cloud Pub/Sub ist nur eine begrenzte Anzahl von Themen zulässig. Wenn Sie also ein Thema verwenden, um alle Benachrichtigungen zu erhalten, treten keine Skalierungsprobleme auf, wenn Ihre Anwendung populär wird.

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

  6. 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 Developer Console-Projekt 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 Aufrufe von registrations.create() mit einem Autorisierungstoken autorisiert werden. Dieses Authentifizierungstoken muss den Bereich „Push-Benachrichtigungen“ (https://www.googleapis.com/auth/classroom.push-notifications) und alle Bereiche enthalten, die zum Ansehen der Daten erforderlich sind, die über gesendeten Benachrichtigungen enthalten sind.

  • Bei Feeds mit Kaderänderungen bedeutet das den Umfang „Kader“ oder (idealerweise) die 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 gesendet werden können, muss die Anwendung eine OAuth-Berechtigung des autorisierten Nutzers mit den erforderlichen Bereichen haben. Wenn der Nutzer die Verbindung zur Anwendung 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 das Nachrichtenattribut registrationId, das die Kennung für die Registrierung enthält, die die Benachrichtigung verursacht hat. Es kann mit registrations.delete() verwendet werden, um die Registrierung für Benachrichtigungen aufzuheben.