Mit den Methoden der Registrations-Sammlung können Sie Benachrichtigungen erhalten, wenn sich Daten in Classroom ändern.
Dieser Artikel bietet eine konzeptionelle Übersicht sowie einfache Anweisungen zum Erhalt von Push-Benachrichtigungen.
Push-Benachrichtigungen in Classroom
Mit der Classroom API-Push-Benachrichtigungsfunktion können Anwendungen, die die Classroom API verwenden, Benachrichtigungen abonnieren, wenn sich Daten in Classroom ändern. Benachrichtigungen werden normalerweise 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 für Benachrichtigungen erstellen.
Im Folgenden finden Sie Definitionen der Schlüsselkonzepte, die in dieser Dokumentation verwendet werden:
- Ein Ziel ist ein Ort, an den Benachrichtigungen gesendet werden.
- Ein Feed ist ein Benachrichtigungstyp, den eine Drittanbieter-App abonnieren kann. Beispiel: „Teilnehmerliste ändert sich für Kurs 1234“.
- Eine Registrierung ist eine Anweisung an die Classroom API, um Benachrichtigungen von 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 eine Woche. Sie können sie jedoch jederzeit verlängern, bevor sie abläuft. Senden Sie dazu eine identische Anfrage an registrations.create().
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 Ihrer Anwendung widerruft oder als Lehrkraft entfernt wird, werden die Benachrichtigungen länger gesendet.
Feedarten
Die Classroom API bietet derzeit drei Feedtypen:
- Für jede Domain gibt es einen Feed mit Teilnehmerlistenänderungen für die Domain, der Benachrichtigungen enthält, wenn Schüler, Studenten und Lehrkräfte an Kursen in dieser Domain teilnehmen oder diese verlassen.
- Für jeden Kurs gibt es einen Feed mit Änderungen der Teilnehmerliste für den Kurs, in dem Benachrichtigungen eingeblendet werden, wenn Lernende und Lehrkräfte an Kursen in diesem Kurs teilnehmen oder diese verlassen.
- Für jeden Kurs gibt es einen Feed für Änderungen an Kursarbeiten am Kurs. In diesem werden Benachrichtigungen eingeblendet, wenn in diesem Kurs Kursarbeiten oder eingereichte Objekte von Schülern/Studenten erstellt oder geändert werden.
Cloud Pub/Sub-Thema einrichten
Benachrichtigungen werden an Cloud Pub/Sub-Themen gesendet. In 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:
- Prüfen Sie, ob die Cloud Pub/Sub-Voraussetzungen erfüllt sind.
- Cloud Pub/Sub-Client einrichten
- Prüfen Sie die Cloud Pub/Sub-Preise 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 mithilfe der Cloud Pub/Sub API. Beachten Sie, dass Cloud Pub/Sub nur eine begrenzte Anzahl von Themen zulässt. Wenn Sie also ein Thema zum Empfang aller Benachrichtigungen verwenden, vermeiden Sie Skalierungsprobleme, wenn Ihre Anwendung beliebt wird.
Erstellen Sie ein Abo in Cloud Pub/Sub, um Cloud Pub/Sub mitzuteilen, wie Ihre Benachrichtigungen gesendet werden sollen.
Bevor Sie sich für Push-Benachrichtigungen registrieren, müssen Sie dem Dienstkonto für Push-Benachrichtigungen die Berechtigung
classroom-notifications@system.gserviceaccount.comzum Veröffentlichen in Ihrem Thema erteilen.
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 senden können, feststellen, dass es vorhanden ist, und sich für Benachrichtigungen an das Thema registrieren. Viele Anwendungen speichern OAuth-Client-IDs auf Clientseite, sodass Endnutzer möglicherweise Anfragen über Ihr Developer Console-Projekt senden können. Wenn dies auf Sie zutrifft und Sie befürchten, 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 über ein anderes Developer Console-Projekt für Push-Benachrichtigungen registrieren.
Anwendung für Benachrichtigungen registrieren
Sobald Sie ein Thema haben, zu dem 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. Die Methode registrations.create() prüft, ob das angegebene Cloud Pub/Sub-Thema über das 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 existiert oder Sie ihm keine Veröffentlichungsberechtigung für dieses Thema gewährt 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 „Push-Benachrichtigungen“ (https://www.googleapis.com/auth/classroom.push-notifications) und alle Bereiche enthalten, die zum Aufrufen der Daten darüber, welche Benachrichtigungen gesendet werden, erforderlich sind.
- Für Teilnehmerlisten-Änderungsfeeds ist dies der Bereich der Teilnehmerliste oder (idealerweise) die schreibgeschützte Variante (
https://www.googleapis.com/auth/classroom.rosters.readonlyoderhttps://www.googleapis.com/auth/classroom.rosters). - Bei Feeds zu Kursänderungen bezieht sich dies auf die Versionen des Umfangs der Kursaufgabe oder (idealerweise) die schreibgeschützte Variante (
https://www.googleapis.com/auth/classroom.coursework.students.readonlyoderhttps://www.googleapis.com/auth/classroom.coursework.students).
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 zur Anwendung trennt, werden keine Benachrichtigungen mehr gesendet. Beachten Sie, dass die domainweite Delegierung von Befugnissen für diesen Zweck derzeit nicht unterstützt wird. Wenn Sie versuchen, sich nur mit domainweiten delegierten Befugnissen für Benachrichtigungen zu registrieren, wird der Fehler @MissingGrant angezeigt.
Benachrichtigungen erhalten
Benachrichtigungen sind mit JSON codiert und enthalten:
- Der Name der Sammlung mit der geänderten Ressource. Für Benachrichtigungen über Teilnehmerlistenänderungen ist dies entweder
courses.studentsodercourses.teachers. Bei Änderungen an Kursarbeiten ist dies entwedercourses.courseWorkodercourses.courseWork.studentSubmissions. - Kennzeichnungen für die geänderte Ressource in einer Karte. Diese Zuordnung ist so konzipiert, dass die Argumente der Methode
getder entsprechenden Ressource zugeordnet werden. Bei Benachrichtigungen zu Änderungen der Teilnehmerliste werden die FeldercourseIdunduserIdausgefüllt und unverändert an courses.students.get() oder courses.teachers.get() gesendet. Entsprechend enthalten Änderungen an der Sammlung „courses.courseWork“courseId- undid-Felder, die unverändert an die Felder courses.courseWork.get() undcourseIdSubmission.idcourseWorkIdcourses.courseWork.studentSubmissions.get()
Das folgende Code-Snippet zeigt eine Beispielbenachrichtigung:
{
"collection": "courses.students",
"eventType": "CREATED",
"resourceId": {
"courseId": "12345",
"userId": "45678"
}
}
Benachrichtigungen haben auch ein Nachrichtenattribut registrationId, 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 von Benachrichtigungen aufzuheben.