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 Lehrenden für den Anhang.
• 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 einen Wert ungleich null haben, 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.

Wichtig :Wenn Sie PATCH-Anfragen senden, geben Sie auch die updateMask an. Der Wert von updateMask sollte eine durch Kommas getrennte Liste der zu ändernden Feldnamen sein.

Einreichungsstatus 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 oder Student seine Arbeit zurückgezogen hat.

Mit diesem Endpunkt können Sie den Status der Arbeit des Schülers oder Studenten in Ihrem Add-on 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 lassen. 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 oder Student seine Einreichung 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

Wichtig :Sie sollten Lehrkräften die Möglichkeit geben, beim Erstellen eines Anhangs die Übergabe von Noten zu aktivieren oder zu deaktivieren.

Zum Festlegen der Note für eine einzelne Aufgabe kann nur ein Add-on-Anhang verwendet werden. 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. Übersicht über die Benotung in der Classroom-Benutzeroberfläche

Warnung: Notenaktualisierungen in der Google Classroom-Benutzeroberfläche erfolgen nicht in Echtzeit. Es kann bis zu 30 Sekunden dauern, bis eine Note in Classroom angezeigt wird.

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 entscheidende Unterschied besteht darin, ob Sie die Anmeldedaten der Lehrkräfte speichern, da nur die Lehrkräfte eine Note ändern können.

Es gibt zwei Add-on-Momente, in denen Sie eine Note an Google Classroom senden können: wenn der Schüler oder Student seine Arbeit abschließt oder wenn die Lehrkraft die Arbeit des Schülers oder Studenten im IFrame für die Überprüfung der Schüler-/Studentenarbeit öffnet.

Wenn Sie Noten festlegen möchten, wenn der Schüler oder Student die Arbeit abgeschlossen hat, müssen Sie die Offline-Anmeldedaten einer Lehrkraft speichern und dann abrufen und verwenden, um die Note zu ändern, wenn der Schüler oder Student die Arbeit abgeschlossen hat. Diese Methode bietet einige potenzielle Vorteile:

• Sie können Noten nahtlos aktualisieren. Lehrkräfte müssen nichts weiter tun, damit Noten in der Classroom-Benutzeroberfläche angezeigt werden.
• Sie erhalten in Echtzeit Informationen zum 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 eine asynchrone Methode zur Benotungssynchronisierung ermöglicht. Sie können den AddOnAttachmentStudentSubmission-Endpunkt regelmäßig abfragen, um zu erkennen, wann ein Schüler oder Student seine Arbeit eingereicht hat. Nachdem die Aufgabe eingereicht wurde, legen Sie die Note mit den gespeicherten Anmeldedaten fest.

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

Wichtiger Hinweis: Prüfen Sie die aktuellen Benotungseinstellungen einer Aufgabe, bevor Sie die Note für eine Abgabe festlegen.

Lehrkräfte können die Benotungseinstellungen in Classroom bearbeiten, nachdem eine Aufgabe erstellt wurde. Dazu gehören:

• 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 den Wert „null“ oder „0“ für maxPoints.

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.