Mit Anhängen interagieren

Auf dieser Seite werden Implementierungsdetails zum Erstellen eines Anhangs und zum Arbeiten mit den Einreichungen von Schülern/Studenten erläutert. Möglicherweise müssen Sie bei diesen Anfragen Anhängeparameter angeben.

Anhang erstellen

Erstellen Sie einen Anhang, indem Sie eine CREATE-Anfrage an den entsprechenden courses.*.addOnAttachments.create-Endpunkt senden. Ihre Anfrage muss im Anfragetext eine Instanz von AddOnAttachment enthalten.

Die folgenden Felder sind beim Erstellen eines Anhangs erforderlich:

  • title: der Stringname des Anhangs.
  • teacherViewUri: der URI für die Ansicht des Anhangs für Lehrkräfte.
  • studentViewUri: der URI für die Ansicht des Anhangs für Schüler/Studenten.
  • studentWorkReviewUri: der URI, über den die Lehrkraft die Arbeit des Schülers oder Studenten im Anhang sehen kann. Dieses Feld ist nur für Anhänge vom Typ „Aktivität“ erforderlich.

Sie können einige der folgenden optionalen Felder angeben:

  • dueDate und dueTime, wenn Sie angeben, wann der Anhang fällig ist.
  • maxPoints: die maximale Note für den Anhang. Muss ein Wert ungleich Null sein, wenn Sie die Rückgabe von Noten unterstützen möchten. Gilt nur für Anhänge vom Typ „Aktivität“.

Weitere Informationen zu diesen Feldern finden Sie in der AddOnAttachment-Referenz.

Details zur Einreichung von Schülern/Studenten

Ein typischer Einreichungsablauf umfasst die folgenden Schritte:

  1. Ein Schüler startet die studentViewUri, um eine Aktivität abzuschließen.
  2. Das Add-on ruft mithilfe der Anmeldedaten der Schüler eine submissionId über die getAddOnContext-Methode ab.
  3. Die submissionId und attachmentId werden vom Add-on-Entwickler als eindeutige Kennung der Arbeit des Schülers oder Studenten gespeichert. Wenn eine Lehrkraft eine Aufgabe in Classroom kopiert, können Sie mit dem zusammengesetzten Schlüssel dieser beiden Parameter einen neuen Anhang in der kopierten Aufgabe anzeigen. Weitere Informationen finden Sie auf unserer Seite zu kopierten Inhalten.
  4. Eine Lehrkraft, die die Arbeit von Schülern/Studenten überprüfen möchte, startet die studentWorkReviewUri. Die Anfrage enthält die folgenden Abfrageparameter: courseId, itemId, itemType, attachmentId und submissionId.
  5. Der Add-on-Entwickler verwendet diese vier IDs, um die Arbeit der Schüler oder Studenten abzurufen. Verwenden Sie den Endpunkt courses.courseWork.addOnAttachments.studentSubmissions, um Informationen zu einer Einreichung von Schülern oder Studenten abzurufen oder zu ändern.

Abgabestatus erkennen

Senden Sie eine GET-Anfrage an den Endpunkt courses.courseWork.addOnAttachments.studentSubmissions, um Details zu einer bestimmten submissionId zu erhalten. Sie erhalten ein AddOnAttachmentStudentSubmission-Objekt, das die Note (pointsEarned) und den aktuellen Status (postSubmissionState) der Einreichung enthält. Der Status der Einreichung kann einen der folgenden Werte haben:

  • NEW, wenn der Schüler/Student noch nie auf die Aufgabe zugegriffen hat.
  • CREATED, wenn der Schüler/Student eine Aufgabe erstellt, aber noch nicht eingereicht hat.
  • TURNED_IN, wenn der Schüler oder die Schülerin seine oder ihre Arbeit an die Lehrkraft gesendet hat.
  • RETURNED, wenn die Lehrkraft die Aufgabe an den Schüler/Studenten zurückgegeben hat.
  • RECLAIMED_BY_STUDENT, wenn der Schüler/Student seine Aufgabe zurückgezogen hat.

Verwenden Sie diesen Endpunkt, um den Status der Aufgabe des Schülers/Studenten in Ihrem Add-on zu ermitteln. Je nach zurückgegebenem Status können Sie die Ansichten oder Optionen für den Schüler oder Studenten anpassen. Dazu gehören unter anderem:

  • Sie können den Abgabestatus von Aufgaben in Ihrem Add-on anzeigen. So können Schüler und Studenten mögliche Verwirrung vermeiden und dafür sorgen, dass sie eine Aufgabe nicht versehentlich nicht abgeben.
  • Berechtigungen zum Bearbeiten von Einreichungen einschränken Wenn die Aufgabe den Status CREATED oder RECLAIMED_BY_STUDENT hat, kann der Schüler/Student seine abgegebene Aufgabe möglicherweise bearbeiten. Wenn die Aufgabe den Status TURNED_IN oder RETURNED hat, darf der Schüler oder Student seine Einreichung möglicherweise nicht bearbeiten.

Noten und mehrere Anhänge

Es kann nur ein Add-on-Anhang verwendet werden, um die Note für eine einzelne Aufgabe festzulegen. Wenn eine Lehrkraft mehrere Anhänge vom Typ „Aktivität“ erstellt, die einen maxPoints-Wert enthalten, kann die Note für die Aufgabe nur für den ersten dieser Anhänge festgelegt werden. Lassen Sie den Wert für maxPoints entweder leer oder setzen Sie ihn auf null, um die Rückgabe von Noten für einen Anhang zu deaktivieren.

Note für eine Aufgabe festlegen

Sie können eine Einreichung eines Schülers oder Studenten ändern, indem Sie eine PATCH-Anfrage an den Endpunkt courses.courseWork.addOnAttachments.studentSubmissions senden. Der Anfragetext muss eine Instanz von AddOnAttachmentStudentSubmission mit den geänderten Werten enthalten. Legen Sie im Feld pointsEarned die Note für eine Einreichung fest. Der in pointsEarned übergebene Wert wird zu einer Note im Entwurfsstatus, die für die Lehrkraft in der Classroom-Benutzeroberfläche sichtbar ist. Lehrkräfte können die Notenentwürfe ändern, bevor sie die Aufgabe an die Schüler/Studenten zurückgeben. Ausführliche Informationen zur Darstellung von Noten für Lehrkräfte finden Sie unter Übersicht über die Benotung in der Classroom-Benutzeroberfläche.

Sie können die Note mit pointsEarned nur dann festlegen, wenn folgende Bedingungen erfüllt sind:

  • Der Anhang muss einen positiven maxPoints-Wert haben.
  • Das Add-on muss der ursprüngliche Ersteller des Anhangs sein.

Sie können den maxPoints-Wert eines bereits erstellten AddOnAttachment auch ändern, indem Sie eine PATCH-Anfrage an den addOnAttachments-Endpunkt senden.

Wann Sie eine Note festlegen sollten

Sie können festlegen, wann eine Note an Google Classroom zurückgegeben wird. Der wesentliche Unterschied besteht darin, ob Sie die Anmeldedaten der Lehrkraft speichern, da nur die Lehrkraft eine Note ändern kann.

Es gibt zwei Add-on-Momente, in denen Sie eine Note an Google Classroom weitergeben können: wenn der Schüler oder Student seine Aufgabe erledigt hat oder wenn die Lehrkraft die Aufgabe des Schülers im iFrame des Schülers/Studenten öffnet.

Wenn Sie Noten festlegen möchten, sobald der Schüler oder Student eine Aufgabe fertiggestellt hat, müssen Sie die Offlineanmeldedaten der Lehrkraft speichern und dann die Note abrufen und verwenden, um die Note zu ändern, wenn der Schüler oder Student die Aufgabe abgeschlossen hat. Diese Methode bietet einige potenzielle Vorteile:

  • Sorgen Sie für nahtlose Notenaktualisierungen. Lehrkräfte müssen keine besonderen Maßnahmen ergreifen, damit Noten in der Classroom-Benutzeroberfläche eingetragen werden.
  • Sie erhalten in Echtzeit einen Überblick über den Fortschritt der Klasse bei einer Aufgabe. Wenn Lehrkräfte Noten festlegen, während Schüler und Studenten Anhänge einreichen, können sie sich ein Bild davon machen, was die Schüler und Studenten verstanden haben, ohne jede einzelne Einreichung zu öffnen.

Beachten Sie, dass dieser Ansatz auch einen asynchronen Ansatz für die Benotung der Synchronisierung ermöglicht. Sie können den AddOnAttachmentStudentSubmission-Endpunkt regelmäßig abfragen, um zu erkennen, wann ein Schüler oder Student seine Arbeit eingereicht hat. Nach dem Einreichen können Sie anhand der gespeicherten Anmeldedaten die Note festlegen.

Wenn Sie die Anmeldedaten der Lehrkraft nicht während einer Sitzung eines Schülers oder Studenten laden möchten, können Sie die Anmeldedaten der aktiven Lehrkraft verwenden, wenn diese die Einreichung des Schülers oder Studenten im iframe für die Überprüfung der Schüler-/Studentenarbeit lädt. Dies ist jedoch möglicherweise nicht besonders nutzerfreundlich, da die Noten in der Classroom-Benutzeroberfläche nicht in Echtzeit aktualisiert werden und Lehrkräfte den Iframe für die Bewertung der Schüler-/Studentenarbeit für jede Einreichung öffnen müssen.

Änderungen an Noten für Aufgaben erkennen

Lehrkräfte können die Benotungseinstellungen in Classroom bearbeiten, nachdem eine Aufgabe erstellt wurde. Beispiele für Änderungen:

  • Die zugewiesene Punktzahl ändern.
  • Ändern Sie den Wert maxPoints einer Aufgabe.
  • Ändern, ob die Aufgabe überhaupt benotet werden soll.

Wenn Sie die aktuellen Benotungseinstellungen einer Aufgabe sehen möchten, senden Sie eine GET-Anfrage an den Endpunkt courses.courseWork. Die Antwort enthält den aktuellen Wert für maxPoints. Eine unbenotete Aufgabe hat einen maxPoints-Wert oder einen Nullwert.

Wenn Sie eine Note an Classroom zurückgegeben haben, können Sie mit dem Endpunkt courses.courseWork.addOnAttachments.studentSubmissions die Note für einen Add-on-Anhang abrufen oder ändern. Der Benotungswert wird mit dem Feld pointsEarned festgelegt. Prüfen und aktualisieren Sie diesen Wert, falls Lehrkräfte in Ihrem Produkt die Punktzahl eines Schülers oder Studenten für eine bestimmte Aktivität bearbeiten können.