Push-Benachrichtigungen in der Classroom API

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

In diesem Artikel finden Sie eine konzeptionelle Übersicht 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 Benachrichtigungsfeed 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 können. Beispiel: „Kurs 1234: Änderungen an der Teilnehmerliste“.
  • 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, empfängt das Cloud Pub/Sub-Thema dieser Registrierung Benachrichtigungen von diesem Feed, bis die Registrierung abläuft. Ihre Registrierung dauert eine Woche. Sie können sie jedoch jederzeit vor Ablauf verlängern, indem Sie eine identische Anfrage an registrations.create() senden.

Ihr Cloud Pub/Sub-Thema empfängt nur Benachrichtigungen zu Ressourcen, die Sie mit den Anmeldedaten ansehen 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 für Änderungen an der Kursliste für die Domain, der Benachrichtigungen enthält, wenn Schüler/Studenten und Lehrkräfte Kursen in dieser Domain beitreten oder sie verlassen.
  • Jeder Kurs hat einen Feed roster changes for course (Kurslistenänderungen), in dem Benachrichtigungen angezeigt werden, wenn Schüler/Studenten und Lehrkräfte dem Kurs beitreten oder ihn verlassen.
  • Jeder Kurs hat einen Feed course work changes for course, in dem Benachrichtigungen angezeigt werden, wenn in diesem Kurs Kursarbeiten oder Objekte für Schüler-/Studentenaufgaben 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 Abrufen eines Abo-Endpunkts erhalten.

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

  1. Achten Sie darauf, dass Sie die Cloud Pub/Sub-Voraussetzungen erfüllen.
  2. Cloud Pub/Sub-Client einrichten
  3. Sehen Sie sich die Cloud Pub/Sub-Preise an 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 Befehlszeilentool (für die einfache programmatische Verwendung) oder mit der Cloud Pub/Sub API. Cloud Pub/Sub erlaubt nur eine begrenzte Anzahl von Themen. Wenn Sie also ein Thema verwenden, um alle Ihre Benachrichtigungen zu empfangen, vermeiden Sie Skalierungsprobleme, falls Ihre Anwendung beliebt wird.

  5. Abo in Cloud Pub/Sub erstellen, um Cloud Pub/Sub mitzuteilen, wie 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.

Anwendung für Benachrichtigungen registrieren

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

Autorisierung

Wie alle Aufrufe der Classroom API registrations.create() müssen 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 Aufrufen der Daten dazu erforderlich sind, welche Benachrichtigungen gesendet werden.

  • Für Feeds für Dienstplanänderungen bedeutet das den Bereich „Dienstpläne“ oder (idealerweise) die schreibgeschützte Variante (https://www.googleapis.com/auth/classroom.rosters.readonly oder https://www.googleapis.com/auth/classroom.rosters).
  • Für Änderungsfeeds für Kursarbeiten bedeutet das, 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) verwendet werden.

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

Benachrichtigungen erhalten

Benachrichtigungen sind mit JSON codiert und enthalten:

  • 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 Kursaufgaben ist dies entweder courses.courseWork oder courses.courseWork.studentSubmissions.
  • Kennungen für die Ressource, die sich geändert hat, in einer Karte. Diese Karte soll die Argumente der get-Methode der entsprechenden Ressource abgleichen. Bei Benachrichtigungen über Ä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, das die Kennung für die Registrierung enthält, die die Benachrichtigung ausgelöst hat. Dieses Attribut kann mit registrations.delete() verwendet werden, um die Registrierung für Benachrichtigungen aufzuheben.