Notes en pièce jointe et renvoi des notes

Il s'agit du sixième tutoriel de la série de tutoriels sur les modules complémentaires Classroom.

Dans ce tutoriel, vous allez modifier l'exemple de l'étape précédente pour générer un rattachement de type activité noté. Vous pouvez également renvoyer une note à Google Classroom par programmation, qui apparaît dans le carnet de notes de l'enseignant sous forme de note temporaire.

Ce tutoriel diffère légèrement des autres contenus de la série, car il existe deux approches possibles pour transmettre des notes dans Classroom. Les deux ont un impact distinct sur l'expérience du développeur et l'expérience utilisateur. Tenez-en compte lorsque vous concevez votre module complémentaire Classroom. Consultez la page du guide Interagir avec les pièces jointes pour une discussion plus détaillée sur les options d'implémentation.

Notez que les fonctionnalités de notation de l'API sont facultatives. Elles peuvent être utilisées avec n'importe quel rattachement de type activité.

Dans ce tutoriel, vous allez:

• Modifiez les précédentes demandes de création de pièce jointe dans l'API Classroom pour définir également le dénominateur des notes de la pièce jointe.
• Notez le devoir de l'élève de manière automatisée et définissez le numérateur des notes de la pièce jointe.
• Pour transmettre la note d'un devoir à Classroom, mettez en œuvre deux approches, en utilisant les identifiants de l'enseignant, connectés ou non.

Une fois l'opération terminée, les notes s'affichent dans le carnet de notes Classroom dès que le comportement de renvoi est déclenché. Le moment exact où cela se produit dépend de l'approche d'implémentation.

Pour les besoins de cet exemple, réutilisez l'activité du tutoriel précédent, dans laquelle l'élève voit une image d'un point de repère célèbre et est invité à saisir son nom. Attribuez une note complète à la pièce jointe si l'élève saisit le nom correct. Sinon, marquez zéro.

Comprendre la fonctionnalité de notation des modules complémentaires Classroom à l'aide de l'API

Votre module complémentaire peut définir à la fois le numérateur et le dénominateur des notes pour une pièce jointe. Elles sont respectivement définies à l'aide des valeurs pointsEarned et maxPoints dans l'API. Une fiche associée à une pièce jointe dans l'interface utilisateur de Classroom affiche la valeur maxPoints lorsqu'elle a été définie.

Figure 1. UI de création d'attributions avec trois fiches de pièces jointes de modules complémentaires pour lesquelles maxPoints est défini

L'API des modules complémentaires Classroom vous permet de configurer les paramètres et de définir le score obtenu pour les notes associées aux pièces jointes. Elles sont différentes des notes de devoir. Toutefois, les paramètres de note des devoirs suivent ceux de la pièce jointe dont la carte comporte le libellé Synchronisation des notes. Lorsque la pièce jointe "Synchronisation des notes" définit pointsEarned pour le devoir envoyé par un élève, la note temporaire de l'élève est également définie pour le devoir.

En règle générale, la première pièce jointe ajoutée au devoir qui définit maxPoints reçoit le libellé "Synchronisation des notes". Consultez l'exemple d'interface utilisateur de création d'un devoir illustré à la figure 1 pour un exemple de libellé "Synchronisation des notes". Notez que la fiche "Pièce jointe 1" porte le libellé "Synchronisation des notes" et que la note du devoir dans le cadre rouge a été remplacée par 50 points. Notez également que, bien que la figure 1 présente trois cartes pour pièces jointes, une seule d'entre elles porte le libellé "Synchronisation des notes". Il s'agit d'une limite clé de l'implémentation actuelle: une seule pièce jointe peut avoir le libellé "Synchronisation des notes".

Si la maxPoints est définie pour plusieurs pièces jointes, la suppression de la pièce jointe avec "Synchronisation des notes" n'active pas cette fonctionnalité pour les pièces jointes restantes. L'ajout d'une autre pièce jointe qui définit maxPoints active la synchronisation des notes sur la nouvelle pièce jointe, et la note maximale du devoir est ajustée en conséquence. Il n'existe aucun mécanisme permettant d'identifier par programmation la pièce jointe associée au libellé "Synchronisation des notes", ni de connaître le nombre de pièces jointes associées à un devoir particulier.

Définir la note maximale d'une pièce jointe

Cette section explique comment définir le dénominateur d'une note pour les pièces jointes, c'est-à-dire le score maximal que tous les élèves peuvent obtenir pour leurs devoirs. Pour ce faire, définissez la valeur maxPoints du rattachement.

Seule une modification mineure de notre implémentation existante est nécessaire pour activer les fonctionnalités de notation. Lorsque vous créez un rattachement, ajoutez la valeur maxPoints dans le même objet AddOnAttachment contenant les champs studentWorkReviewUri, teacherViewUri et autres.

Notez que la note maximale par défaut pour un nouveau devoir est de 100. Nous vous suggérons de définir maxPoints sur une valeur autre que 100 afin de vérifier que les notes sont correctement définies. Pour l'exemple, définissez maxPoints sur 50:

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}",
}

Pour les besoins de cette démonstration, vous allez également stocker la valeur maxPoints dans votre base de données de pièces jointes locale. Cela vous évitera d'avoir à effectuer un appel d'API supplémentaire par la suite lors de la notation des devoirs. Toutefois, il est possible que les enseignants modifient les paramètres de notation des devoirs indépendamment de votre module complémentaire. Envoyez une requête GET au point de terminaison courses.courseWork pour afficher la valeur maxPoints au niveau de l'attribution. Lors de cette opération, transmettez la valeur itemId dans le champ CourseWork.id.

À présent, mettez à jour votre modèle de base de données pour qu'il contienne également la valeur maxPoints du rattachement. Nous vous recommandons d'utiliser la valeur maxPoints de la réponse CREATE:

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

La note maximale est désormais attribuée à la pièce jointe. Vous devriez maintenant pouvoir tester ce comportement. Ajoutez une pièce jointe à un nouveau devoir, et vérifiez que la carte associée affiche le libellé "Synchronisation des notes" et que la valeur "Points" du devoir change.

Définir la note d'un élève à son devoir dans Classroom

Cette section décrit la définition du numérateur d'une note de pièce jointe, c'est-à-dire le score d'un élève individuel pour la pièce jointe. Pour ce faire, définissez la valeur pointsEarned d'un devoir d'élève.

Vous avez maintenant une décision importante à prendre: comment votre module complémentaire doit-il envoyer une requête pour définir pointsEarned ?

Le problème est que la configuration de pointsEarned nécessite le champ d'application OAuth teacher. Vous ne devez pas accorder le niveau d'accès teacher aux élèves. Cela pourrait entraîner un comportement inattendu lors des interactions des élèves avec votre module complémentaire, par exemple en chargeant l'iFrame de la vue enseignant au lieu de l'iFrame de la vue élève. Vous avez donc deux options pour définir pointsEarned:

• Avec les identifiants de l'enseignant connecté
• Utiliser des identifiants d'enseignant stockés (hors connexion)

Les sections suivantes décrivent les compromis propres à chaque approche avant de présenter chacune d'entre elles. Notez que les exemples fournis illustrent les deux approches pour transmettre une note dans Classroom. Consultez les instructions spécifiques à la langue ci-dessous pour savoir comment choisir une approche lorsque vous exécutez les exemples fournis:

Définir les notes à l'aide des identifiants de l'enseignant connecté

Utilisez les identifiants de l'utilisateur connecté pour envoyer la requête permettant de définir pointsEarned. Cette approche devrait sembler assez intuitive, car elle reflète le reste de l'implémentation jusqu'à présent et ne nécessite que peu d'effort.

Toutefois, gardez à l'esprit que l'enseignant n'interagit qu'avec la remise de l'élève dans l'iFrame de révision des devoirs des élèves. Cela a des conséquences importantes:

• Aucune note n'est affichée dans Classroom tant que l'enseignant n'a pas effectué d'action dans l'interface utilisateur de Classroom.
• Un enseignant peut avoir à ouvrir le travail de chaque élève pour remplir toutes les notes des élèves.
• Un court délai s'écoule entre la réception de la note par Classroom et son affichage dans l'interface utilisateur de Classroom. Le délai est généralement de cinq à dix secondes, mais peut être de 30 secondes maximum.

La combinaison de ces facteurs implique que les enseignants devront peut-être effectuer un travail manuel considérable et chronophage pour remplir toutes les notes d'une classe.

Pour implémenter cette approche, ajoutez un appel d'API supplémentaire à votre parcours Student Work Review existant.

Après avoir récupéré les devoirs remis et les pièces jointes, évaluez le travail de l'élève et stockez la note obtenue. Définissez la note dans le champ pointsEarned d'un objet AddOnAttachmentStudentSubmission. Enfin, envoyez une requête PATCH au point de terminaison courses.courseWork.addOnAttachments.studentSubmissions en indiquant l'instance AddOnAttachmentStudentSubmission dans le corps de la requête. Notez que nous devons également spécifier pointsEarned dans le updateMask de notre requête PATCH:

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

Définir des notes à l'aide d'identifiants d'enseignant hors connexion

La deuxième méthode pour définir les notes nécessite l'utilisation d'identifiants stockés pour l'enseignant qui a créé la pièce jointe. Cette implémentation nécessite de créer des identifiants à l'aide des jetons d'actualisation et d'accès d'un enseignant précédemment autorisé, puis d'utiliser ces identifiants pour définir pointsEarned.

L'un des principaux avantages de cette approche est que les notes sont remplies sans intervention de l'enseignant dans l'interface utilisateur de Classroom, ce qui permet d'éviter les problèmes mentionnés ci-dessus. Résultat : les utilisateurs finaux perçoivent l'expérience de notation comme étant fluide et efficace. De plus, cette approche vous permet de choisir le moment auquel vous transmettez les notes, par exemple lorsque les élèves terminent l'activité ou de manière asynchrone.

Pour implémenter cette approche, effectuez les tâches suivantes:

1. Modifiez les enregistrements de la base de données des utilisateurs pour stocker un jeton d'accès.
2. Modifiez les enregistrements de la base de données des pièces jointes pour stocker un ID d'enseignant.
3. Récupérez les identifiants de l'enseignant et, si vous le souhaitez, créez une instance de service Classroom.
4. Définir la note d'un devoir

Pour les besoins de cette démonstration, définissez la note lorsque l'élève termine l'activité, c'est-à-dire lorsqu'il envoie le formulaire dans la vue élève.

Modifier les enregistrements de la base de données des utilisateurs pour stocker le jeton d'accès

Deux jetons uniques sont nécessaires pour effectuer des appels d'API : le jeton d'actualisation et le jeton d'accès. Si vous avez suivi la série de tutoriels jusqu'à présent, votre schéma de table User devrait déjà stocker un jeton d'actualisation. Le stockage du jeton d'actualisation est suffisant lorsque vous n'effectuez des appels d'API qu'avec l'utilisateur connecté, car vous recevez un jeton d'accès dans le flux d'authentification.

Toutefois, vous devez maintenant passer des appels en tant qu'utilisateur autre que l'utilisateur connecté, ce qui signifie que le flux d'authentification n'est pas disponible. Vous devez donc stocker le jeton d'accès avec le jeton d'actualisation. Mettez à jour le schéma de votre table User pour inclure un jeton d'accès:

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

Ensuite, mettez à jour tout code qui crée ou met à jour un enregistrement User pour stocker également le jeton d'accès:

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

Modifier les enregistrements de la base de données des pièces jointes pour stocker un ID d'enseignant

Pour attribuer une note à une activité, appelez pointsEarned en tant qu'enseignant du cours. Il existe plusieurs façons d'y parvenir:

• Stockez un mappage local des identifiants des enseignants avec les ID de cours. Notez toutefois qu'il est possible qu'un même enseignant ne soit pas toujours associé à un cours particulier.
• Envoyez des requêtes GET au point de terminaison courses de l'API Classroom pour obtenir le ou les enseignants actuels. Ensuite, interrogez les enregistrements d'utilisateurs locaux pour trouver les identifiants d'enseignant correspondants.
• Lorsque vous créez une pièce jointe de module complémentaire, stockez un ID d'enseignant dans la base de données des pièces jointes locale. Ensuite, récupérez les identifiants de l'enseignant à partir du attachmentId transmis à l'iFrame de la vue élève.

Cet exemple illustre la dernière option, car vous définissez des notes lorsque l'élève remplit une pièce jointe d'activité.

Ajoutez un champ d'ID d'enseignant à la table Attachment de votre base de données:

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

Ensuite, mettez à jour tout code qui crée ou met à jour un enregistrement Attachment pour stocker également l'ID du créateur:

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

Récupérer les identifiants de l'enseignant

Recherchez la route menant à l'iFrame "Vue élève". Immédiatement après avoir stocké la réponse de l'élève dans votre base de données locale, récupérez les identifiants de l'enseignant à partir de votre espace de stockage local. Compte tenu de la préparation aux deux étapes précédentes, cela devrait être simple. Vous pouvez également vous en servir pour créer une instance du service Classroom pour l'utilisateur enseignant:

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

Définir la note d'un devoir

La procédure à suivre est identique à celle qui consiste à utiliser les identifiants de l'enseignant connecté. Toutefois, notez que vous devez effectuer l'appel avec les identifiants de l'enseignant récupérés à l'étape précédente:

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

Tester le module complémentaire

Comme pour le tutoriel précédent, créez un devoir avec une pièce jointe de type activité en tant qu'enseignant, envoyez une réponse en tant qu'élève, puis ouvrez son envoi dans l'iFrame de révision des devoirs des élèves. La note devrait s'afficher à différents moments en fonction de votre approche d'implémentation:

• Si vous avez choisi de transmettre une note lorsque l'élève a terminé l'activité, vous devriez déjà voir sa note temporaire dans l'interface utilisateur avant d'ouvrir l'iFrame de révision des devoirs des élèves. Il apparaît également dans la liste des élèves à l'ouverture du devoir, ainsi que dans la zone "Note" à côté de l'iFrame "Révision des devoirs des élèves".
• Si vous choisissez de transmettre une note lorsque l'enseignant ouvre l'iFrame "Examen des devoirs des élèves", la note devrait apparaître dans la zone "Note" peu de temps après le chargement de l'iFrame. Comme indiqué ci-dessus, cette opération peut prendre jusqu'à 30 secondes. Par la suite, la note de l'élève concerné devrait également apparaître dans les autres affichages du carnet de notes Classroom.

Vérifiez que la note affichée pour l'élève est correcte.

Félicitations ! Vous êtes prêt à passer à l'étape suivante: créer des pièces jointes en dehors de Google Classroom.