Mit Anhängen interagieren

Auf dieser Seite werden Implementierungsdetails zum Erstellen eines Anhangs, empfohlene Aktionen beim Öffnen von Anhängen durch Nutzer und die Arbeit mit Schülerarbeiten behandelt. Beachten Sie, dass Sie bei diesen Anfragen möglicherweise Parameter für Anhänge 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 eine Instanz von AddOnAttachment im Anfragetext 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üleransicht des Anhangs.
  • 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 die Anlage. Muss ein Wert ungleich null sein, wenn Sie die Notenrückübertragung unterstützen möchten. Gilt nur für Anhänge vom Typ „Aktivität“.

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

Nutzeranmeldedaten und Rolle validieren

Das iFrame für die Schüleransicht, das iFrame für die Überprüfung von Schülerarbeiten und das iFrame für die Lehreransicht sind alle dazu gedacht, dem Nutzer Inhalte zu präsentieren, anstatt eine Classroom-Aufgabe zu ändern. Wenn eine dieser Ansichten geöffnet wird, können Sie Folgendes tun:

  • OAuth-Anmeldedaten für den Nutzer abrufen
  • Stellen Sie eine courseWork.getAddOnContext-, courseWorkMaterials.getAddOnContext- oder announcements.getAddOnContext-Anfrage basierend auf itemType, um die Nutzerrolle zu validieren.
  • Prüfen Sie die Antwort, um festzustellen, ob TeacherContext oder StudentContext vorhanden sind. Es kann nur eine zurückgegeben werden, die der Rolle des Nutzers im Kurs entspricht.
  • Wenn der aktuelle Nutzer ein Schüler oder Student ist und itemType courseWork ist, erfassen Sie die submissionId aus der Antwort mit der Arbeit des Schülers oder Studenten. Der submissionIds muss in allen Add-on-iFrames übereinstimmen. Er ist erforderlich, um Noten zurückzugeben und Lehrkräften die Aufgaben von Schülern/Studenten im Benotungstool anzuzeigen.
  • Wenn die attachmentId dem Add-on bereits bekannt ist, wird die entsprechende Benutzeroberfläche für Anhänge angezeigt.
  • Andernfalls muss dieser Anhang aus einem anderen Stream-Element oder Kurs kopiert worden sein. Im Leitfaden Umgang mit kopierten Inhalten finden Sie Empfehlungen für dieses Szenario.

Details zu eingereichten Aufgaben von Schülern/Studenten

Ein typischer Einreichungsworkflow umfasst die folgenden Schritte:

  1. Ein Schüler startet studentViewUri, um eine Aktivität abzuschließen.
  2. Das Add-on ruft mit den Anmeldedaten des Schülers oder Studenten ein submissionId über die getAddOnContext-Methode ab.
  3. Die submissionId und attachmentId werden vom Add-on-Entwickler als eindeutige Kennung der Arbeit des Schülers gespeichert. Wenn ein Lehrer eine Aufgabe in Classroom kopiert, können Sie den zusammengesetzten Schlüssel dieser beiden Parameter verwenden, um in der kopierten Aufgabe einen neuen Anhang 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 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 Schülerarbeiten abzurufen. Mit dem Endpunkt courses.courseWork.addOnAttachments.studentSubmissions können Sie Informationen zu einer Schüler- oder Studentenarbeit abrufen oder ändern.

Einreichungsstatus erkennen

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

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

Mit diesem Endpunkt können Sie den Status der Arbeit des Schülers in Ihrem Add-on erkennen. Je nach zurückgegebenem Status können Sie dann die Ansichten oder Optionen anpassen, die dem Lernenden zur Verfügung stehen. Dazu können Funktionen wie die folgenden gehören:

  • 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 einreichen.
  • Berechtigungen zum Bearbeiten von Beiträgen einschränken Wenn die Aufgabe den Status CREATED oder RECLAIMED_BY_STUDENT hat, kann der Schüler oder Student seine Aufgabe möglicherweise bearbeiten. Wenn die Aufgabe den Status TURNED_IN oder RETURNED hat, darf der Schüler oder Student seine 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 mehr als einen Anhang vom Typ „Aktivität“ erstellt, der einen maxPoints-Wert enthält, kann nur mit dem ersten Anhang die Note für die Aufgabe festgelegt werden. Lassen Sie den Wert maxPoints entweder nicht festgelegt oder setzen Sie ihn auf null, um die Notenrückgabe für eine Anlage zu deaktivieren.

Note für eine Aufgabe festlegen

Sie können eine Schülerarbeit ä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 Aufgabe zu ändern. Der in pointsEarned übergebene Wert wird in der Classroom-Benutzeroberfläche als Entwurfsnote für den Lehrer angezeigt. Lehrkräfte können die Notenentwürfe ä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 über die Benotung in der Classroom-Benutzeroberfläche.

Sie können die Note mit pointsEarned nur 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 den maxPoints-Wert eines bereits erstellten AddOnAttachment ändern, indem Sie eine PATCH-Anfrage an den addOnAttachments-Endpunkt senden.

Wann eine Note festgelegt werden sollte

Sie haben die Möglichkeit, festzulegen, 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 oder Student seine Aufgabe abschließt oder wenn die Lehrkraft die Aufgabe des Schülers oder Studenten im iframe „Arbeiten von Schülern/Studenten überprüfen“ öffnet.

Wenn Sie Noten festlegen möchten, wenn der Schüler die Aufgabe erledigt hat, müssen Sie die Offline-Anmeldedaten eines Lehrers speichern und dann abrufen und verwenden, um die Note zu ändern, wenn der Schüler die Aufgabe erledigt hat. Diese Methode bietet einige potenzielle Vorteile:

  • Nahtlose Aktualisierung der Noten Lehrkräfte müssen keine besonderen Maßnahmen ergreifen, damit Noten in der Classroom-Benutzeroberfläche angezeigt werden.
  • Echtzeitinformationen zum Fortschritt einer Klasse bei einer Aufgabe bereitstellen Wenn Lehrkräfte Noten vergeben, während Schüler Anhänge bearbeiten, können sie sich ein Bild vom Verständnis der Schüler machen, ohne jede Aufgabe öffnen zu müssen.

Dieser Ansatz ermöglicht auch einen asynchronen Ansatz für die Synchronisierung von Noten. Sie können den AddOnAttachmentStudentSubmission-Endpunkt regelmäßig abfragen, um zu erkennen, wann ein Schüler oder Student seine Aufgabe eingereicht hat. Nachdem die Aufgabe eingereicht wurde, legen Sie die Note der Einreichung mit den gespeicherten Anmeldedaten fest.

Wenn Sie die Anmeldedaten der Lehrkraft nicht während einer Sitzung des Schülers/Studenten laden möchten, können Sie die Anmeldedaten der aktiven Lehrkraft verwenden, wenn sie die Arbeit des Schülers/Studenten im Student Work Review-iFrame lädt. Das ist jedoch möglicherweise nicht besonders nutzerfreundlich, da Noten in der Classroom-Benutzeroberfläche nicht in Echtzeit aktualisiert werden und Lehrkräfte den iframe „Student Work Review“ für jede Aufgabe öffnen müssten.

Änderungen bei den Noten für Aufgaben erkennen

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

  • Ändern der zugewiesenen Punktzahl.
  • Ändern des maxPoints-Werts einer Aufgabe.
  • Sie können ändern, ob die Aufgabe überhaupt benotet werden soll.

Wenn Sie die aktuellen Einstellungen für die Benotung einer Aufgabe aufrufen möchten, empfehlen wir, eine GET-Anfrage an den Endpunkt courses.courseWork zu senden. Die Antwort enthält den aktuellen Wert von maxPoints. Eine unbenotete Aufgabe hat einen NULL- oder 0-Wert für maxPoints.

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