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.

Dieser Artikel bietet eine konzeptionelle Übersicht sowie eine einfache Anleitung zum Einstieg in Push-Benachrichtigungen.

Übersicht über Classroom-Push-Benachrichtigungen

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

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 der 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 Drittanbieter-App abonnieren kann. Beispiel: „Teilnehmerliste für Kurs 1234 ändern“.
Eine Registrierung ist eine Anweisung an die Classroom API, mit der Sie Benachrichtigungen von einem bestimmten Feed an ein Ziel senden können.

Nachdem Sie eine Registrierung für einen Feed erstellt haben, erhält das Cloud Pub/Sub-Thema dieser Registrierung Benachrichtigungen von diesem Feed, bis es abläuft. Ihre Registrierung dauert eine Woche. Sie können sie jedoch jederzeit 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 bei der Registrierung angegebenen Anmeldedaten aufrufen können. Wenn der Nutzer beispielsweise die Berechtigung für Ihre Anwendung aufhebt 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 Teilnehmerlisten-Änderungen an einem Domainfeed. Dadurch werden Benachrichtigungen angezeigt, wenn Schüler und Lehrer an Kursen in dieser Domain teilnehmen und diese verlassen.
Für jeden Kurs gibt es einen Teilnehmerlistenänderungen für den Kursfeed, der Benachrichtigungen anzeigt, wenn Schüler und Lehrkräfte Kurse in diesem Kurs betreten und verlassen.
Für jeden Kurs gibt es einen Kurswechsel für den Kurs. Dadurch werden Benachrichtigungen eingeblendet, wenn in diesem Kurs Aufgaben 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 erhalten oder über einen Aboendpunkt abfragen.

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

Prüfen Sie, ob die Cloud Pub/Sub-Voraussetzungen erfüllt sind.
Cloud Pub/Sub-Client einrichten
Sehen Sie sich die Cloud Pub/Sub-Preise an und aktivieren Sie die Abrechnung für Ihr Developer Console-Projekt.
Erstellen Sie ein Cloud Pub/Sub-Thema in der Developer Console (am einfachsten), über das Befehlszeilentool (für die einfache programmatische Verwendung) oder mit der Cloud Pub/Sub API. Beachten Sie, dass Cloud Pub/Sub nur eine begrenzte Anzahl von Themen zulässt. Wenn also ein Thema alle Benachrichtigungen erhält, können Sie keine Skalierungsprobleme vermeiden, wenn Ihre Anwendung beliebter 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 können, müssen Sie dem Dienstkonto Push-Benachrichtigungen (classroom-notifications@system.gserviceaccount.com) die Berechtigung erteilen, in Ihrem Thema zu veröffentlichen.

HINWEIS: Wenn Sie dem Dienstkonto für Push-Benachrichtigungen die Berechtigung zur Veröffentlichung in Ihrem Cloud Pub/Sub-Thema erteilen, können Nutzer, die Anfragen von Ihrem Developer Console-Projekt aus stellen können, feststellen, ob es vorhanden ist, und sich dafür 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 Push-Benachrichtigungen aus einem anderen Entwicklerkonsolenprojekt registrieren.

Anwendung für Benachrichtigungen registrieren

Sobald Sie ein Thema haben, in dem das Classroom API-Push-Benachrichtigungsdienstkonto veröffentlichen kann, können Sie sich mit der Methode registrations.create() für Benachrichtigungen registrieren. Die Methode registrations.create() prüft, ob das bereitgestellte 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 Veröffentlichungsberechtigung für dieses Thema erteilt haben.

Autorisierung

Wie alle Aufrufe der Classroom API müssen die 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 die Bereiche enthalten, die zum Aufrufen der Daten erforderlich sind, über die Benachrichtigungen gesendet werden.

Bei Änderungsfeeds für die Teilnehmerliste bedeutet dies den Umfang der 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 die Änderungsfeeds des Kurses bedeutet dies, dass die „Schüler/Studenten“-Versionen des Kursarbeitsbereichs oder idealerweise die schreibgeschützte Variante (https://www.googleapis.com/auth/classroom.coursework.students.readonly oder https://www.googleapis.com/auth/classroom.coursework.students) sind.

Damit Benachrichtigungen zugestellt werden können, muss die Anwendung eine OAuth-Zustimmung des autorisierten Nutzers mit den erforderlichen Bereichen beibehalten. Wenn der Nutzer die Verbindung trennt, werden keine Benachrichtigungen mehr angezeigt. Beachten Sie, dass die domainweite Delegierung von Befugnissen für diesen Zweck derzeit nicht unterstützt wird. Wenn Sie versuchen, sich nur mit einer domainweiten delegierten Zertifizierungsstelle für Benachrichtigungen zu registrieren, wird der Fehler „@MissingGrant“ angezeigt.

Benachrichtigungen erhalten

Benachrichtigungen sind mit JSON codiert und enthalten:

Der Name der Sammlung, die die geänderte Ressource enthält. Bei Benachrichtigungen zu Änderungen der Teilnehmerliste ist dies entweder courses.students oder courses.teachers. Bei Kursänderungen sind das entweder courses.courseWork oder courses.courseWork.studentSubmissions.
IDs der geänderten Ressource in einer Zuordnung. Diese Zuordnung ist so konzipiert, dass die Argumente der Methode get der entsprechenden Ressource zugeordnet werden. Für Benachrichtigungen über Änderungen der Teilnehmerlisten werden die Felder courseId und userId automatisch ausgefüllt und können an courses.students.get() oder courses.teachers.get() unverändert gesendet werden. Änderungen an der Sammlung „courses.courseWork.get.course1.course.course_course“ werden an courseIdcourses.course.course.course

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 für die Registrierung enthält, die die Benachrichtigung ausgelöst hat. Diese kann mit registrations.delete() verwendet werden, um die Registrierung von Benachrichtigungen aufzuheben.