Mit Anhängen interagieren

Auf dieser Seite werden Implementierungsdetails zum Erstellen eines Anhangs, empfohlene Maßnahmen beim Öffnen von Anhängen durch Nutzer und die Arbeit mit Abgaben von Schülern und Studenten behandelt. Beachten Sie, dass Sie bei diesen Anfragen möglicherweise anhangbezogene Parameter angeben müssen.

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 Lehreransicht des Anhangs.
  • studentViewUri: der URI für die Schüler-/Studentenansicht des Anhangs.
  • studentWorkReviewUri: der URI, über den die Lehrkraft die Arbeit des Schülers/Studenten am Anhang sehen kann. Dieses Feld ist nur für Anhänge vom Typ „Aktivität“ erforderlich.

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

  • 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 Notenrückgabe unterstützen möchten. Gilt nur für Anhänge vom Typ „Aktivität“.

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

Anmeldedaten und Rolle des Nutzers validieren

Die iFrames für die Schüler-/Studentenansicht, die Überprüfung der Arbeit von Schülern/Studenten und die Lehreransicht iFrame sollen dem Nutzer Inhalte präsentieren und keine Classroom-Aufgabe ändern. Berücksichtigen Sie Folgendes, wenn eine dieser Ansichten geöffnet wird:

  • Rufen Sie OAuth-Anmeldedaten für den Nutzer ab.
  • Stellen Sie je nach itemType eine courseWork.getAddOnContext, courseWorkMaterials.getAddOnContext oder announcements.getAddOnContext Anfrage, um die Nutzerrolle zu validieren.
  • Prüfen Sie die Antwort, um festzustellen, ob TeacherContext oder StudentContext vorhanden sind. Es kann nur einer zurückgegeben werden, entsprechend der Rolle des Nutzers im Kurs.
  • Wenn der aktuelle Nutzer ein Schüler oder Student ist und der itemType courseWork ist, notieren Sie die submissionId aus der Antwort mit der Arbeit des Schülers/Studenten. Die submissionIds stimmen in allen Add-on-iFrames überein und sind erforderlich, um Noten zurückzugeben und Lehrkräften die Arbeit von Schülern/Studenten im Bewertungstool zu zeigen.
  • Wenn die attachmentId dem Add-on bereits bekannt ist, zeigen Sie die entsprechende UI für den Anhang an.
  • Andernfalls muss dieser Anhang aus einem anderen Stream-Element oder Kurs kopiert worden sein. Im Leitfaden zum Umgang mit kopierten Inhalten finden Sie Empfehlungen für dieses Szenario.

Details zur Abgabe von Schülern/Studenten

Ein typischer Abgabeworkflow umfasst die folgenden Schritte:

  1. Ein Schüler oder Student startet studentViewUri, um eine Aktivität abzuschließen.
  2. Das Add-on ruft mit den Anmeldedaten des Schülers/Studenten eine submissionId aus der Methode getAddOnContext ab.
  3. Die submissionId und attachmentId werden vom Add-on-Entwickler als eindeutige Kennung der Arbeit des Schülers/Studenten 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 für weitere Details.
  4. Eine Lehrkraft, die die Arbeit von Schülern/Studenten überprüfen 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 Arbeit des Schülers/Studenten abzurufen. Verwenden Sie den courses.courseWork.addOnAttachments.studentSubmissions Endpunkt, um Informationen zu einer Abgabe eines Schülers/Studenten abzurufen oder zu ändern.

Abgabestatus erkennen

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

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

Verwenden Sie diesen Endpunkt, um den Status der Arbeit des Schülers/Studenten in Ihrem Add-on zu erkennen. Anschließend können Sie die Ansichten oder Optionen, die dem Schüler/Studenten zur Verfügung stehen, je nach zurückgegebenem Status anpassen. Dazu gehören möglicherweise folgende Funktionen:

  • Anzeigen des Abgabestatus von Aufgaben in Ihrem Add-on. So können Schüler und Studenten potenzielle Verwirrung vermeiden und sicherstellen, dass sie eine Aufgabe nicht versehentlich nicht abgeben.
  • Einschränken der Berechtigungen zum Bearbeiten von Abgaben. Wenn die Aufgabe den Status CREATED oder RECLAIMED_BY_STUDENT hat, darf der Schüler/Student seine Abgabe möglicherweise bearbeiten. Wenn die Aufgabe den Status TURNED_IN oder RETURNED hat, darf der Schüler/Student seine Abgabe möglicherweise nicht bearbeiten.

Noten und mehrere Anhänge

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

Note für eine Abgabe festlegen

Sie können eine Abgabe eines Schülers/Studenten ändern, indem Sie eine PATCH Anfrage an den courses.courseWork.addOnAttachments.studentSubmissions Endpunkt senden. Der Anfragetext muss eine Instanz von AddOnAttachmentStudentSubmission mit den geänderten Werten enthalten. Legen Sie das Feld pointsEarned fest, um die Note einer Abgabe zu ändern. Der in pointsEarned übergebene Wert wird als Notenentwurf angezeigt, der für die Lehrkraft in der Classroom-UI sichtbar ist. Lehrkräfte können den Notenentwurf ändern, bevor sie die Aufgabe an die Schüler/Studenten zurückgeben. Weitere Informationen dazu, wie Noten Lehrkräften präsentiert werden, finden Sie unter Übersicht zur Bewertung in der Classroom-UI.

Sie können die Note nur 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 gewesen sein.

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

Wann eine Note festgelegt werden sollte

Sie haben einige Möglichkeiten, wann eine Note an Google Classroom zurückgegeben wird. Der entscheidende Unterschied besteht darin, ob Sie die Anmeldedaten der Lehrkraft speichern möchten, da nur die Lehrkraft eine Note ändern kann.

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

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

  • Nahtlose Notenaktualisierungen. Lehrkräfte müssen keine besonderen Maßnahmen ergreifen, damit Noten in der Classroom-UI angezeigt werden.
  • Echtzeitinformationen zum Fortschritt eines Kurses bei einer Aufgabe. Wenn Lehrkräfte Noten festlegen, während Schüler und Studenten Anhänge bearbeiten, können sie sich ein Bild vom Verständnis ihrer Schüler und Studenten machen, ohne jede Abgabe öffnen zu müssen.

Dieser Ansatz ermöglicht auch eine asynchrone Methode zur Notensynchronisierung. Sie können den Endpunkt AddOnAttachmentStudentSubmission regelmäßig abfragen, um festzustellen, wann ein Schüler/Student seine Arbeit eingereicht hat. Wenn die Arbeit eingereicht wurde, legen Sie die Note der Abgabe mit den gespeicherten Anmeldedaten fest.

Wenn Sie die Anmeldedaten der Lehrkraft nicht während einer Sitzung eines Schülers/Studenten laden möchten, können Sie die Anmeldedaten der aktiven Lehrkraft verwenden, wenn sie die Abgabe des Schülers/Studenten im iFrame zur Überprüfung der Arbeit von Schülern/Studenten lädt. Dies bietet jedoch möglicherweise keine besonders reibungslose Nutzererfahrung, da Noten in der Classroom-UI nicht in Echtzeit aktualisiert werden und Lehrkräfte das iFrame zur Überprüfung der Arbeit von Schülern/Studenten für jede Abgabe öffnen müssten.

Änderungen an den Noten für Aufgaben erkennen

Lehrkräfte können die Noteneinstellungen in Classroom bearbeiten, nachdem eine Aufgabe erstellt wurde. Solche Änderungen können Folgendes umfassen:

  • Ändern des zugewiesenen Punktwerts.
  • Ändern des Werts maxPoints einer Aufgabe.
  • Ändern, ob die Aufgabe überhaupt bewertet werden soll.

Um die aktuellen Bewertungseinstellungen einer Aufgabe zu sehen, empfehlen wir, eine GET Anfrage an den courses.courseWork Endpunkt zu senden. Die Antwort enthält den aktuellen Wert maxPoints. Eine nicht bewertete Aufgabe hat einen Wert maxPoints von null.

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