Noten und Rücksendungen von Anhängen

Dies ist die sechste Schritt-für-Schritt-Anleitung der Serie 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. Außerdem übergeben Sie eine Note programmatisch an Google Classroom, die im Notenbuch der Lehrkraft als Notenentwurf angezeigt wird.

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 jedem Anhang vom Typ „Aktivität“ 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.
• Es gibt zwei Ansätze, um die Note der abgegebenen Aufgabe mit den Anmeldedaten angemeldeter oder offline an Classroom zu übergeben.

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 UI zum Erstellen von Aufgaben mit drei Add-on-Anhangskarten, für die maxPoints festgelegt ist.

Mit der Classroom Add-ons API können Sie die Einstellungen konfigurieren und die Punktzahl für Noten für Anhänge festlegen. Diese sind nicht mit den Noten für die Aufgabe identisch. Die Noteneinstellungen für die Aufgabe richten sich jedoch nach den Noteneinstellungen für Anhänge, die auf der Karte mit dem Label Notensynchronisierung gekennzeichnet sind. Wenn im Anhang „Note synchronisieren“ pointsEarned für eine eingereichte Aufgabe 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, 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. Dies 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 eines Anhangs festlegen

In diesem Abschnitt wird beschrieben, wie Sie den Nennator für die Note eines Anhängens festlegen, also die maximal mögliche Punktzahl, die alle Schüler mit ihren Aufgaben erreichen können. Legen Sie dazu den Wert maxPoints des Anhangs fest.

Es sind nur geringfügige Änderungen an unserer bestehenden Implementierung erforderlich, um die Benotungsfunktionen nutzen zu können. 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 auch den Wert maxPoints in Ihrer lokalen Anhangsdatenbank. So müssen Sie bei der Benotung von abgegebenen Aufgaben nicht später einen 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 Endpunkt courses.courseWork, um den maxPoints-Wert auf Zuweisungsebene zu sehen. Geben Sie dazu itemId in das Feld CourseWork.id ein.

Aktualisieren Sie nun Ihr Datenbankmodell, damit es auch den Wert maxPoints des Anhangs enthält. 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 Karte „Anhang“ das Label „Benotung synchronisieren“ angezeigt wird und sich der Wert „Punkte“ der Aufgabe ändert.

Noten für abgegebene Aufgaben in Classroom festlegen

In diesem Abschnitt wird beschrieben, wie Sie den Zähler für die Note eines Anhangs festlegen. Das ist die Punktzahl eines einzelnen Schülers oder Studenten für den Anhang. Legen Sie dazu den Wert pointsEarned für abgegebene Aufgaben 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 oder Studenten den Bereich teacher nicht zuweisen. Dies kann zu unerwartetem Verhalten führen, wenn Schüler mit Ihrem Add-on interagieren und z. B. den iFrame der Lehrkräfteansicht anstelle des iFrames der Schüleransicht laden. Sie haben daher zwei Möglichkeiten, pointsEarned festzulegen:

• Mit den Anmeldedaten der angemeldeten Lehrkraft.
• (Offline) gespeicherte Anmeldedaten von Lehrkräften 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 eine 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 in 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.

Die Kombination dieser Faktoren bedeutet, dass Lehrkräfte möglicherweise erhebliche, zeitaufwändige manuelle Arbeit leisten müssen, um die Noten eines Kurses vollständig einzutragen.

Um diesen Ansatz zu implementieren, fügen Sie der bestehenden Route der Student Work Review einen zusätzlichen API-Aufruf hinzu.

Nachdem Sie die eingereichten Unterlagen und Anhänge abgerufen haben, bewerten Sie die abgegebenen Aufgaben des Schülers/Studenten und speichern Sie die daraus 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

Der zweite Ansatz zum Festlegen von Noten erfordert die Verwendung gespeicherter Anmeldedaten für die Lehrkraft, 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 der Lehrkräfte erfasst 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 bei diesem Ansatz den Zeitpunkt auswählen, an dem Sie Noten weitergeben möchten, z. B. wenn die Schüler oder Studenten die Aktivität abschließen 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 Datenbankeinträge für Anhänge, um eine Lehrkräfte-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 Tabellenschema User, damit es ein Zugriffstoken enthält:

# 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. Dafür gibt es 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.

Dieses Beispiel zeigt die letzte Option, da Sie Noten festlegen, wenn der Schüler oder Student eine Aktivität als Anhang fertiggestellt hat.

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))

Aktualisieren Sie dann den Code, mit dem ein Attachment-Eintrag erstellt oder aktualisiert wird, um auch die ID des Erstellers zu speichern:

# 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

Das Verfahren hier ist identisch mit dem bei der Verwendung der Anmeldedaten der angemeldeten Lehrkraft. 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 dies 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.