API-Ressourcen

Dieser Leitfaden bietet einen Überblick über die wichtigsten Komponenten der Google Classroom API. Die Google Classroom API besteht aus Ressourcen und Diensten. Ressourcen stellen Entitäten in Google Classroom dar, z. B. einen Kurs oder eine Aufgabe. Dienste rufen diese Ressourcen ab und verwalten sie. Einige dieser Entitäten haben zusätzlich zu den in Classroom vorhandenen Attributen zusätzliche API-spezifische Attribute. Die Hauptentitätstypen sind:

Entität	Darstellung 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, außerhalb des Kontexts von Schülern, Studenten oder Lehrkräften.
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 in 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. zum Ändern der Liste der Schüler, denen eine bestimmte Aufgabe zugewiesen ist.

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 Kennungen 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/Studenten reichen 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. Mathematik der 4. Stunde von Smith“ 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 umschließt 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 zugeordnet 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 Domainnamensraum 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 mit einer bestimmten Google API Console verknüpft. 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 Rollen „Schüler/Student“ und „Lehrkraft“ sind nicht global: Ein Nutzer kann für einen Kurs als Lehrkraft und für einen 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. Ein Kurs kann mehrere Lehrkräfte oder keine Schüler/Studenten haben. Lehrkräfte und Schüler/Studenten können einem Kurs jederzeit hinzugefügt oder daraus entfernt werden.

Studenten

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

Schüler/Studenten dürfen 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 an einem Kurs teilnehmen möchten, anstatt dass Sie sie direkt über die Ressourcen für Lehrkräfte und Schüler/Studenten hinzufü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 UserProfiles-Dienst können auch Guardians verwaltet und eingeladen werden. Dabei handelt es sich um eine Zuordnung zwischen einem Schüler/Studenten 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.

Elemente streamen

Streamelemente sind die geposteten Inhalte, die für die Mitglieder eines Kurses freigegeben wurden. Entwickler und Lehrkräfte können drei Arten von Streamelementen erstellen: Announcement, CourseWork und CourseWorkMaterial.

Lehrkräfte erstellen Announcements oben auf der Stream-Seite in der Classroom-Benutzeroberfläche. Lehrkräfte erstellen CourseWork und CourseWorkMaterials, indem sie auf dem Tab „Aufgaben“ auf die Schaltfläche Erstellen klicken. Entwickler können alle Streamelementtypen programmatisch über die Classroom API erstellen.

Für Streamelemente gilt Folgendes:

• Alle Streamelemente können zusätzliche Materialien enthalten, z. B. Google Drive-Dateien, YouTube-Videos, Google Formulare, URL-Hyperlinks und Anhänge von Classroom-Add-ons.
• Alle Streamelemente können einer Teilmenge der Schüler/Studenten im Kurs zugewiesen werden.
• Ein CourseWork kann benotet oder unbenotet sein. Lehrkräfte können den Benotungsstatus einer CourseWork-Aufgabe jederzeit ändern.
• Ein Streamelement kann mehrere Anhänge haben.
• Ein Streamelement kann Anhänge verschiedener Typen haben. Eine CourseWork-Aufgabe kann beispielsweise Google Drive-Dateien, YouTube-Videos und Anhänge aus dem Classroom-Add-on gleichzeitig enthalten.
• Ein Streamelement kann Add-on-Anhänge von mehreren Entwicklern haben.
• Entwickler können Details zu jeder Streamelementressource abrufen und ändern, die eines ihrer Add-on-Anhänge enthält.
• Entwickler können die Abgabe eines Schülers oder Studenten für eine CourseWork-Aufgabe, die einen ihrer Add-on-Anhänge enthält, einreichen, zurückziehen oder zurückgeben.
• Entwickler können Noten nur für einzelne Einreichungen von Schülern/Studenten in von ihnen erstellten Aufgaben endgültig festlegen.

Gekopierte Streamelemente

Lehrkräfte können ein Streamelement kopieren, indem sie einen Kurs kopieren, eine Aufgabe wiederverwenden oder ein Streamelement in mehreren Kursen veröffentlichen. Alle neuen Kopien haben eindeutige Kennungen. Das ist ein wichtiger Aspekt, wenn Sie ein Classroom-Add-on entwickeln. In unserem Leitfaden zu kopierten Inhalten erfahren Sie, wie ein Add-on diese Szenarien behandeln kann.

Kursaufgaben und Abgegebene Aufgaben

Ein CourseWork-Element steht für eine Aufgabe für eine Gruppe von Schülern/Studenten in einem Kurs. Es ist der einzige Streamelementtyp, für den eine Einreichung von Schülern/Studenten zulässig ist. Eine CourseWork-Ressource enthält Details wie die Beschreibung, den Abgabetermin, die Höchstnote und Metadaten wie den Erstellungszeitpunkt.

Jede CourseWork-Ressource beschreibt einen der folgenden Aufgabentypen:

• Eine Aufgabe, die Schüler oder Studenten durch Einreichen von Arbeitsblättern oder anderen Anhängen erledigen.
• Eine Frage mit 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 einem Status und einer zugewiesenen Note.

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

• Die für eine Aufgabe eingereichten Arbeitsblätter und Anhänge, einschließlich Titel, Thumbnail und URL sowie Kennungen, 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 Kursarbeiten verwalten.

Kursmaterialien und Ankündigungen

Ähnlich wie CourseWork stehen CourseWorkMaterials für Inhalte, die einer Gruppe von Schülern/Studenten in einem Kurs zugewiesen sind. Jede Ressource enthält Details wie einen Titel und eine Beschreibung sowie ergänzende Materialien. Im Gegensatz zu CourseWork müssen Schüler und 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 verwenden, um Lesematerial, 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. Der Schüler/Student muss 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.

Anmeldungen

Für Anwendungen können Benachrichtigungen abonniert werden, wenn sich bestimmte Daten in Google Classroom ändern. 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.