Lehrkräfte, die sowohl Classroom als auch Drittanbieter-Tools verwenden, stehen vor der Herausforderung, ihre Kurse und Teilnehmerlisten auf mehreren Plattformen einzurichten. Dies kann manuell erfolgen, entweder durch CSV-Uploads oder durch Eingabe der E-Mail-Adressen einzeln. Mit der Classroom API können Drittanbietertools die Arbeitsbelastung von Lehrkräften jedoch verringern, indem sie sich in den häufigsten Anwendungsfall der API integrieren: den Import von Kurslisten.
Durch den Import von Teilnehmerlisten können Drittanbieterplattformen die Metadaten, Lehrkräfte und Schüler/Studenten 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 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 Kurslisten 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.In der JSON-Antwort werden die Titel der Kurse des Lehrers angezeigt, 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 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 in Classroom implementieren, müssen Sie festlegen, welche Kurs- und Nutzerinformationen Sie über die API abrufen müssen. Welche Kursmetadaten verfügbar sind, können Sie in der Referenzdokumentation nachlesen. 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, d.h. für die Anzeige auf Ihrer Website |
| ownerId | Erforderlich beim Import auf Domainebene, um den Hauptlehrer 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 zwar keine Parameter erforderlich, aber einige werden empfohlen:
| 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 oder 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 Reaktionszeit 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, d.h. für die 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 die Autorisierung von 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 Lesezugriff auf die Teilnehmerlisten von Google Classroom-Kursen (Lehrkräfte und Schüler/Studenten).
- https://www.googleapis.com/auth/classroom.profile.emails
- Bietet Lesezugriff auf die Eigenschaft email von Lehrkräften und Schülern/Studenten.
Synchronisieren von Teilnehmerlisten mit Pub/Sub-Benachrichtigungen
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 es dann in 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.