So funktionieren Anfragen

Auf dieser Seite erhalten Sie einen allgemeinen Überblick über die Funktionsweise von Anfragen in der Google Classroom API. Ziel ist es, Lesern zu helfen, die noch nicht mit dem ressourcenorientierten Design oder den Google Workspace APIs vertraut sind.

Spezifische Codebeispiele finden Sie in den entsprechenden API-Leitfäden, z. B. Kurse erstellen und verwalten oder Kursleistungen erstellen und verwalten.

Ressourcenorientiertes Design

Wie bereits unter API-Struktur erwähnt, folgt die Classroom API den Mustern des ressourcenorientierten Designs. Die meisten Ressourcen haben Methoden für Standardvorgänge wie das Erstellen, Lesen, Aktualisieren und Löschen von Instanzen der Ressource.

So ist es beispielsweise möglich, mit der API ein Classroom-Course zu create(), patch(), get(), list() und delete().

Erstellen

Wenn Sie eine neue Ressource wie eine Course erstellen möchten, rufen Sie die Methode create() für die entsprechende Ressource auf.

Für Create()-Aufrufe sind immer die ersten wichtigen Details der entsprechenden Ressource als Eingabe erforderlich. Wenn Sie beispielsweise eine Course erstellen möchten, rufen Sie die Methode create() für die Course-Ressource auf und geben Sie in der Anfrage die name und description sowie optionale Informationen wie die room an.

Für untergeordnete Ressourcen (manchmal auch als untergeordnete Ressourcen bezeichnet) sind auch Kennungen für die übergeordnete Ressource erforderlich. Wenn Sie beispielsweise eine CourseWork in einer Course erstellen, ist das Course id erforderlich, um festzustellen, zu welcher Course die CourseWork gehört.

Create()-Methoden geben in der API-Aufrufantwort eine Instanz der neu erstellten Ressource zurück. Die zurückgegebene Ressource enthält in der Regel zusätzliche, servergenerierte Felder, z. B. die Ressource id oder creationTime.

Patch

Wenn Sie vorhandene Ressourcen ändern möchten, rufen Sie die Methode patch() (manchmal auch update() genannt) für die entsprechende Ressource auf. Die Methode patch() ist fast identisch mit create(), mit zwei wichtigen Unterschieden: Beim Aufrufen der patch()-Methode müssen Sie Folgendes angeben:

1. Der id der zu ändernden Ressource.
2. Eine Liste von Feldern, die als updateMask bezeichnet wird, um festzulegen, welche Felder in der Ressource aktualisiert werden sollen. Dies ist optional, wenn es einen Standardsatz von Feldern gibt oder die Felder abgeleitet werden.

Tipp :Neben patch()-Methoden werden möglicherweise auch update()-Methoden angezeigt. Beide ändern eine Ressource, unterscheiden sich aber im Verhalten. Mit Update() wird eine Ressource vollständig durch eine neue ersetzt, während mit patch() nur ausgewählte Felder aktualisiert werden. Mit courses.update() wird beispielsweise eine gesamte vorhandene Course ersetzt, während mit courses.patch() die oben genannte fieldMask verwendet wird, um nur bestimmte Felder in der Course zu ändern. Aus Gründen der Einfachheit wird in der Google Classroom API fast ausschließlich patch() verwendet. Wir empfehlen Ihnen, diese Methode im Allgemeinen zu verwenden.

Patch()-Methoden geben die vollständige Instanz der aktualisierten Ressource in der API-Aufrufantwort zurück, wobei alle Änderungen abgeschlossen sind.

Abrufen und auflisten

Es gibt zwei Methoden zum Abrufen von Ressourcen: get() und list().

Mit der Methode get() wird eine bestimmte Ressource anhand einer Kennung abgerufen. Beispiel: Abrufen einer Course basierend auf id oder alias. Der get()-Aufruf gibt die vollständige Ressource direkt zurück.

Mit der list()-Methode werden mehrere Ressourcen desselben Typs in einer einzigen Anfrage abgerufen, ohne dass die einzelnen Ressourcen-IDs erforderlich sind. Häufig werden mit dem list()-Vorgang alle untergeordneten Ressourcen einer übergeordneten Ressource abgerufen, z. B. alle CourseWork in einer Course. Das ist nützlich, um Anfragen im Vergleich zu mehreren get()-Aufrufen zu minimieren. Das ist besonders wertvoll, wenn Sie die id der gewünschten Ressourcen nicht kennen.

list()-Methoden haben in der Regel eine maximale Anzahl von Ressourcen, die in einem einzelnen Aufruf zurückgegeben werden können. Niedrigere Grenzwerte können konfiguriert werden, indem ein pageSize-Wert in den Aufruf aufgenommen wird. Wenn es mehr Ressourcen als das Limit gibt, unterstützt die list()-Methode die Paginierung. Jede zurückgegebene „Seite“ mit Ergebnissen enthält ein pageToken, das in einem nachfolgenden list()-Aufruf enthalten sein kann, um den nächsten Satz von Ressourcen abzurufen.

Löschen

Die Methode delete() akzeptiert eine Ressourcen-ID wie id und löscht die entsprechende Ressource. Wenn die delete() erfolgreich ist, wird eine leere Antwort zurückgegeben.

Sonstige Vorgänge

Nicht alle mit der Classroom API möglichen Vorgänge können mit den oben genannten Standardvorgängen ausgeführt werden, z. B. die Änderung der zugewiesenen Personen einer CourseWork-Ressource. In diesen Fällen sind benutzerdefinierte Methoden wie die Methode modifyAssignees verfügbar. Das Verhalten dieser Methoden ist individuell und Sie sollten die jeweilige Dokumentation lesen.