Noten und Rücksendungen von Anhängen

Dies ist die sechste Schritt-für-Schritt-Anleitung in der Reihe zu Classroom-Add-ons.

In dieser Anleitung ändern Sie das Beispiel aus dem vorherigen Schritt der Anleitung, um einen Anhang vom Aktivitätstyp Benotet zu erstellen. Sie können eine Note auch programmatisch an Google Classroom zurückgeben. Sie wird dann im Notenbuch der Lehrkraft als Notenentwurf angezeigt.

Diese Schritt-für-Schritt-Anleitung unterscheidet sich geringfügig von anderen in dieser Reihe, da es zwei Möglichkeiten gibt, Noten an Classroom zurückzugeben. Beide haben unterschiedliche Auswirkungen auf die Nutzer- und Entwicklerfreundlichkeit. Berücksichtigen Sie beide Aspekte beim Entwerfen Ihres Classroom-Add-ons. Weitere Informationen zu den Implementierungsoptionen finden Sie im Leitfaden zur Interaktion mit Anhängen.

Die Benotungsfunktionen in der API sind optional. Sie können mit allen Anhängen vom Aktivitätstyp verwendet werden.

In dieser Anleitung führen Sie die folgenden Schritte aus:

• Ändern Sie die vorherigen Anfragen zum Erstellen von Anhängen an die Classroom API, um auch den Nenner der Note für das Anhang zu festlegen.
• Benoten Sie die Aufgabe des Schülers/Studenten programmatisch und legen Sie den Nenner der Note für den Anhang fest.
• Implementieren Sie zwei Ansätze, um die Note der Einreichung mithilfe von Anmeldedaten für angemeldete oder offline tätige Lehrkräfte an Classroom weiterzuleiten.

Nach Abschluss werden die Noten in der Classroom-Benotungsübersicht angezeigt, sobald das Passback-Verhalten ausgelöst wurde. Der genaue Zeitpunkt hängt vom Implementierungsansatz ab.

Verwenden Sie für dieses Beispiel die Aktivität aus der vorherigen Schritt-für-Schritt-Anleitung, in der ein Schüler ein Bild eines berühmten Wahrzeichens sieht und aufgefordert wird, den Namen einzugeben. Weisen Sie dem Anhang die volle Punktzahl zu, wenn der Schüler oder Student den richtigen Namen eingibt, andernfalls null.

Benotungsfunktion der Classroom Add-ons API

Ihr Add-on kann sowohl den Nenner als auch den Zähler der Note für einen Anhang festlegen. Sie werden jeweils mit den Werten pointsEarned und maxPoints in der API festgelegt. Auf einer Anhängekarte in der Classroom-Benutzeroberfläche wird der maxPoints-Wert angezeigt, wenn er festgelegt wurde.

Abbildung 1. Die Benutzeroberfläche zum Erstellen von Aufgaben mit drei Add-on-Anhängekarten, für die maxPoints festgelegt ist.

Mit der Classroom Add-ons API können Sie die Einstellungen für die Noten für Anhänge konfigurieren und die erzielte Punktzahl festlegen. Diese sind nicht mit den Noten für die Aufgabe identisch. Die Einstellungen für die Benotung der Aufgabe folgen jedoch den Einstellungen für die Benotung des Anhangs, der auf der Anhangskarte das Label Benotung synchronisieren hat. Wenn im Anhang „Note synchronisieren“ pointsEarned für die Einreichung eines Schülers oder Studenten festgelegt wird, wird auch die Note des Schülers oder Studenten für die Aufgabe als Entwurf festgelegt.

Normalerweise erhält der erste Anhang, der der Aufgabe hinzugefügt wurde, die maxPoints festlegt, das Label „Notensynchronisierung“. Ein Beispiel für das Label „Benotungssynchronisierung“ finden Sie in Abbildung 1. Beachten Sie, dass die Karte „Anhang 1“ das Label „Benotung synchronisieren“ hat und dass die Note für die Aufgabe im roten Feld auf 50 Punkte aktualisiert wurde. Beachten Sie auch, dass in Abbildung 1 zwar drei Anhängekarten zu sehen sind, aber nur eine Karte das Label „Benotungssynchronisierung“ hat. Das ist eine wichtige Einschränkung der aktuellen Implementierung: Nur ein Anhang kann das Label „Notensynchronisierung“ haben.

Wenn es mehrere Anhänge gibt, für die maxPoints festgelegt wurde, wird die Option „Benotungssynchronisierung“ nicht für die verbleibenden Anhänge aktiviert, wenn Sie den Anhang mit der Benotungssynchronisierung entfernen. Wenn Sie einen weiteren Anhang hinzufügen, der maxPoints festlegt, wird die Benotungssynchronisierung für den neuen Anhang aktiviert und die maximale Note für die Aufgabe wird entsprechend angepasst. Es gibt keinen Mechanismus, mit dem Sie programmatisch sehen können, welcher Anhang das Label „Benotungssynchronisierung“ hat oder wie viele Anhänge eine bestimmte Aufgabe hat.

Maximale Note für einen Anhang festlegen

In diesem Abschnitt wird beschrieben, wie Sie den Nenner für die Note für einen Anhang festlegen, also die maximal mögliche Punktzahl, die alle Schüler/Studenten für ihre Einreichungen erreichen können. Legen Sie dazu den maxPoints-Wert des Anhangs fest.

Es ist nur eine kleine Änderung an unserer bestehenden Implementierung erforderlich, um die Benotungsfunktionen zu aktivieren. Fügen Sie beim Erstellen eines Anhangs den Wert maxPoints in dasselbe AddOnAttachment-Objekt ein, das die Felder studentWorkReviewUri, teacherViewUri und andere Anhangsfelder enthält.

Die Standardpunktzahl für eine neue Aufgabe ist 100. Wir empfehlen, maxPoints auf einen anderen Wert als 100 festzulegen, damit Sie prüfen können, ob die Noten richtig festgelegt werden. Legen Sie maxPoints beispielhaft auf 50 fest:

attachment = {
    # Specifies the route for a teacher user.
    "teacherViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True),
    },
    # Specifies the route for a student user.
    "studentViewUri": {
        "uri":
            flask.url_for(
                "load_activity_attachment",
                _scheme='https',
                _external=True)
    },
    # Specifies the route for a teacher user when the attachment is
    # loaded in the Classroom grading view.
    "studentWorkReviewUri": {
        "uri":
            flask.url_for(
                "view_submission", _scheme='https', _external=True)
    },
    # Sets the maximum points that a student can earn for this activity.
    # This is the denominator in a fractional representation of a grade.
    "maxPoints": 50,
    # The title of the attachment.
    "title": f"Attachment {attachment_count}",
}

Für diese Demonstration speichern Sie den Wert maxPoints auch in Ihrer lokalen Datenbank für Anhänge. So müssen Sie später beim Benoten der Einreichungen der Schüler/Studenten keinen zusätzlichen API-Aufruf ausführen. Beachten Sie jedoch, dass Lehrkräfte die Einstellungen für die Benotungsskala von Aufgaben unabhängig von Ihrem Add-on ändern können. Senden Sie eine GET-Anfrage an den courses.courseWork-Endpunkt, um den maxPoints-Wert auf Aufgabenebene aufzurufen. Geben Sie dazu itemId in das Feld CourseWork.id ein.

Aktualisieren Sie nun Ihr Datenbankmodell, damit auch der maxPoints-Wert des Anhangs enthalten ist. Wir empfehlen, den Wert maxPoints aus der Antwort CREATE zu verwenden:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    # Store the maxPoints value returned in the response.
    max_points=int(resp.get("maxPoints")))
db.session.add(new_attachment)
db.session.commit()

Der Anhang hat jetzt die höchste Note. Sie sollten dieses Verhalten jetzt testen können. Fügen Sie einer neuen Aufgabe einen Anhang hinzu und achten Sie darauf, dass auf der Anhangskarte das Label „Benotung synchronisieren“ angezeigt wird und sich der Wert „Punkte“ der Aufgabe ändert.

Note für die Einreichung eines Schülers oder Studenten in Classroom festlegen

In diesem Abschnitt wird beschrieben, wie Sie den Nenner für die Note für einen Anhang festlegen, also die Punktzahl eines einzelnen Schülers oder Studenten für den Anhang. Legen Sie dazu den Wert pointsEarned für die Einreichung eines Schülers fest.

Sie müssen jetzt eine wichtige Entscheidung treffen: Wie sollte Ihr Add-on einen Antrag zum Festlegen von pointsEarned stellen?

Das Problem ist, dass für die Einstellung pointsEarned der OAuth-Bereich teacher erforderlich ist. Sie sollten Schülern und Studenten keine Berechtigung vom Typ teacher gewähren. Andernfalls kann es zu unerwartetem Verhalten kommen, wenn Schüler und Studenten mit Ihrem Add-on interagieren, z. B. zum Laden des Iframes für die Ansicht des Lehrkräfte statt des Iframes für die Ansicht der Schüler. Sie haben also zwei Möglichkeiten, pointsEarned festzulegen:

• Anmeldedaten des angemeldeten Lehrers verwenden
• Gespeicherte (offline) Anmeldedaten für Lehrkräfte verwenden

In den folgenden Abschnitten werden die Vor- und Nachteile der einzelnen Ansätze erläutert, bevor die einzelnen Implementierungen demonstriert werden. In den Beispielen wird beide Methoden zur Weitergabe einer Note an Classroom veranschaulicht. In den sprachspezifischen Anleitungen unten erfahren Sie, wie Sie bei der Ausführung der Beispiele eine Methode auswählen:

Noten mit den Anmeldedaten der angemeldeten Lehrkraft festlegen

Verwenden Sie die Anmeldedaten des angemeldeten Nutzers, um die Anfrage zum Festlegen von pointsEarned zu senden. Das sollte ziemlich intuitiv erscheinen, da es dem Rest der bisherigen Implementierung entspricht und nur wenig Aufwand erfordert.

Beachten Sie jedoch, dass die Lehrkraft nur im IFrame für die Überprüfung der Schüler-/Studentenarbeit mit der Einreichung des Schülers/Studenten interagiert. Das hat einige wichtige Auswirkungen:

• In Classroom werden erst dann Noten angezeigt, wenn die Lehrkraft in der Classroom-Benutzeroberfläche eine entsprechende Aktion ausführt.
• Eine Lehrkraft muss möglicherweise jede Einreichung eines Schülers oder Studenten öffnen, um alle Noten eintragen zu können.
• Zwischen dem Empfang der Note in Classroom und ihrer Darstellung auf der Classroom-Benutzeroberfläche kann es zu einer kurzen Verzögerung kommen. Die Verzögerung beträgt in der Regel fünf bis zehn Sekunden, kann aber auch bis zu 30 Sekunden dauern.

Aufgrund dieser Faktoren müssen Lehrkräfte möglicherweise erhebliche, zeitaufwendige manuelle Arbeit leisten, um die Noten eines Kurses vollständig zu erfassen.

Um diesen Ansatz zu implementieren, fügen Sie Ihrer bestehenden Route für die Überprüfung von Schüler-/Studentenarbeiten einen weiteren API-Aufruf hinzu.

Nachdem Sie die Einreichungs- und Anhangsdatensätze des Schülers oder Studenten abgerufen haben, bewerten Sie die Einreichung und speichern Sie die resultierende Note. Legen Sie die Note im Feld pointsEarned eines AddOnAttachmentStudentSubmission-Objekts fest. Senden Sie abschließend eine PATCH-Anfrage an den courses.courseWork.addOnAttachments.studentSubmissions-Endpunkt mit der AddOnAttachmentStudentSubmission-Instanz im Anfragetext. Beachten Sie, dass wir auch pointsEarned im updateMask in unserer PATCH-Anfrage angeben müssen:

# Look up the student's submission in our database.
student_submission = Submission.query.get(flask.session["submissionId"])

# Look up the attachment in the database.
attachment = Attachment.query.get(student_submission.attachment_id)

grade = 0

# See if the student response matches the stored name.
if student_submission.student_response.lower(
) == attachment.image_caption.lower():
    grade = attachment.max_points

# Create an instance of the Classroom service.
classroom_service = ch._credential_handler.get_classroom_service()

# Build an AddOnAttachmentStudentSubmission instance.
add_on_attachment_student_submission = {
    # Specifies the student's score for this attachment.
    "pointsEarned": grade,
}

# Issue a PATCH request to set the grade numerator for this attachment.
patch_grade_response = classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Noten mithilfe von Offline-Anmeldedaten für Lehrkräfte festlegen

Für den zweiten Ansatz zum Festlegen von Noten müssen gespeicherte Anmeldedaten für die Lehrkraft verwendet werden, die den Anhang erstellt hat. Für diese Implementierung müssen Sie Anmeldedaten mit den Aktualisierungs- und Zugriffstokens eines zuvor autorisierten Lehrers erstellen und dann diese Anmeldedaten verwenden, um pointsEarned festzulegen.

Ein wichtiger Vorteil dieses Ansatzes ist, dass Noten in der Classroom-Benutzeroberfläche ohne Aktion des Lehrkräfte hinzugefügt werden. So lassen sich die oben genannten Probleme vermeiden. Das Ergebnis ist, dass die Endnutzer die Benotung als nahtlos und effizient empfinden. Außerdem können Sie mit diesem Ansatz festlegen, wann Sie die Noten zurückgeben, z. B. wenn die Schüler oder Studenten die Aktivität abgeschlossen haben oder asynchron.

Führen Sie die folgenden Aufgaben aus, um diesen Ansatz zu implementieren:

1. Ändern Sie die Datensätze der Nutzerdatenbank, um ein Zugriffstoken zu speichern.
2. Ändern Sie die Datensätze der Datenbank „Anhang“, um eine Lehrer-ID zu speichern.
3. Rufen Sie die Anmeldedaten der Lehrkraft ab und erstellen Sie (optional) eine neue Classroom-Dienstinstanz.
4. Geben Sie die Note für eine Aufgabe ein.

Legen Sie für diese Demonstration die Note fest, wenn der Schüler/Student die Aktivität abgeschlossen hat, also wenn er das Formular im Pfad „Student View“ (Ansicht für Schüler/Studenten) einreicht.

Nutzerdatenbankeinträge zum Speichern des Zugriffstokens ändern

Für API-Aufrufe sind zwei eindeutige Tokens erforderlich: das Aktualisierungstoken und das Zugriffstoken. Wenn Sie der Anleitungsreihe bis hierher gefolgt sind, sollte in Ihrem User-Tabellenschema bereits ein Aktualisierungstoken gespeichert sein. Das Speichern des Aktualisierungstokens ist ausreichend, wenn Sie nur API-Aufrufe mit dem angemeldeten Nutzer ausführen, da Sie im Rahmen des Authentifizierungsablaufs ein Zugriffstoken erhalten.

Sie müssen jetzt jedoch Aufrufe als eine andere Person als den angemeldeten Nutzer ausführen, d. h. der Authentifizierungsablauf ist nicht verfügbar. Daher müssen Sie das Zugriffstoken zusammen mit dem Aktualisierungstoken speichern. Aktualisieren Sie das User-Tabellenschema, um ein Zugriffstoken einzubinden:

# Database model to represent a user.
class User(db.Model):
    # The user's identifying information:
    id = db.Column(db.String(120), primary_key=True)
    display_name = db.Column(db.String(80))
    email = db.Column(db.String(120), unique=True)
    portrait_url = db.Column(db.Text())

    # The user's refresh token, which will be used to obtain an access token.
    # Note that refresh tokens will become invalid if:
    # - The refresh token has not been used for six months.
    # - The user revokes your app's access permissions.
    # - The user changes passwords.
    # - The user belongs to a Google Cloud organization
    #   that has session control policies in effect.
    refresh_token = db.Column(db.Text())

    # An access token for this user.
    access_token = db.Column(db.Text())

Aktualisieren Sie dann den Code, der einen User-Eintrag erstellt oder aktualisiert, sodass auch das Zugriffstoken gespeichert wird:

def save_credentials_to_storage(self, credentials):
    # Issue a request for the user's profile details.
    user_info_service = googleapiclient.discovery.build(
        serviceName="oauth2", version="v2", credentials=credentials)
    user_info = user_info_service.userinfo().get().execute()
    flask.session["username"] = user_info.get("name")
    flask.session["login_hint"] = user_info.get("id")

    # See if we have any stored credentials for this user. If they have used
    # the add-on before, we should have received login_hint in the query
    # parameters.
    existing_user = self.get_credentials_from_storage(user_info.get("id"))

    # If we do have stored credentials, update the database.
    if existing_user:
        if user_info:
            existing_user.id = user_info.get("id")
            existing_user.display_name = user_info.get("name")
            existing_user.email = user_info.get("email")
            existing_user.portrait_url = user_info.get("picture")

        if credentials and credentials.refresh_token is not None:
            existing_user.refresh_token = credentials.refresh_token
            # Update the access token.
            existing_user.access_token = credentials.token

    # If not, this must be a new user, so add a new entry to the database.
    else:
        new_user = User(
            id=user_info.get("id"),
            display_name=user_info.get("name"),
            email=user_info.get("email"),
            portrait_url=user_info.get("picture"),
            refresh_token=credentials.refresh_token,
            # Store the access token as well.
            access_token=credentials.token)

        db.session.add(new_user)

    db.session.commit()

Datenbankeinträge für Anhänge ändern, um eine Lehrer-ID zu speichern

Wenn Sie eine Note für eine Aktivität festlegen möchten, müssen Sie pointsEarned als Lehrkraft im Kurs festlegen. Dazu haben Sie mehrere Möglichkeiten:

• Speichern Sie eine lokale Zuordnung der Anmeldedaten von Lehrkräften zu Kurs-IDs. Beachten Sie jedoch, dass nicht immer dieselbe Lehrkraft mit einem bestimmten Kurs verknüpft ist.
• Stellen Sie GET-Anfragen an den courses-Endpunkt der Classroom API, um die aktuellen Lehrkräfte abzurufen. Anschließend werden lokale Nutzerdatensätze abgefragt, um übereinstimmende Anmeldedaten für Lehrkräfte zu finden.
• Speichern Sie beim Erstellen eines Add-on-Anhangs eine Lehrkraft-ID in der lokalen Datenbank für Anhänge. Rufe dann die Anmeldedaten der Lehrkraft aus dem attachmentId ab, das an den IFrame der Schüleransicht übergeben wurde.

In diesem Beispiel wird die letzte Option veranschaulicht, da Sie Noten festlegen, wenn der Schüler oder Student einen Aktivitäts-Anhang abschließt.

Fügen Sie der Tabelle Attachment Ihrer Datenbank ein Feld für die Lehrer-ID hinzu:

# Database model to represent an attachment.
class Attachment(db.Model):
    # The attachmentId is the unique identifier for the attachment.
    attachment_id = db.Column(db.String(120), primary_key=True)

    # The image filename to store.
    image_filename = db.Column(db.String(120))

    # The image caption to store.
    image_caption = db.Column(db.String(120))

    # The maximum number of points for this activity.
    max_points = db.Column(db.Integer)

    # The ID of the teacher that created the attachment.
    teacher_id = db.Column(db.String(120))

Aktualisiere dann den Code, der einen Attachment-Eintrag erstellt oder aktualisiert, sodass auch die ID des Erstellers gespeichert wird:

# Store the attachment by id.
new_attachment = Attachment(
    # The new attachment's unique ID, returned in the CREATE response.
    attachment_id=resp.get("id"),
    image_filename=key,
    image_caption=value,
    max_points=int(resp.get("maxPoints")),
    teacher_id=flask.session["login_hint"])
db.session.add(new_attachment)
db.session.commit()

Anmeldedaten der Lehrkraft abrufen

Suchen Sie die Route, über die der iFrame für die Schüler-/Studentenansicht ausgeliefert wird. Rufen Sie unmittelbar nach dem Speichern der Antwort des Schülers in Ihrer lokalen Datenbank die Anmeldedaten des Lehrers aus Ihrem lokalen Speicher ab. Das sollte aufgrund der Vorbereitung in den beiden vorherigen Schritten ganz einfach sein. Sie können damit auch eine neue Instanz des Classroom-Dienstes für den Nutzer „Lehrkraft“ erstellen:

# Create an instance of the Classroom service using the tokens for the
# teacher that created the attachment.

# We're assuming that there are already credentials in the session, which
# should be true given that we are adding this within the Student View
# route; we must have had valid credentials for the student to reach this
# point. The student credentials will be valid to construct a Classroom
# service for another user except for the tokens.
if not flask.session.get("credentials"):
    raise ValueError(
        "No credentials found in session for the requested user.")

# Make a copy of the student credentials so we don't modify the original.
teacher_credentials_dict = deepcopy(flask.session.get("credentials"))

# Retrieve the requested user's stored record.
teacher_record = User.query.get(attachment.teacher_id)

# Apply the user's tokens to the copied credentials.
teacher_credentials_dict["refresh_token"] = teacher_record.refresh_token
teacher_credentials_dict["token"] = teacher_record.access_token

# Construct a temporary credentials object.
teacher_credentials = google.oauth2.credentials.Credentials(
    **teacher_credentials_dict)

# Refresh the credentials if necessary; we don't know when this teacher last
# made a call.
if teacher_credentials.expired:
    teacher_credentials.refresh(Request())

# Request the Classroom service for the specified user.
teacher_classroom_service = googleapiclient.discovery.build(
    serviceName=CLASSROOM_API_SERVICE_NAME,
    version=CLASSROOM_API_VERSION,
    credentials=teacher_credentials)

Note für eine Aufgabe festlegen

Die weitere Vorgehensweise entspricht der mit den Anmeldedaten des angemeldeten Lehrkräften. Sie sollten den Aufruf jedoch mit den Anmeldedaten des Lehrers ausführen, die Sie im vorherigen Schritt abgerufen haben:

# Issue a PATCH request as the teacher to set the grade numerator for this
# attachment.
patch_grade_response = teacher_classroom_service.courses().courseWork(
).addOnAttachments().studentSubmissions().patch(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    attachmentId=flask.session["attachmentId"],
    submissionId=flask.session["submissionId"],
    # updateMask is a list of fields being modified.
    updateMask="pointsEarned",
    body=add_on_attachment_student_submission).execute()

Add-on testen

Erstellen Sie als Lehrkraft eine Aufgabe mit einem Anhang vom Typ „Aktivität“, reichen Sie als Schüler/Student eine Antwort ein und öffnen Sie die Einreichung dann im IFrame für die Überprüfung der Schüler-/Studentenarbeit. Je nach Implementierungsansatz sollte die Note zu unterschiedlichen Zeiten angezeigt werden:

• Wenn Sie eine Note zurückgegeben haben, als der Schüler oder Student die Aktivität abgeschlossen hat, sollte die Note bereits in der Benutzeroberfläche angezeigt werden, bevor Sie den IFrame für die Bewertung der Schüler-/Studentenarbeit öffnen. Sie sehen sie auch in der Schüler-/Studentenliste, wenn Sie die Aufgabe öffnen, und im Feld „Note“ neben dem IFrame für die Überprüfung der Schüler-/Studentenarbeit.
• Wenn Sie sich dafür entschieden haben, eine Note zurückzugeben, wenn die Lehrkraft den Iframe „Aufgaben von Schülern/Studenten überprüfen“ öffnet, sollte die Note kurz nach dem Laden des Iframes im Feld „Note“ angezeigt werden. Wie oben erwähnt, kann das bis zu 30 Sekunden dauern. Danach sollte die Note für den jeweiligen Schüler/Studenten auch in den anderen Ansichten des Classroom-Notenbuchs angezeigt werden.

Prüfen Sie, ob die richtige Punktzahl für den Schüler oder Studenten angezeigt wird.

Glückwunsch! Sie können mit dem nächsten Schritt fortfahren: Anhänge außerhalb von Google Classroom erstellen.