API-Struktur

Dieser Leitfaden bietet einen Überblick über die wichtigsten Komponenten der Google Classroom API. Die Google Classroom API besteht aus Ressourcen und Diensten. Ressourcen stellen Elemente in Google Classroom dar, z. B. Kurse oder Aufgaben. Diese werden von Diensten abgerufen und verwaltet. Einige dieser Entitäten haben zusätzlich zu den in Classroom vorhandenen Attributen zusätzliche API-spezifische Attribute. Die Hauptentitätstypen sind:

Entität	Repräsentation in Classroom
Kurse	Eine Klasse, z. B. „M. Mathematik der 4. Stunde von Smith“
Aliasse	Eine alternative ID für einen Kurs.
Einladungen	Eine Möglichkeit, einem Kurs Nutzer hinzuzufügen.
Kursteilnehmer	Ein Schüler/Student in einem Kurs.
Lehrkräfte	Eine Lehrkraft in einem Kurs.
Nutzerprofile	Ein Nutzer im Allgemeinen, also außerhalb des Kontexts des Schülers/Studenten oder der Lehrkraft.
CourseWork	Eine Aufgabe in einem Kurs.
StudentSubmissions	Schüler/Studenten arbeiten an einer bestimmten Aufgabe, z. B. an Antworten oder Arbeitsblättern.
CourseWorkMaterials	Materialien für Schüler/Studenten in einem Kurs.
Ankündigungen	Eine Ankündigung für Schüler/Studenten in einem Kurs.
AddOnAttachment	Inhalte oder Aktivitäten zu einer Aufgabe oder einem Material, die normalerweise als eingebetteter iFrame angezeigt werden.
Themen	Eine visuelle Gruppierung von Aufgaben und Materialien in einem Kurs.
Registrierungen	Eine Anweisung, Benachrichtigungen bei Datenänderungen an Ihre App zu senden, z. B. bei Änderungen an einer Teilnehmerliste.

Die meisten Ressourcen haben Dienstmethoden für Standardvorgänge wie das Lesen, Aktualisieren und Löschen von Instanzen der Ressource. Einige Ressourcen haben auch benutzerdefinierte Methoden für andere Vorgänge, z. B. das Ändern der Liste der Schüler/Studenten, denen eine bestimmte Aufgabe zugewiesen wurde.

Ausführliche Informationen zu den API-Ressourcen und -Methoden finden Sie in der Referenz zur Classroom API.

Ressourcenbeziehungen – Übersicht

• Der Kurs ist das grundlegende Datenobjekt in Google Classroom.
• Aliasse werden als alternative Kennzeichnungen für Courses verwendet.
• Mit Einladungen können Nutzerprofile zu Lehrkräften oder Schülern/Studenten in einer Course eingeladen werden. Nutzer können aber auch direkt von Google Workspace for Education-Domainadministratoren hinzugefügt werden.
• Lehrkräfte erstellen Streams und teilen sie mit den Schülern oder Studenten in ihren Kursen. Mögliche Streamelementtypen sind Kursarbeit, Kursmaterialien und Ankündigungen. Die CourseWork und CourseWorkMaterials können visuell in Themen organisiert werden und Add-on-Anhänge enthalten. Schüler und Studenten geben StudentSubmissions für ihre CourseWork ein.
• Entwickler können Registrierungen erstellen, um benachrichtigt zu werden, wenn sich einige dieser Daten ändern.

Google Classroom ist für Domains verfügbar, die Google Workspace for Education abonniert haben. Eine Domain im Kontext von Classroom steht in der Regel für einen Schulbezirk. Sie können eine Testdomain für Google Workspace for Education für Entwicklungszwecke erstellen. So haben Sie die Kontrolle über eine Produktionsinstanz von Classroom, ohne dass sich dies auf echte Nutzer auswirkt.

Kurse und Aliasse

Courses steht für eine Klasse, z. B. „M. und die zugewiesenen Lehrkräfte, die Teilnehmerliste und die Metadaten. Jeder Kurs wird durch eine eindeutige ID identifiziert, die vom Server zugewiesen wird. Die Course-Ressource enthält insbesondere alle Metadaten zum Kurs, z. B. den Namen, die Beschreibung, den Ort und die Zeit. Teilnehmerlisten für Kurse werden über die Ressourcen Schüler, Lehrkraft und Einladung und ihre Methoden verwaltet.

Aliases sind alternative IDs für einen Kurs, die einem Kurs zugewiesen und anstelle der eindeutigen ID verwendet werden können. Jeder Alias befindet sich in einem Namespace, der einschränkt, wer ihn erstellen und aufrufen kann. Es werden zwei Namespaces unterstützt:

• Domain:Der Domain-Namespace eignet sich zum Erstellen von Aliasen, auf die alle Nutzer zugreifen müssen, die aber nicht für ein bestimmtes Programm spezifisch sind. Beispielsweise sollten alternative Einträge für einen Kurs wie MATH 127 und COMSCI 127 im Domain-Namespace erstellt werden. Aliasse im Domain-Namespace können nur von Domainadministratoren erstellt werden, sind aber für alle Nutzer in einer Domain sichtbar.
• Entwicklerprojekt: Der Namespace des Entwicklerprojekts ist nützlich, um Aliasse zu verwalten, die für eine Anwendung spezifisch sind. Eine Anwendung, die beispielsweise alternative IDs für Kurse verwendet, kann Aliasse erstellen, um ihre ID zu Classroom-Kursen zuzuordnen. In diesem Namespace erstellte Aliasse sind an eine bestimmte Google API Console gebunden. Jeder Nutzer einer Anwendung kann Aliasse im Namespace für das Entwicklerprojekt dieser Anwendung erstellen und aufrufen.

Weitere Informationen zum Verwalten von Kursmetadaten und Aliassen finden Sie unter Kurse verwalten.

Kurslisten und Nutzer

Students und Teachers sind spezifische Zuordnungen zwischen einem Nutzerprofil und einem Kurs, die die Rolle des Nutzers im Kurs darstellen. Die Bezeichnungen „Schüler/Student“ und „Lehrkraft“ sind nicht global: Ein Nutzer kann in einem Kurs als Lehrkraft und in einem anderen als Schüler/Student zugewiesen werden. Die Bezeichnung „Schüler“ oder „Lehrkraft“ steht für eine Reihe von Berechtigungen für einen bestimmten Nutzer in einem bestimmten Kurs.

Studenten

Eine Student-Ressource stellt einen Nutzer dar, der als Schüler oder Student in einem bestimmten Kurs eingeschrieben ist.

Schüler/Studenten können sich die Kursdetails und die Lehrkräfte für diesen Kurs ansehen.

Lehrkräfte

Eine Teacher-Ressource stellt einen Nutzer dar, der einen bestimmten Kurs unterrichtet.

Lehrkräfte dürfen die Kursdetails aufrufen und ändern, Lehrkräfte und Schüler/Studenten ansehen und weitere Lehrkräfte und Schüler/Studenten verwalten.

Invitations und die zugehörigen Methoden bieten eine praktische Möglichkeit, Kursen Schüler/Studenten und Lehrkräfte hinzuzufügen. Wenn Sie Einladungen erstellen, können Nutzer selbst entscheiden, ob sie einem Kurs beitreten möchten oder nicht, anstatt sie direkt über die Ressourcen für Lehrkräfte und Schüler/Studenten hinzuzufügen.

UserProfiles steht für eine Zuordnung zum Domainprofil eines Nutzers, wie durch die eindeutige ID oder E-Mail-Adresse des Nutzers angegeben, die von der Directory API zurückgegeben wird. Der aktuelle Nutzer kann sich auch mit der Kurzform "me" auf seine eigene ID beziehen.

Mit dem Dienst UserProfiles können Sie auch Guardians verwalten und einladen. Dies ist eine Zuordnung zwischen einem Schüler und einem Erziehungsberechtigten. Erziehungsberechtigte in Classroom haben Zugriff auf einige Informationen zu Schülern, z. B. zu ihren Aufgaben.

Weitere Informationen zum Verwalten von Teilnehmerlisten finden Sie unter Lehrkräfte und Schüler/Studenten verwalten.

Kursaufgaben und abgegebene Aufgaben

Ein CourseWork-Element steht für eine einzelne Aufgabe, die einer Gruppe von Schülern/Studenten in einem Kurs zugewiesen wurde. Sie enthält Details wie die Beschreibung, den Abgabetermin und die Materialien sowie Metadaten wie den Erstellungszeitpunkt. Die Materialien umfassen einen Titel, ein Thumbnail und eine URL sowie eine Kennung, die mit den entsprechenden APIs (z.B. Drive, YouTube) verwendet werden kann.

CourseWork Elemente beschreiben eine der folgenden Arten von Aufgaben:

• Eine Aufgabe, die Schüler oder Studenten durch Einreichen von Arbeitsblättern oder anderen Anhängen abschließen können.
• Eine Kurzantwort- oder Multiple-Choice-Frage.

Die Arbeit von Schülern/Studenten für ein CourseWork-Element wird durch ein StudentSubmission dargestellt. Sie besteht aus einer Antwort und zusätzlichen Metadaten wie dem Status und der zugewiesenen Note.

Der Inhalt eines StudentSubmission hängt vom Typ des entsprechenden CourseWork-Elements ab:

• Die Arbeitsblätter und Anhänge, die für eine Aufgabe eingereicht wurden, einschließlich Titel, Miniaturansicht und URL sowie IDs, die mit den entsprechenden APIs wie Drive oder YouTube verwendet werden können.
• Die Antwort auf eine Frage mit Kurzantwort oder Multiple-Choice-Frage.

Weitere Informationen zum Verwalten von Kursarbeiten und Einreichungen von Schülern/Studenten finden Sie unter Kursarbeit verwalten.

Kursmaterialien und Ankündigungen

Ähnlich wie CourseWork steht CourseWorkMaterials für Inhalte, die einer Gruppe von Schülern oder Studenten in einem Kurs zugewiesen sind. Dazu gehören Details wie ein Titel und eine Beschreibung sowie Materialien. Im Gegensatz zu CourseWork müssen Schüler oder Studenten bei CourseWorkMaterials jedoch keine Artefakte einreichen. Daher gibt es keinen Abgabetermin und StudentSubmissions gibt es für CourseWorkMaterials nicht. Lehrkräfte können CourseWorkMaterials beispielsweise verwenden, um Lesevorschläge, einen Lehrplan oder Kursregeln zu posten.

Announcements stehen auch für Inhalte, die mit einer Gruppe von Schülern/Studenten geteilt wurden, haben aber keine Details wie einen Titel und können nicht wie CourseWork oder CourseWorkMaterials nach Topics organisiert werden. Lehrkräfte können sie beispielsweise verwenden, um Erinnerungen oder Mitteilungen an die Klasse zu senden.

Themen

Topics werden verwendet, um CourseWork und CourseWorkMaterials innerhalb einer Klasse visuell zu organisieren. So können Sie beispielsweise Aufgaben in „optional“ und „erforderlich“ oder „Modul 1“ und „Modul 2“ gruppieren.

Add-ons für Classroom

Ein Add-on ist eine vom Entwickler bereitgestellte Benutzeroberfläche und ein Back-End, die bzw. das in der Regel in einem IFrame angezeigt wird. Add-ons werden als Anhänge zu einem Streamelement angezeigt. Das Streamelement kann Announcements, CourseWork oder CourseWorkMaterials sein. Add-on-Anhänge sind durch ein AddOnAttachment gekennzeichnet.

Add-on-Anhänge können Aktivitäten oder Inhalte sein.

• Bei Aktivitätsanhängen müssen die Schüler oder Studenten eine individuelle Aufgabe erledigen und einreichen. Beispiele sind Quizze, Verlosungen oder Spiele. Eine Aktivität kann optional benotet werden.
• Für angehängte Inhalte ist keine Einreichung durch Schüler oder Studenten erforderlich. Die Lernenden müssen den Anhang nicht abgeben und er wird nicht benotet. Beispiele hierfür sind Fotos, Artikel und Videos.

Weitere Informationen finden Sie in den Entwicklerleitfäden für Add-ons.

Registrierungen

Für Anwendungen können Benachrichtigungen abonniert werden, wenn sich bestimmte Daten in Google Classroom ändern. Zum Beispiel, wenn die Teilnehmerliste eines Kurses aktualisiert wird. Registrations ist eine Anweisung, diese Benachrichtigungen an Ihre Anwendung zu senden.

Weitere Informationen finden Sie im Leitfaden zu Push-Benachrichtigungen.