Mit Anhängen interagieren

Auf dieser Seite werden Details zur Implementierung für das Erstellen von Anhängen und die Arbeit mit abgegebenen Aufgaben von Schülern/Studenten erläutert. Beachten Sie, dass Sie beim Senden dieser Anfragen möglicherweise anhangbezogene Parameter angeben müssen.

Anhang erstellen

Erstellen Sie einen Anhang. Senden Sie dazu eine CREATE-Anfrage an den entsprechenden Endpunkt courses.*.addOnAttachments.create. Der Anfragetext muss eine Instanz von AddOnAttachment enthalten.

Die folgenden Felder sind Pflichtfelder, wenn Sie einen Anhang erstellen:

  • title: der Stringname des Anhangs.
  • teacherViewUri: URI für die Lehrkraftansicht des Anhangs.
  • studentViewUri: URI für die Schüleransicht des Anhangs.
  • studentWorkReviewUri: URI für die Lehrkraft, um die Arbeit des Schülers/Studenten am Anhang zu sehen. Dieses Feld ist nur bei Anhängen des Typs „Aktivität“ erforderlich.

Sie können einige der folgenden optionalen Felder einfügen:

  • dueDate und dueTime, wenn angegeben wird, wann der Anhang fällig ist.
  • maxPoints: die höchste Note des Anhangs. Muss ein Wert ungleich null sein, wenn Sie die Notenrückgabe unterstützen möchten. Gilt nur für Aktivitätsanhänge.

Weitere Informationen zu diesen Feldern finden Sie in der Ressourcenreferenz zu AddOnAttachment.

Details zur abgegebenen Aufgabe des Schülers/Studenten

Ein typischer Arbeitsablauf für die Übermittlung umfasst die folgenden Schritte:

  1. Ein Schüler startet die studentViewUri, um eine Aktivität abzuschließen.
  2. Das Add-on ruft mit den Anmeldedaten von Studenten ein submissionId aus der Methode getAddOnContext ab.
  3. submissionId und attachmentId werden vom Add-on-Entwickler als eindeutige Kennzeichnung der Arbeit des Schülers gespeichert. Wenn eine Lehrkraft eine Aufgabe in Classroom kopiert, können Sie den zusammengesetzten Schlüssel dieser beiden Parameter verwenden, um einen neuen Anhang in der kopierten Aufgabe anzuzeigen. Weitere Informationen finden Sie auf unserer Seite zu kopierten Inhalten.
  4. Eine Lehrkraft, die sich die Aufgaben von Schülern/Studenten ansehen möchte, startet 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 Aufgabe von Schülern/Studenten abzurufen. Verwenden Sie den Endpunkt courses.courseWork.addOnAttachments.studentSubmissions, um Informationen zu einer abgegebenen Aufgabe von Schülern/Studenten abzurufen oder zu ändern.

Übermittlungsstatus erkennen

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

  • NEW, wenn der Schüler oder Student noch nie auf die abgegebene Aufgabe zugegriffen hat.
  • CREATED, wenn der Kursteilnehmer eine Aufgabe erstellt, aber noch nicht abgegeben hat.
  • TURNED_IN, wenn der Schüler/Student seine Aufgabe 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 oder Student seine Aufgabe zurückgezogen hat.

Mit diesem Endpunkt können Sie den Status der Aufgabe des Schülers/Studenten in Ihrem Add-on ermitteln. Anschließend können Sie die angezeigten Ansichten oder Optionen je nach zurückgegebenem Status anpassen. Dazu gehören unter anderem:

  • Den Abgabestatus von Aufgaben in Ihrem Add-on anzeigen. Auf diese Weise können Lernende potenzielle Verwirrung vermeiden und dafür sorgen, dass sie eine Aufgabe nicht versehentlich nicht abgeben.
  • Bearbeitungsberechtigungen für die Einreichung werden eingeschränkt. Wenn die Aufgabe den Status CREATED oder RECLAIMED_BY_STUDENT hat, darf der Schüler oder Student möglicherweise die abgegebene Aufgabe bearbeiten. Wenn die Aufgabe den Status TURNED_IN oder RETURNED hat, darf der Schüler oder Student die abgegebene Aufgabe 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 Aktivitätstypen mit einem maxPoints-Wert erstellt, kann nur der erste Anhang die Note einer Aufgabe festlegen. Lassen Sie den Wert maxPoints entweder nicht konfiguriert oder setzen Sie ihn auf null, um die Notenrückgabe für einen Anhang zu deaktivieren.

Note für abgegebene Aufgabe festlegen

Sie können die abgegebene Aufgabe eines Schülers/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 das Feld pointsEarned fest, um die Note einer abgegebenen Aufgabe zu ändern. Der in pointsEarned übergebene Wert wird zu einem Notenentwurf, den die Lehrkraft in der Classroom-UI sehen kann. Lehrkräfte können den Notenentwurf ändern, bevor sie die Aufgabe an die Schüler zurückgeben. Weitere Informationen dazu, wie Lehrkräften Noten angezeigt werden, finden Sie unter Überblick über die Benotung in der Classroom-Benutzeroberfläche.

Sie können die Note nur dann mit pointsEarned festlegen, wenn die folgenden 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 auch den maxPoints-Wert einer bereits erstellten AddOnAttachment ändern. Senden Sie dazu eine PATCH-Anfrage an den Endpunkt addOnAttachments.

Wann eine Note festgelegt werden sollte

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

Es gibt zwei zusätzliche Zeitpunkte, in denen Sie eine Benotung an Google Classroom übergeben können: wenn der Schüler/Student seine Arbeit erledigt oder die Lehrkraft die Aufgabe im iFrame für die Prüfung der Aufgaben von Schülern/Studenten öffnet.

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

  • Sie profitieren von nahtlosen Notenupdates. Es sind keine besonderen Maßnahmen erforderlich, damit die Noten in der Classroom-Benutzeroberfläche angezeigt werden.
  • Echtzeit-Einblicke in den Fortschritt eines Kurses durch eine Aufgabe. Indem sie Noten festlegen, während die Lernenden Anhänge ausfüllen, können Lehrkräfte einen Eindruck vom Verständnis ihrer Schüler gewinnen, ohne jede Aufgabe öffnen zu müssen.

Beachten Sie, dass dieser Ansatz auch einen asynchronen Ansatz für die Notensynchronisierung ermöglicht. Sie können den Endpunkt AddOnAttachmentStudentSubmission regelmäßig abfragen, um festzustellen, ob ein Schüler oder Student seine Aufgabe abgegeben hat. Nach dem Absenden legen Sie die Note für die abgegebene Aufgabe mit den gespeicherten Anmeldedaten fest.

Wenn Sie die Anmeldedaten der Lehrkraft während einer Sitzung nicht laden möchten, können Sie die Anmeldedaten der aktiven Lehrkraft verwenden, wenn diese die abgegebene Aufgabe des Schülers/Studenten in den iFrame für die Bewertung von Aufgaben von Schülern/Studenten lädt. Dies ist jedoch möglicherweise nicht besonders reibungslos, da die Noten in der Classroom-Benutzeroberfläche nicht in Echtzeit aktualisiert werden und die Lehrkräfte bei jeder Aufgabe den iFrame für die Bewertung von Aufgaben von Schülern/Studenten öffnen müssen.

Änderungen an Aufgabennoten erkennen

Lehrkräften die Möglichkeit, die Noteneinstellungen in Classroom zu bearbeiten, nachdem eine Aufgabe erstellt wurde. Beispiele für solche Änderungen:

  • Ändern der zugewiesenen Punktzahl.
  • maxPoints-Wert einer Zuweisung ändern
  • Ändern, ob die Aufgabe überhaupt benotet werden soll.

Wenn Sie sich die aktuellen Benotungseinstellungen einer Aufgabe ansehen möchten, senden Sie eine GET-Anfrage an den Endpunkt courses.courseWork. Die Antwort enthält den aktuellen Wert maxPoints. Eine unbenotete Aufgabe hat einen maxPoints-Wert von null oder null.

Wenn Sie eine Note an Classroom zurückgegeben haben, können Sie die Note für einen Add-on-Anhang über den Endpunkt courses.courseWork.addOnAttachments.studentSubmissions abrufen oder ändern. Der Notenwert wird mit dem Feld pointsEarned festgelegt. Prüfen Sie diesen Wert und aktualisieren Sie ihn bei Bedarf, wenn Ihr Produkt es Lehrkräften ermöglicht, die Punktzahl eines Schülers/Studenten für eine bestimmte Aktivität zu bearbeiten.