Noten und Rücksendungen von Anhängen

Dies ist die sechste Anleitung in der Reihe zu Classroom-Add‑ons.

In dieser Anleitung ändern Sie das Beispiel aus dem vorherigen Schritt, um einen benoteten Anhang vom Typ „Aktivität“ zu erstellen. Außerdem übergeben Sie programmatisch eine Note an Google Classroom, die im Notenbuch der Lehrkraft als Entwurf angezeigt wird.

Diese Anleitung unterscheidet sich leicht von den anderen in der Reihe, da es zwei mögliche Ansätze gibt, um Noten an Classroom zurückzugeben. Beide haben unterschiedliche Auswirkungen auf die Entwickler- und Nutzererfahrung. Berücksichtigen Sie beide beim Entwerfen Ihres Classroom-Add‑ons. 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 Anhang vom Typ „Aktivität“ verwendet werden.

In dieser Anleitung führen Sie folgende Schritte aus:

• Ändern Sie die vorherigen Anfragen zum Erstellen von Anhängen an die Classroom API, um auch den Nenner der Note für den Anhang festzulegen.
• Bewerten Sie die eingereichte Aufgabe des Schülers/Studenten programmatisch und legen Sie den Zähler der Note für den Anhang fest.
• Implementieren Sie zwei Ansätze, um die Note der eingereichten Aufgabe mithilfe von Anmeldedaten der angemeldeten oder offline verfügbaren Lehrkraft an Classroom zu übergeben.

Nach Abschluss werden die Noten im Classroom-Notenbuch angezeigt, nachdem das Verhalten für die Rückgabe ausgelöst wurde. Der genaue Zeitpunkt hängt vom Implementierungsansatz ab.

Für dieses Beispiel verwenden wir die Aktivität aus der vorherigen Anleitung, in der einem Schüler/Studenten ein Bild eines berühmten Wahrzeichens gezeigt wird und er aufgefordert wird, den Namen einzugeben. Geben Sie für den Anhang die volle Punktzahl, wenn der Schüler/Student den richtigen Namen eingibt, andernfalls null.

Benotungsfunktion der Classroom-Add‑ons API

Mit Ihrem Add‑on können Sie sowohl den Zähler als auch den Nenner der Note für einen Anhang festlegen. Diese werden jeweils mit den Werten pointsEarned und maxPoints in der API festgelegt. Auf einer Anhangskarte in der Classroom-UI wird der Wert maxPoints angezeigt, wenn er festgelegt wurde.

Abbildung 1 : UI zum Erstellen von Aufgaben mit drei Anhangskarten für Add‑ons, für die maxPoints festgelegt ist.

Mit der Classroom-Add‑ons API können Sie die Einstellungen für Anhangsnoten konfigurieren und die erreichte Punktzahl festlegen. Diese sind nicht mit den Aufgabennoten identisch. Die Einstellungen für die Aufgabennote folgen jedoch den Einstellungen für die Anhangsnote des Anhangs, auf dessen Anhangskarte das Label Notensynchronisierung angezeigt wird. Wenn für den Anhang „Notensynchronisierung“ pointsEarned für eine eingereichte Aufgabe eines Schülers/Studenten festgelegt wird, wird auch die Entwurfsnote des Schülers/Studenten für die Aufgabe festgelegt.

Normalerweise erhält der erste Anhang, der der Aufgabe hinzugefügt wurde und für den maxPoints festgelegt ist, das Label „Notensynchronisierung“. Ein Beispiel für das Label „Notensynchronisierung“ finden Sie in der UI zum Erstellen von Aufgaben in Abbildung 1. Beachten Sie, dass die Karte „Anhang 1“ das Label „Notensynchronisierung“ hat und dass die Aufgabennote im roten Feld auf 50 Punkte aktualisiert wurde. Beachten Sie auch, dass in Abbildung 1 zwar drei Anhangskarten angezeigt werden, aber nur eine Karte das Label „Notensynchronisierung“ hat. Dies ist eine wichtige Einschränkung der aktuellen Implementierung: Nur ein Anhang kann das Label „Notensynchronisierung“ haben.

Wenn mehrere Anhänge vorhanden sind, für die maxPoints festgelegt ist, wird die Notensynchronisierung für keinen der verbleibenden Anhänge aktiviert, wenn der Anhang mit „Notensynchronisierung“ nicht entfernt wird. Wenn Sie einen weiteren Anhang hinzufügen, für den maxPoints festgelegt ist, wird die Notensynchronisierung für den neuen Anhang aktiviert und die maximale Aufgabennote entsprechend angepasst. Es gibt keinen Mechanismus, um programmatisch zu sehen, welcher Anhang das Label „Notensynchronisierung“ 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 eine Anhangsnote festlegen, d. h. die maximal mögliche Punktzahl, die alle Schüler/Studenten für ihre eingereichten Aufgaben erreichen können. Legen Sie dazu den Wert maxPoints für den Anhang fest.

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

Die Standardpunktzahl für eine neue Aufgabe ist 100. Wir empfehlen, für maxPoints einen anderen Wert als 100 festzulegen, damit Sie überprüfen können, ob die Noten richtig festgelegt werden. Legen Sie maxPoints als Beispiel 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 Anhangsdatenbank. So müssen Sie später beim Benoten der eingereichten Aufgaben der Schüler/Studenten keinen zusätzlichen API-Aufruf ausführen. Beachten Sie jedoch, dass Lehrkräfte die Einstellungen für die Aufgabennote unabhängig von Ihrem Add‑on ändern können. Senden Sie eine GET Anfrage an den courses.courseWork Endpunkt, um den Wert maxPoints auf Aufgabenebene zu sehen. Übergeben Sie dabei itemId im Feld CourseWork.id.

Aktualisieren Sie nun Ihr Datenbankmodell, um auch den Wert maxPoints des Anhangs zu speichern. 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 beobachten Sie, dass auf der Anhangskarte das Label „Notensynchronisierung“ angezeigt wird und sich der Wert „Punkte“ der Aufgabe ändert.

Note für eine eingereichte Aufgabe eines Schülers/Studenten in Classroom festlegen

In diesem Abschnitt wird beschrieben, wie Sie den Zähler für eine Anhangsnote festlegen, d. h. die Note eines einzelnen Schülers/Studenten für den Anhang. Legen Sie dazu den Wert pointsEarned für die eingereichte Aufgabe eines Schülers/Studenten für den Anhang fest.

Sie müssen jetzt eine wichtige Entscheidung treffen: Wie soll Ihr Add‑on eine Anfrage zum Festlegen von pointsEarned senden?

Das Problem ist, dass zum Festlegen von pointsEarned der teacher OAuth-Bereich erforderlich ist. Sie sollten Schülern/Studenten nicht den Bereich teacher gewähren. Dies kann zu unerwartetem Verhalten führen, wenn Schüler/Studenten mit Ihrem Add‑on interagieren, z. B. wenn der Teacher View-iFrame anstelle des Student View-iFrames geladen wird. Sie haben daher zwei Möglichkeiten, pointsEarned festzulegen:

• Mit den Anmeldedaten der angemeldeten Lehrkraft.
• Mit gespeicherten (offline verfügbaren) Anmeldedaten der Lehrkraft.

In den folgenden Abschnitten werden die Vor- und Nachteile der einzelnen Ansätze erläutert, bevor die jeweilige Implementierung demonstriert wird. In unseren Beispielen werden beide Ansätze zum Übergeben einer Note an Classroom demonstriert. In den sprachspezifischen Anleitungen unten erfahren Sie, wie Sie einen Ansatz auswählen, wenn Sie die Beispiele ausführen:

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 recht intuitiv sein, da es dem Rest der bisherigen Implementierung entspricht und nur wenig Aufwand erfordert.

Beachten Sie jedoch, dass die Lehrkraft nur im Student Work Review-iFrame mit der eingereichten Aufgabe des Schülers/Studenten interagiert. Das hat einige wichtige Auswirkungen:

• In Classroom werden erst Noten angezeigt, wenn die Lehrkraft in der Classroom-UI eine Aktion ausführt.
• Eine Lehrkraft muss möglicherweise jede eingereichte Aufgabe eines Schülers/Studenten öffnen, um alle Noten der Schüler/Studenten zu sehen.
• Es gibt eine kurze Verzögerung zwischen dem Zeitpunkt, zu dem Classroom die Note erhält, und dem Zeitpunkt, zu dem sie in der Classroom-UI angezeigt wird. 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 und zeitaufwendige manuelle Arbeit leisten, um alle Noten einer Klasse zu sehen.

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

Nachdem Sie die eingereichte Aufgabe des Schülers/Studenten und die Anhangsdatensätze abgerufen haben, bewerten Sie die eingereichte Aufgabe des Schülers/Studenten und speichern Sie die resultierende Note. Legen Sie die Note im pointsEarned Feld eines AddOnAttachmentStudentSubmission Objekts fest. Senden Sie schließlich eine PATCH Anfrage an den courses.courseWork.addOnAttachments.studentSubmissions Endpunkt mit der AddOnAttachmentStudentSubmission Instanz im Anfragetext. Beachten Sie, dass wir pointsEarned auch in der 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 mit offline verfügbaren Anmeldedaten der Lehrkraft festlegen

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

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

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

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

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

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