Lehrkräfte, die sowohl Classroom als auch Tools von Drittanbietern nutzen, stehen vor der Herausforderung, ihre Kurse und Teilnehmerlisten auf mehreren Plattformen einzurichten. Dies kann manuell erfolgen, entweder über CSV-Uploads oder durch Eingabe der E-Mail-Adressen einzeln. Mit der Classroom API können Tools von Drittanbietern jedoch die Arbeitsbelastung von Lehrkräften reduzieren, indem sie den häufigsten Anwendungsfall der API einbinden: den Import von Teilnehmerlisten.
Mit dem Importieren von Teilnehmerlisten können Drittanbieterplattformen die Metadaten, Lehrkräfte und Schüler/Studenten eines Kurses kursweise abrufen, wenn sie Lehrkraft- oder Administratorberechtigungen haben. Lehrkräfte können Details zu den von ihnen unterrichteten Kursen abrufen, während Administratoren Zugriff auf Details zu allen Kursen in einer gesamten Domain haben. Diese Flexibilität ermöglicht es Entwicklern, Kurslisten mithilfe von Administratoranmeldedaten nahtlos auf ihrer Plattform einzurichten, sowohl auf Ebene einzelner Lehrkräfte als auch für eine ganze Domain.
Bevor wir uns mit den technischen Details einer Integration für den Spielerlistenimport befassen, sehen wir uns zuerst einen Beispiel-Workflow an:
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, wodurch eine JSON-Antwort mit allen Kursen des Lehrers zurückgegeben wird.Anhand der JSON-Antwort zeigt die Drittanbieteranwendung die Titel der Kurse des Lehrers an, aus denen er einen auswählen kann. Die Anwendung muss die Kurs-IDs im Auge 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 wurden, lädt die Drittanbieteranwendung die Nutzer ein, sich dem neu importierten Kurs auf ihrer Plattform anzuschließen.
Mit dem API Explorer können Sie für jede der im Workflow genannten Methoden genau sehen, wie sie sich verhalten. Wir empfehlen Ihnen außerdem, sich die folgenden Artikel anzusehen, bevor Sie mit diesem Leitfaden fortfahren:
Erste Schritte
Bevor Sie die Details Ihres Classroom-Kurslistenimports 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 gängige Felder werden unten zusammengefasst:
| Feld | Verwenden |
|---|---|
| id | Erforderlich für API-Anfragen, bei denen Schüler/Studenten oder Lehrkräfte abgerufen werden |
| name | Empfohlen für die Nutzerfreundlichkeit, d.h. für die Anzeige auf Ihrer Website |
| ownerId | Erforderlich, wenn auf domainweiter Basis importiert wird, um die Hauptlehrkraft eines Kurses korrekt zu identifizieren |
Diese Kursinformationen werden im Schritt courses.list des Workflows oben abgerufen. In dieser Anfrage können Sie bestimmte Anfrageparameter angeben. Für diese Methode sind keine Parameter erforderlich. Wir empfehlen jedoch folgende Parameter:
| Parameter | Verwenden |
|---|---|
| courseState | Wenn Sie diesen Parameter nicht angeben, gibt die API Kurse mit allen sechs Kursstatus zurück. Wir empfehlen, ACTIVE anzugeben, um die Kurse abzurufen, die Lehrkräfte derzeit verwenden. |
| pageSize | Lehrkräften, die ihre eigenen Kurse importieren, empfehlen wir, eine kleine Seitengröße (unter 10) anzugeben, um die Antwortzeit des API-Aufrufs zu verkürzen. |
| pageToken | Erforderlich, wenn Sie getaktete Anfragen verwenden. |
| teacherId | Empfohlen, da Domainadministratoren oft Kurse leiten. Wenn keine Angabe gemacht wird, werden in der Anfrage Kurse für Lehrkräfte in der gesamten Domain zurückgegeben. |
| Felder | Es wird empfohlen, die Antwortzeit des API-Aufrufs zu verkürzen. |
Anhand der zuvor abgerufenen Kurs-IDs kann Ihre Anwendung jetzt die Liste der Schüler oder Studenten und der zusätzlichen Lehrkräfte für diesen oder diese Kurse abrufen. Diese Kurs-ID ist der einzige erforderliche Abfrageparameter für teachers.list und students.list. Sie können aber auch die Parameter pageSize und fields angeben, um die Antwortzeit Ihrer API-Aufrufe zu verkürzen.
Alle verfügbaren Felder für die Ressourcen für Schüler/Studenten und Lehrkräfte 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 die Nutzerfreundlichkeit, d.h. für die Anzeige auf Ihrer Website |
| profile.emailAddress | Erforderlich für Anwendungen, mit denen Schüler/Studenten eindeutig identifiziert werden sollen |
Wenn Ihre App diese Kurs- oder Teilnehmerlistendetails aus Classroom abrufen und verwenden soll, muss sie von den Nutzern autorisiert werden. Für die Implementierung dieses Workflows sind drei (3) Bereiche erforderlich:
- https://www.googleapis.com/auth/classroom.courses.readonly
- Lesezugriff auf Kurse in Google Classroom
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Bietet Lesezugriff auf die Kurslisten von Google Classroom-Kursen (Lehrkräfte und Schüler/Studenten)
- https://www.googleapis.com/auth/classroom.profile.emails
- Ermöglicht Lesezugriff auf das Attribut email von Lehrkräften und Schülern/Studenten
Teilnehmerlisten mit Pub/Sub-Benachrichtigungen synchronisieren
Im Laufe des Schuljahres können sich die Teilnehmerlisten ändern, wenn Schüler oder Studenten Kurse abbrechen oder hinzufügen. Wenn Sie Pub/Sub-Benachrichtigungen hinzufügen, können Sie Ihre Drittanbieteranwendung mit den Klassenlisten in Classroom synchronisieren. Wenn Sie Benachrichtigungen erhalten möchten, richten Sie ein Google Cloud Pub/Sub-Thema ein und registrieren Sie es dann bei der Classroom API. Diese Registrierung ist eine Anfrage an Classroom, Daten aus dem angegebenen Feed an das angegebene Thema zu senden. Dieser Feed ist der Ereignisauslöser für die erneute Synchronisierung mit der Classroom-Teilnehmerliste einer Lehrkraft.
Für die Nutzung 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 es Ihrer App, sich für alle Push-Benachrichtigungsaktivitäten zu registrieren
Weitere Informationen zur Integration von Push-Benachrichtigungen in Classroom finden Sie in unserem Leitfaden zum Verwalten von Push-Benachrichtigungen.