Einführung

Lehrkräfte, die sowohl Classroom-Tools als auch Tools von Drittanbietern nutzen, müssen ihre Kurse und Teilnehmerlisten plattformübergreifend einrichten. Dies kann manuell erfolgen, entweder über CSV-Uploads oder durch Eingabe der E-Mail-Adressen einzeln. Mit der Classroom API können Drittanbietertools jedoch die Arbeitslast von Lehrkräften reduzieren, da sie in den häufigsten Anwendungsfall der API eingebunden werden: den Import von Teilnehmerlisten.

Durch das Importieren von Teilnehmerlisten können Drittanbieterplattformen die Metadaten eines Kurses, Lehrkräfte und Schüler/Studenten für jeden Kurs mit Berechtigungen für Lehrkräfte oder Administratoren abrufen. Lehrkräfte können Details zu den Kursen abrufen, die sie unterrichten, während Administratoren Zugriff auf Details für alle Kurse in der gesamten Domain haben. Dank dieser Flexibilität können Entwickler Classroom-Teilnehmerlisten nahtlos auf ihrer Plattform einrichten – sowohl für einzelne Lehrkräfte als auch für die gesamte Domain, indem sie Administratoranmeldedaten verwenden.

Domainadministratoren können Drittanbieter-Tools für ihre eigenen Kurse einsetzen. Beim Abrufen von Kursdetails über die API muss der Unterschied zwischen den Berechtigungen für den Domainadministrator und die Berechtigungen für Lehrkräfte sorgfältig gehandhabt werden.

Bevor wir uns mit den technischen Details einer Integration des Imports von Teilnehmerlisten befassen, sehen wir uns zuerst einen Beispielworkflow an:

1. In der Drittanbieter-App wählt die Lehrkraft die Option zum Importieren eines Classroom-Kurses aus.

2. Die Drittanbieteranwendung ruft die Methode courses.list über die Classroom API auf, die eine JSON-Antwort mit allen Kursen der Lehrkraft zurückgibt.

3. Aus der JSON-Antwort zeigt die Drittanbieteranwendung die Titel der Kurse der Lehrkraft an, damit sie einen auswählen können. Die Anwendung muss die Kurs-IDs im Auge behalten, um mit dem nächsten Schritt fortfahren zu können.

4. Mit der ausgewählten Kurs-ID ruft die Drittanbieter-App die Methoden students.list und teachers.list auf und zeigt alle Namen auf ihrer Website an, damit Lehrkräfte den Import bestätigen können.

5. Mithilfe der E-Mails, die in den Antwort-JSONs für students.list und teachers.list zurückgegeben werden, lädt die Drittanbieteranwendung die Nutzer ein, dem neu importierten Kurs auf ihrer Plattform beizutreten.

Mit dem API Explorer können Sie für jede der im Workflow erwähnten Methoden genau sehen, wie sich jede Methode verhält. Bevor Sie diesen Leitfaden abschließen, sollten Sie außerdem die folgenden Lesematerialien lesen:

1. Kurse mit der Classroom API verwalten
2. Schüler, Studenten und Lehrkräfte verwalten

Sehen Sie sich zusätzlich zum Workflow-Diagramm unten auch das Live-Beispiel von ActivelyLearn an, um ein besseres Verständnis für diese Art der Integration zu erhalten.

Erste Schritte

Bevor Sie die Details des Imports Ihrer Classroom-Teilnehmerliste implementieren, müssen Sie festlegen, welche Kurs- und Nutzerinformationen Sie über die API abrufen müssen. Welche Kursmetadaten verfügbar sind, können Sie der Referenzdokumentation entnehmen. Einige erforderliche oder allgemeine Felder, die erforderlich sind, finden Sie jedoch unten:

Feld	Verwenden
id	Erforderlich für API-Anfragen zum Abrufen von Schülern, Studenten oder Lehrkräften
name	Aus Gründen der Nutzerfreundlichkeit empfohlen, d.h. zur Anzeige auf Ihrer Website
ownerId	Erforderlich beim domainweiten Import, um die Hauptlehrkraft eines Kurses korrekt zu identifizieren

Diese Kursinformationen werden im obigen Schritt courses.list des Workflows abgerufen. In dieser Anfrage können Sie bestimmte Anfrageparameter angeben. Für diese Methode sind zwar keine der Parameter erforderlich, dies sind jedoch einige empfohlene Parameter:

Parameter	Verwenden
courseState	Wenn Sie nichts angeben, 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 ihre eigenen Kurse importieren, empfehlen wir, eine kleine Größe (weniger als 10) anzugeben, um die Antwortzeit des API-Aufrufs zu verkürzen.
pageToken	Erforderlich, wenn Sie ausgelagerte Anfragen verwenden.
teacherId	Empfohlen, da Domainadministratoren häufig Kurse unterrichten. Wenn Sie nichts angeben, werden bei 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.

Mithilfe der zuvor abgerufenen Kurs-IDs kann Ihre Anwendung nun die Liste der Schüler/Studenten und zusätzlichen Lehrkräfte für diese Kurse abrufen. Diese Kurs-ID ist der einzige erforderliche Abfrageparameter für teachers.list und students.list. Ähnlich empfiehlt es sich, die Parameter pageSize und fields anzugeben, um die Antwortzeit Ihrer API-Aufrufe zu verringern.

Alle verfügbaren Felder für die Ressourcen für Schüler/Studenten und Lehrkräfte finden Sie in der entsprechenden Dokumentation. Die beiden am häufigsten verwendeten und normalerweise erforderlichen Felder befinden sich im Feld profile: profile.name und profile.emailAddress.

Feld	Verwenden
profile.name	Aus Gründen der Nutzerfreundlichkeit empfohlen, d.h. zur Anzeige auf Ihrer Website
profile.emailAddress	Erforderlich für Anwendungen, mit denen Schüler und Studenten eindeutig identifiziert werden sollen

Um diese Kurs- oder Teilnehmerlistendetails aus Classroom abzurufen und zu verwenden, muss Ihre Anwendung eine Autorisierung von Nutzern anfordern. Für die Implementierung dieses Workflows sind drei (3) erforderliche Bereiche erforderlich:

• https://www.googleapis.com/auth/classroom.courses.readonly
  • Gewährt Lesezugriff auf Google Classroom-Kurse
• https://www.googleapis.com/auth/classroom.rosters.readonly
  • Gewährt Lesezugriff auf die Listen von Google Classroom-Kursen (Lehrkräfte und Schüler/Studenten)
• https://www.googleapis.com/auth/classroom.profile.emails
  • Gewährt Lesezugriff auf die Property email von Lehrkräften, Schülern oder Studenten

Da einer dieser Bereiche als vertraulich gilt, muss Ihre Anwendung einen Überprüfungsprozess durchlaufen.

Teilnehmerlisten mit Pub/Sub-Benachrichtigungen synchronisieren

Im Verlauf des Schuljahres können sich die Teilnehmerlisten ändern, wenn Lernende Kurse löschen oder hinzufügen. Wenn Sie Pub/Sub-Benachrichtigungen hinzufügen, können Sie Drittanbieteranwendungen mit den Classroom-Listen synchron halten. Um Benachrichtigungen zu erhalten, richten Sie ein Google Cloud Pub/Sub-Thema ein und registrieren das Thema dann bei der Classroom API. Mit dieser Registrierung sendet Classroom Daten aus dem gegebenen Feed zum jeweiligen Thema. Dieser Feed ist der Ereignisauslöser für die erneute Synchronisierung mit der Classroom-Teilnehmerliste einer Lehrkraft.

Je nach Anwendungsfall Ihrer Anwendung können Sie Benachrichtigungen für einzelne Kurse oder Domains abonnieren.

Die Nutzung von Push-Benachrichtigungen erfordert einen zusätzlichen Bereich, der nicht zur Überprüfung eingereicht werden muss:

• https://www.googleapis.com/auth/classroom.push-notifications
  • Ermöglicht deiner App, sich bei Push-Benachrichtigungen zu registrieren

Weitere Informationen zur Einbindung von Push-Benachrichtigungen in Classroom finden Sie im Leitfaden zum Verwalten von Push-Benachrichtigungen.