API-Ressourcen

In dieser Anleitung erhalten Sie einen Überblick über die primären 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 weitere Attribute, die spezifisch für die API sind. Die primären Entitätstypen sind:

Entität	Darstellung in Classroom
Kurse	Eine Klasse, z. B. „M. Smiths Mathe in der 4. Stunde“.
Aliasse	Eine alternative ID für einen Kurs.
Einladungen	Eine Möglichkeit, Nutzer einem Kurs 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	Die Arbeit eines Schülers/Studenten für eine bestimmte Aufgabe, z. B. Antworten oder Arbeitsblätter.
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 in der Regel als eingebettetes iFrame angezeigt werden.
Themen	Eine visuelle Gruppierung von Aufgaben und Materialien in einem Kurs.
Registrierungen	Eine Anweisung, Benachrichtigungen über Änderungen an Daten wie einer Teilnehmerliste von Kursen an Ihre App zu senden.

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 Classroom API-Referenz.

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 als Lehrkräfte oder Schüler/Studenten in eine Course eingeladen werden. Nutzer können aber auch direkt von Google Workspace for Education-Domainadministratoren hinzugefügt werden.
• Lehrkräfte erstellen Stream-Elemente und teilen sie mit den Schülern und Studenten in ihren Kursen. Mögliche Stream-Elementtypen sind Coursework, CourseWorkMaterials und Announcements. Die CourseWork und CourseWorkMaterials können visuell in Themen organisiert werden und AddOnAttachments enthalten. Schüler/Studenten reichen StudentSubmissions für ihre CourseWork ein.
• Entwickler können Registrierungen erstellen, um Benachrichtigungen zu erhalten, wenn sich einige dieser Daten ändern.

Google Classroom ist für Domains verfügbar, die Google Workspace for Education abonnieren. Eine Domain im Classroom-Kontext 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 Aliase

Courses steht für eine Klasse, z. B. „M“. „Mathematik in der 4. Stunde bei Herrn Smith“ mit den zugewiesenen Lehrkräften, der Teilnehmerliste und den Metadaten. Jeder Kurs wird durch eine eindeutige ID identifiziert, die vom Server zugewiesen wird. Die Course-Ressource enthält alle Metadaten zum Kurs, z. B. Name, Beschreibung, Ort und Uhrzeit. Kurslisten werden über die Ressourcen Student, Teacher und Invitation und ihre Methoden verwaltet.

Aliases sind alternative Kennungen für einen Kurs, die einem Kurs zugeordnet und anstelle der eindeutigen ID verwendet werden können. Jeder Alias ist in einem Namespace vorhanden, der einschränkt, wer ihn erstellen und ansehen kann. Es werden zwei Namespaces unterstützt:

• Domain:Der Domain-Namespace ist nützlich, um Aliase zu erstellen, auf die alle Nutzer Zugriff benötigen, die aber nicht für ein bestimmtes Programm spezifisch sind. Alternative Einträge für einen Kurs, z. B. MATH 127 und COMSCI 127, sollten im Domain-Namespace erstellt werden. Aliasse im Domain-Namespace dürfen 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 bestimmte Anwendung spezifisch sind. In einer Anwendung, in der alternative Kennungen für Kurse verwendet werden, können beispielsweise Aliase erstellt werden, um die Kennung der Anwendung den Classroom-Kursen zuzuordnen. In diesem Namespace erstellte Aliase sind an eine bestimmte Google API Console gebunden. Jeder Nutzer einer Anwendung kann Aliase im Namespace für das Entwicklerprojekt dieser Anwendung erstellen und ansehen.

Weitere Informationen zum Verwalten von Kursmetadaten und Aliasen 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 für einen Kurs als Lehrkraft und für einen anderen als Schüler/Student zugewiesen werden. Die Bezeichnung „Schüler/Student“ oder „Lehrer“ steht für eine Reihe von Berechtigungen für einen bestimmten Nutzer in einem bestimmten Kurs. Ein Kurs kann mehrere Kursleiter oder keine Schüler/Studenten haben. Lehrkräfte und Schüler/Studenten können jederzeit einem Kurs 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 repräsentiert einen Nutzer, der einen bestimmten Kurs unterrichtet.

Lehrkräfte dürfen die Kursdetails ansehen und ändern, Lehrkräfte und Schüler/Studenten ansehen sowie zusätzliche Lehrkräfte und Schüler/Studenten verwalten.

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

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

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 Schülerinformationen, z. B. auf die Aufgaben der Schüler.

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

Stream-Elemente

Stream-Elemente sind die geposteten Inhalte, die mit den Mitgliedern eines Kurses geteilt werden. Entwickler und Lehrkräfte können drei Arten von Stream-Elementen erstellen: Announcement, CourseWork und CourseWorkMaterial.

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

Folgendes gilt für Stream-Elemente:

• Alle Stream-Elemente können zusätzliches Material enthalten, z. B. Google Drive-Dateien, YouTube-Videos, Google-Formulare, URL-Hyperlinks und Anhänge von Classroom-Add-ons.
• Alle Stream-Elemente können einer Teilmenge der Schüler/Studenten im Kurs zugewiesen werden.
• Ein CourseWork kann benotet oder unbenotet sein. Lehrkräfte können den Notenstatus einer CourseWork-Aufgabe jederzeit ändern.
• Ein Stream-Element kann mehrere Anhänge haben.
• Ein Stream-Element kann Anhänge verschiedener Typen haben. So kann eine CourseWork-Aufgabe beispielsweise gleichzeitig Google Drive-Dateien, YouTube-Videos und Classroom-Add-on-Anhänge enthalten.
• Ein Stream-Element kann Add-on-Anhänge von mehreren Entwicklern enthalten.
• Entwickler können die Details zu jeder Streamelementressource abrufen und ändern, die einen ihrer Add-on-Anhänge enthält.
• Entwickler können eine Schüler- oder Studentenaufgabe für eine CourseWork-Aufgabe, die einen ihrer Add-on-Anhänge enthält, abgeben, zurückfordern oder zurückgeben.
• Entwickler können Noten nur für einzelne Schüler-/Studentenbeiträge in Aufgaben festlegen, die sie selbst erstellt haben.

Kopierte Stream-Elemente

Lehrkräfte können einen Stream-Beitrag kopieren, indem sie einen Kurs kopieren, eine Aufgabe wiederverwenden oder einen Stream-Beitrag in mehreren Kursen veröffentlichen. Alle neuen Kopien haben eindeutige Kennungen. Das kann wichtig sein, wenn Sie ein Classroom-Add-on entwickeln. In unserem Leitfaden zu kopierten Inhalten erfahren Sie, wie ein Add-on mit diesen Szenarien umgehen kann.

CourseWork und StudentSubmissions

Ein CourseWork-Element stellt eine Aufgabe für eine Gruppe von Schülern/Studenten in einem Kurs dar. Es ist der einzige Stream-Elementtyp, der eine Schüler-/Studentenarbeit annehmen kann. Eine CourseWork-Ressource enthält Details wie die Beschreibung, das Fälligkeitsdatum, die maximale Note und Metadaten wie den Erstellungszeitpunkt.

Jede CourseWork-Ressource beschreibt eine der folgenden Arten von Aufgaben:

• Eine Aufgabe, die Schüler oder Studenten erledigen, indem sie Arbeitsblätter oder andere Anhänge einreichen.
• Eine Frage mit Kurzantwort oder eine Multiple-Choice-Frage.

Die Aufgaben von Schülern/Studenten für ein CourseWork-Element werden 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, Miniaturansicht 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 eine Multiple-Choice-Frage.

Weitere Informationen zum Verwalten von Kursaufgaben und Schülerbeiträgen finden Sie unter Kursaufgaben verwalten.

Kursmaterialien und Ankündigungen

Ähnlich wie bei CourseWork stellen CourseWorkMaterials Inhalte dar, die einer Gruppe von Schülern/Studenten in einem Kurs zugewiesen sind. Jede Ressource enthält Details wie einen Titel und eine Beschreibung sowie zusätzliches Material. Im Gegensatz zu CourseWork müssen Schüler und Studenten bei CourseWorkMaterials jedoch keine Artefakte einreichen. Daher gibt es keinen Abgabetermin und StudentSubmissions ist für CourseWorkMaterials nicht vorhanden. Lehrkräfte können CourseWorkMaterials verwenden, um beispielsweise Leseempfehlungen, einen Lehrplan oder Kursregeln zu posten.

Announcements-Elemente stellen auch Inhalte dar, die mit einer Gruppe von Schülern oder Studenten geteilt wurden, haben aber keine Details wie einen Titel und können nicht nach Topics wie CourseWork oder CourseWorkMaterials organisiert werden. Lehrkräfte können diese verwenden, um Erinnerungen oder Benachrichtigungen für den Kurs anzukündigen.

Themen

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

Add-ons für Classroom

Ein Add-on ist eine vom Entwickler bereitgestellte Benutzeroberfläche und ein Backend, die in der Regel in einem iFrame angezeigt werden. Add-ons werden als Anhänge in einem Stream-Element angezeigt. Das Streamelement kann ein beliebiges Announcements, CourseWork oder CourseWorkMaterials sein. Add-on-Anhänge werden durch ein AddOnAttachment dargestellt.

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

• Für Aktivitätsanhänge muss ein Schüler oder Student eine individuelle Aufgabe einreichen. Beispiele sind Quiz, Zeichnungen oder Spiele. Eine Aktivität kann optional bewertet werden.
• Für Inhaltsanhänge ist keine Schüler- oder Studentenaufgabe erforderlich. Der Schüler/Student muss den Anhang nicht abgeben und er wird nicht benotet. Beispiele sind Fotos, Artikel und Videos.

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

Anmeldungen

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

Weitere Informationen