Lehrkräfte, die sowohl Classroom als auch Drittanbietertools verwenden, stehen vor der Herausforderung, ihre Kurse und Teilnehmerlisten auf mehreren Plattformen einzurichten. Das kann manuell erfolgen, entweder durch CSV-Uploads oder durch die Eingabe von E‑Mail-Adressen einzeln. Mit der Classroom API können Drittanbietertools jedoch die Arbeitsbelastung von Lehrkräften verringern, indem sie in den häufigsten Anwendungsfall der API integriert werden: Klassenlistenimport.
Durch den Import von Teilnehmerlisten können Drittanbieterplattformen die Metadaten, Lehrkräfte und Lernenden eines Kurses kursweise mit Lehrkraft- oder Administratorberechtigungen abrufen. Lehrkräfte können Details zu den Kursen abrufen, die sie unterrichten, während Administratoren Zugriff auf Details zu allen Kursen in einer gesamten Domain haben. Diese Flexibilität ermöglicht es Entwicklern, Classroom-Klassenlisten nahtlos in ihre Plattform zu integrieren, entweder auf der Ebene einzelner Lehrkräfte oder für eine gesamte Domain mit Administratoranmeldedaten.
Bevor wir uns die technischen Details einer Integration für den Import von Teilnehmerlisten ansehen, wollen wir uns zuerst einen Beispielworkflow ansehen:
In der Drittanbieteranwendung wählt eine Lehrkraft die Option zum Importieren eines Classroom-Kurses aus.
Die Drittanbieteranwendung ruft die Methode
courses.listüber die Classroom API auf. Dadurch wird eine JSON-Antwort mit allen Kursen des Lehrers zurückgegeben.Anhand der JSON-Antwort zeigt die Drittanbieteranwendung die Titel der Kurse des Lehrers an, damit er einen auswählen kann. Die Anwendung muss die Kurs-IDs im Blick behalten, um mit dem nächsten Schritt fortzufahren.
Mit der ausgewählten Kurs-ID ruft die Drittanbieteranwendung die Methoden
students.listundteachers.listauf und zeigt alle Namen auf ihrer Website an, damit Lehrkräfte sie für den Import bestätigen können.Anhand der E‑Mail-Adressen, die in den JSON-Antworten
students.listundteachers.listzurückgegeben werden, lädt die Drittanbieteranwendung die Nutzer ein, dem neu importierten Kurs auf ihrer Plattform beizutreten.
Für jede der im Workflow erwähnten Methoden können Sie mit dem API Explorer genau sehen, wie sich die jeweilige Methode verhält. Außerdem empfehlen wir, vor Abschluss dieser Anleitung Folgendes zu lesen:
Erste Schritte
Bevor Sie die Details für den Import von Kurslisten aus Classroom implementieren, müssen Sie festlegen, welche Kurs- und Nutzerinformationen Sie über die API abrufen müssen. In der Referenzdokumentation finden Sie Informationen zu den verfügbaren Kursmetadaten. Einige erforderliche oder häufig benötigte Felder sind unten zusammengefasst:
| Feld | Verwenden |
|---|---|
| id | Erforderlich für API-Anfragen zum Abrufen von Schülern/Studenten oder Lehrkräften |
| name | Empfohlen für eine einfache Nutzung durch den Nutzer, z.B. durch Anzeige auf Ihrer Website |
| ownerId | Erforderlich beim domainweiten Import, um die Hauptlehrkraft eines Kurses korrekt zu identifizieren |
Diese Kursinformationen werden im Schritt courses.list des oben beschriebenen Workflows abgerufen. In dieser Anfrage können Sie bestimmte Anfrageparameter angeben. Für diese Methode sind keine Parameter erforderlich, aber es gibt einige empfohlene Parameter:
| Parameter | Verwenden |
|---|---|
| courseState | Wenn nicht angegeben, gibt die API Kurse aller sechs Kursstatus zurück. Wir empfehlen, ACTIVE anzugeben, um die Kurse abzurufen, die Lehrkräfte derzeit verwenden. |
| pageSize | Lehrkräften, die eigene Kurse importieren, empfehlen wir, einen kleinen Wert für „pageSize“ (weniger als 10) anzugeben, um die Antwortzeit des API-Aufrufs zu verkürzen. |
| pageToken | Erforderlich, wenn Sie paginierte Anfragen verwenden. |
| teacherId | Empfohlen, da Domainadministratoren häufig Kurse unterrichten. Wenn nicht angegeben, werden in der Anfrage Kurse für Lehrkräfte in der gesamten Domain zurückgegeben. |
| Felder | Wird empfohlen, um die Antwortzeit des API-Aufrufs zu verkürzen. |
Mithilfe der zuvor abgerufenen Kurs-IDs kann Ihre Anwendung jetzt die Liste der Schüler/Studenten und zusätzlichen Lehrkräfte für diesen Kurs oder diese Kurse abrufen. Diese Kurs-ID ist der einzige erforderliche Abfrageparameter für teachers.list und students.list. Sie sollten jedoch auch die Parameter pageSize und fields angeben, um die Antwortzeit Ihrer API-Aufrufe zu verkürzen.
Alle verfügbaren Felder für die Ressourcen student und teacher finden Sie in der jeweiligen Dokumentation. Die beiden am häufigsten verwendeten und in der Regel erforderlichen Felder befinden sich im Feld profile: profile.name und profile.emailAddress.
| Feld | Verwenden |
|---|---|
| profile.name | Empfohlen für eine einfache Nutzung durch den Nutzer, z.B. durch Anzeige auf Ihrer Website |
| profile.emailAddress | Erforderlich für Anwendungen, die Schüler/Studenten eindeutig identifizieren möchten |
Wenn Sie diese Kurs- oder Teilnehmerlisteninformationen aus Classroom abrufen und verwenden möchten, muss Ihre Anwendung eine Autorisierung von den Nutzern anfordern. Für die Implementierung dieses Workflows sind drei (3) erforderliche Bereiche erforderlich:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Ermöglicht den Lesezugriff auf Kurse in Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Bietet schreibgeschützten Zugriff auf die Teilnehmerlisten von Google Classroom-Kursen (Lehrkräfte und Lernende).
- https://www.googleapis.com/auth/classroom.profile.emails
- Bietet Lesezugriff auf die Eigenschaft email von Lehrkräften und Schülern/Studenten.
Roster mit Pub/Sub-Benachrichtigungen synchronisieren
Im Laufe des Schuljahres können sich die Teilnehmerlisten ändern, wenn Schüler Kurse abwählen oder hinzufügen. Wenn Sie Pub/Sub-Benachrichtigungen hinzufügen, können Sie Ihre Drittanbieteranwendung mit den Kurslisten von Classroom synchronisieren. Wenn Sie Benachrichtigungen erhalten möchten, richten Sie ein Google Cloud Pub/Sub-Thema ein und registrieren Sie das Thema dann bei der Classroom API. Diese Registrierung ist eine Anfrage, dass Classroom Daten aus dem angegebenen Feed an das angegebene Thema sendet. Dieser Feed enthält die Ereignistrigger für die erneute Synchronisierung mit der Teilnehmerliste einer Lehrkraft in Classroom.
Für die Verwendung von Push-Benachrichtigungen ist ein zusätzlicher Bereich erforderlich, der nicht zur Überprüfung eingereicht werden muss:
- https://www.googleapis.com/auth/classroom.push-notifications
- Ermöglicht Ihrer App, sich für alle Push-Benachrichtigungsaktivitäten zu registrieren
Weitere Informationen zur Integration von Classroom-Push-Benachrichtigungen finden Sie in unserem Leitfaden zum Verwalten von Push-Benachrichtigungen.