So funktionieren Anfragen

Auf dieser Seite wird ein allgemeiner Überblick über die Funktionsweise von Anfragen in der Google Classroom API gegeben. Ziel ist es, Lesern zu helfen, die noch nicht mit ressourcenorientiertem Design oder Google Workspace-APIs vertraut sind.

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

Ressourcenorientiertes Design

Wie unter API-Ressourcen beschrieben, folgt die Classroom API dem ressourcenorientierten Design. 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 create(), patch(), get(), list()} und delete() für einen Classroom-Course zu verwenden.

Erstellen

Wenn Sie eine neue Ressource wie 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 ein Course erstellen möchten, rufen Sie die Methode create() für die Ressource Course auf und geben Sie in der Anfrage name und description sowie optionale Informationen wie 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 innerhalb einer Course erstellen, ist die Course id erforderlich, um festzulegen, zu welcher Course die CourseWork gehört.

Create()-Methoden geben eine Instanz der neu erstellten Ressource in der API-Aufrufantwort zurück. Die zurückgegebene Ressource enthält in der Regel alle zusätzlichen, servergenerierten 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(), es gibt jedoch zwei wichtige Unterschiede: Wenn Sie die Methode patch() aufrufen, müssen Sie Folgendes angeben:

1. Die 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 :Möglicherweise sehen Sie update()-Methoden neben patch()-Methoden. Beide ändern eine Ressource, aber ihr Verhalten ist unterschiedlich. Mit Update() wird eine Ressource vollständig durch eine neue ersetzt, während mit patch() nur ausgewählte Felder aktualisiert werden. Beispiel: courses.update() ersetzt eine gesamte vorhandene Course, 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, diese Methode generell zu nutzen.

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

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 eines Course basierend auf id oder alias. Der get()-Aufruf gibt die vollständige Ressource direkt zurück.

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

Im Allgemeinen haben list()-Methoden eine maximale Anzahl von Ressourcen, die in einem einzelnen Aufruf zurückgegeben werden können. Untere 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 Methode list() die Paginierung. Jede „Seite“ mit Ergebnissen, die zurückgegeben wird, enthält ein pageToken, das in einen nachfolgenden list()-Aufruf aufgenommen werden kann, um den nächsten Batch von Ressourcen abzurufen.

Löschen

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

Andere 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. das Ändern der zugewiesenen Nutzer 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 Dokumentation für jede Methode einzeln lesen.