Noten und Rücksendungen von Anhängen

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

In dieser Schritt-für-Schritt-Anleitung ändern Sie das Beispiel aus der vorherigen Schritt-für-Schritt-Anleitung, um einen benoteten Anhang des Aktivitätstyps 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 derzeit zwei mögliche Ansätze für die Weitergabe von Noten an Classroom gibt. Beide haben unterschiedliche Auswirkungen auf die Entwickler- und die Nutzerfreundlichkeit. Berücksichtigen Sie beim Entwerfen des Classroom-Add-ons beide Optionen. Weitere Informationen zu den Implementierungsoptionen finden Sie auf der Seite Mit Anhängen interagieren.

Die Benotungsfunktionen in der API sind optional. Sie können mit jedem Aktivitätstyp-Anhang verwendet werden.

Im Verlauf dieser Schritt-für-Schritt-Anleitung führen Sie folgende Schritte aus:

• Ändern Sie die vorherigen Anfragen zum Erstellen von Anhängen an die Classroom API, um auch die maximale Punktzahl des Anhangs festzulegen.
• Benoten Sie die abgegebene Aufgabe des Schülers/Studenten programmatisch und legen Sie den Notenzähler des Anhangs fest.
• Es gibt zwei Ansätze, um die Note der abgegebenen Aufgabe mit den Anmeldedaten angemeldeter oder offline an Classroom zu übergeben.

Nach Abschluss des Vorgangs werden die Noten im Classroom-Notenbuch angezeigt, sobald das Rücksendungsverhalten ausgelöst wurde. Der genaue Moment, in dem dies geschieht, hängt vom jeweiligen Implementierungsansatz ab.

Verwenden Sie für dieses Beispiel die Aktivität aus der vorherigen Schritt-für-Schritt-Anleitung, in der einem Schüler ein Bild einer berühmten Sehenswürdigkeit gezeigt wird und er aufgefordert wird, den Namen einzugeben. Wenn der Schüler oder Student den richtigen Namen eingibt, weisen Sie dem Anhang vollständige Markierungen zu, andernfalls null.

Informationen zur Benotungsfunktion der Classroom Add-ons API

Mit dem Add-on können Sie bei einem Anhang sowohl den Notenzähler als auch die maximale Punktzahl festlegen. Diese werden jeweils mit den Werten pointsEarned und maxPoints in der API festgelegt. Eine Karte für Anhänge in der Classroom-Benutzeroberfläche zeigt den Wert maxPoints an, wenn dieser 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 durch den Anhang „Notensynchronisierung“ pointsEarned für die abgegebene Aufgabe eines Schülers/Studenten festgelegt wird, wird auch der Notenentwurf des Schülers/Studenten für die Aufgabe festgelegt.

Normalerweise erhält der erste Anhang, der der Aufgabe, die maxPoints festlegt, das Label „Notensynchronisierung“. In Abbildung 1 sehen Sie ein Beispiel für das Label „Notensynchronisierung“. Die Karte „Anhang 1“ hat das Label „Notensynchronisierung“ und die Note im roten Feld wurde auf 50 Punkte aktualisiert. In Abbildung 1 sind zwar drei Anhangskarten zu sehen, aber nur eine hat das Label „Notensynchronisierung“. Dies ist eine wichtige Einschränkung der aktuellen Implementierung: Nur ein Anhang kann das Label „Notensynchronisierung“ haben.

Wenn für mehrere Anhänge maxPoints festgelegt ist und der Anhang mit „Notensynchronisierung“ entfernt wird, wird die Notensynchronisierung für die verbleibenden Anhänge nicht aktiviert. Wenn Sie einen weiteren Anhang hinzufügen, mit dem maxPoints festgelegt wird, wird die Notensynchronisierung für den neuen Anhang aktiviert. Außerdem wird die maximale Note für eine Aufgabe entsprechend angepasst. Es gibt keinen Mechanismus, um programmatisch zu sehen, welcher Anhang das Label „Notensynchronisierung“ hat, oder um festzustellen, wie viele Anhänge eine bestimmte Aufgabe hat.

Maximale Note eines Anhangs festlegen

In diesem Abschnitt wird beschrieben, wie Sie den Denominator 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 im selben AddOnAttachment-Objekt ein, das studentWorkReviewUri, teacherViewUri und andere Anhangsfelder enthält.

Beachten Sie, dass die Standardhöchstpunktzahl für neue Aufgaben 100 beträgt. Wir empfehlen, maxPoints auf einen anderen Wert als 100 zu setzen, damit Sie prüfen können, ob die Noten korrekt festgelegt sind. Legen Sie zur Veranschaulichung maxPoints 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. Es ist jedoch möglich, dass Lehrkräfte die Noteneinstellungen für Aufgaben unabhängig von Ihrem Add-on ändern. Senden Sie eine GET-Anfrage an den Endpunkt courses.courseWork, um den maxPoints-Wert auf Zuweisungsebene zu sehen. Übergeben Sie dabei itemId im Feld CourseWork.id.

Aktualisieren Sie nun Ihr Datenbankmodell, damit es auch den Wert maxPoints des Anhangs enthält. Wir empfehlen, den Wert maxPoints aus der CREATE-Antwort 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 eine maximale 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 des Anhangs das Label „Notensynchronisierung“ angezeigt wird und sich der Wert für „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 nun eine wichtige Entscheidung treffen: Wie soll Ihr Add-on eine Anfrage zum Festlegen von pointsEarned senden?

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 gezeigt werden. Die bereitgestellten Beispiele veranschaulichen beide Ansätze, um eine Note an Classroom zu übergeben. In den folgenden sprachspezifischen Anleitungen erfahren Sie, wie Sie einen Ansatz auswählen, wenn Sie die bereitgestellten Beispiele ausführen:

Noten anhand der Anmeldedaten der angemeldeten Lehrkraft festlegen

Verwenden Sie die Anmeldedaten des angemeldeten Nutzers, um eine Anfrage zum Festlegen von pointsEarned zu senden. Dies sollte recht intuitiv erscheinen, da es die restliche Implementierung bislang widerspiegelt und mit geringem Aufwand umgesetzt wird.

Beachten Sie jedoch, dass die Lehrkraft nur im iFrame mit den Aufgaben des Schülers/Studenten interagiert. Dies hat einige wichtige Auswirkungen:

• Noten werden erst dann in Classroom angezeigt, wenn die Lehrkraft die entsprechende Aktion über die Classroom-UI ausführt.
• Möglicherweise muss eine Lehrkraft jede Aufgabe eines Schülers/Studenten öffnen, um die Noten aller Schüler/Studenten einzutragen.
• Zwischen dem Eingang der Note in Classroom und der Anzeige in der Classroom-Benutzeroberfläche gibt es eine kurze Verzögerung. Die Verzögerung beträgt normalerweise fünf bis zehn Sekunden, kann aber auch bis zu 30 Sekunden betragen.

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

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. Abschließend senden Sie eine PATCH-Anfrage an den Endpunkt courses.courseWork.addOnAttachments.studentSubmissions. Die Instanz muss dabei die AddOnAttachmentStudentSubmission-Instanz enthalten. Außerdem muss pointsEarned im updateMask der PATCH-Anfrage angegeben werden:

# 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 der Lehrkraft festlegen

Der zweite Ansatz zum Festlegen von Noten erfordert die Verwendung gespeicherter Anmeldedaten für die Lehrkraft, die den Anhang erstellt hat. Bei dieser Implementierung müssen Sie Anmeldedaten mithilfe der Aktualisierungs- und Zugriffstokens einer zuvor autorisierten Lehrkraft erstellen und diese dann verwenden, um pointsEarned festzulegen.

Ein entscheidender Vorteil dieser Methode besteht darin, dass Noten automatisch über die Classroom-Benutzeroberfläche eingefügt werden. So werden die oben genannten Probleme vermieden. Das hat zur Folge, dass Endnutzer die Benotung als reibungslos 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 Nutzer-Datenbankeinträge, 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. Benotung einer abgegebenen Aufgabe festlegen

Legen Sie für diese Demo die Note fest, wenn der Schüler oder Student die Aktivität abgeschlossen hat, also wenn er das Formular über die Route für die Ansicht absendet.

Nutzer-Datenbankeinträge ändern, um Zugriffstoken zu speichern

Für API-Aufrufe sind zwei eindeutige Tokens erforderlich: das Aktualisierungstoken und das Zugriffstoken. Wenn Sie bisher der Schritt-für-Schritt-Serie gefolgt sind, sollte das User-Tabellenschema bereits ein Aktualisierungstoken speichern. Es reicht aus, das Aktualisierungstoken zu speichern, wenn Sie nur API-Aufrufe mit dem angemeldeten Nutzer ausführen, da Sie im Rahmen des Authentifizierungsvorgangs ein Zugriffstoken erhalten.

Allerdings müssen Sie jetzt nicht als angemeldeter Nutzer Anrufe tätigen, d. h., der Authentifizierungsvorgang 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, um auch das Zugriffstoken zu speichern:

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 Lehrkraft-ID zu speichern

Wenn Sie eine Note für eine Aktivität festlegen möchten, rufen Sie pointsEarned als Lehrkraft für den Kurs auf. 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 einem bestimmten Kurs zugeordnet werden kann.
• Senden Sie GET-Anfragen an den courses-Endpunkt der Classroom API, um die aktuellen Lehrkräfte abzurufen. Fragen Sie dann die lokalen Nutzerdatensätze ab, um übereinstimmende Lehrkräfte-Anmeldedaten zu finden.
• Speichern Sie beim Erstellen eines Add-on-Anhangs eine Lehrer-ID in der lokalen Datenbank für Anhänge. Rufen Sie dann die Anmeldedaten der Lehrkraft aus dem attachmentId ab, der an den iFrame der Schüler-/Studentenansicht ü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 Lehrer-ID-Feld 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 der Schüler-/Studentenansicht bereitgestellt wird. Sobald die Antwort des Schülers/Studenten in Ihrer lokalen Datenbank gespeichert ist, sollten Sie die Anmeldedaten der Lehrkraft aus dem lokalen Speicher abrufen. Dies sollte angesichts der Vorbereitungen in den vorherigen beiden Schritten unkompliziert sein. Sie können damit auch eine neue Instanz des Classroom-Dienstes für den Nutzer der 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,
    discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=ADD_ONS_ALPHA&key={GOOGLE_API_KEY}",
    credentials=teacher_credentials)

Note einer abgegebenen Aufgabe festlegen

Das Verfahren hier ist identisch mit dem bei der Verwendung der Anmeldedaten der angemeldeten Lehrkraft. Beachten Sie jedoch, dass Sie beim Aufruf die Anmeldedaten der Lehrkraft verwenden sollten, 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

Ähnlich wie in der vorherigen Schritt-für-Schritt-Anleitung können Sie als Lehrkraft eine Aufgabe mit einem Anhang des Aktivitätstyps erstellen, eine Antwort als Schüler senden und dann die Aufgabe im iFrame von „Aufgaben von Schülern/Studenten“ öffnen. Die Bewertung sollte je nach Implementierungsansatz zu unterschiedlichen Zeiten angezeigt werden:

• Wenn Sie nach Abschluss der Aktivität eine Note zurückgegeben haben, sollte der Notenentwurf bereits in der Benutzeroberfläche zu sehen sein, bevor der iFrame des Schülers/Studenten geöffnet wird. Sie sehen ihn auch in der Liste der Schüler/Studenten, wenn Sie die Aufgabe öffnen, und im Feld „Note“ neben dem iFrame „Aufgaben von Schülern/Studenten“.
• Wenn Sie eine Note zurückgegeben haben, 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/Studenten angezeigt wird.

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