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 produire une pièce jointe de type activité notée. Vous allez également transmettre une note à Google Classroom par programmation, qui s'affichera dans le carnet de notes de l'enseignant en tant que note provisoire.

Ce tutoriel diffère légèrement des autres de la série, car il existe deux approches possibles pour transmettre des notes à Classroom. Les deux ont des impacts distincts sur les expériences des développeurs et des utilisateurs. Tenez compte des deux lorsque vous concevez votre module complémentaire Classroom. Consultez la page de notre guide Interagir avec des pièces jointes pour en savoir plus 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 quelle pièce jointe de type activité.

Au cours de ce tutoriel, vous allez effectuer les opérations suivantes :

• Modifiez les requêtes de création de pièces jointes précédentes adressées à l'API Classroom pour définir également le dénominateur de la note de la pièce jointe.
• Notez par programmation le devoir de l'élève et définissez le numérateur de la note de la pièce jointe.
• Implémentez deux approches pour transmettre la note du devoir à Classroom à l'aide des identifiants de l'enseignant connecté ou hors connexion.

Une fois l'opération terminée, les notes s'affichent dans le carnet de notes Classroom après le déclenchement du comportement de transmission. 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 un élève voit une image d'un monument célèbre et est invité à saisir son nom. Attribuez la note maximale à la pièce jointe si l'élève saisit le nom correct, sinon zéro.

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

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

Figure 1. Interface utilisateur de création de devoirs 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 la note obtenue pour les notes des pièces jointes. Elles ne sont pas identiques aux notes des devoirs. Toutefois, les paramètres de note du devoir suivent les paramètres de note de la pièce jointe qui comporte le libellé Synchronisation des notes sur sa fiche de pièce jointe. Lorsque la pièce jointe "Synchronisation des notes" définit pointsEarned pour un devoir d'élève, elle définit également la note provisoire de l'élève 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 de devoirs présenté à la figure 1 pour voir un exemple du libellé "Synchronisation des notes". Notez que la fiche "Pièce jointe 1" comporte le libellé "Synchronisation des notes" et que la note du devoir dans la zone rouge a été mise à jour à 50 points. Notez également que, bien que la figure 1 présente trois fiches de pièces jointes, une seule comporte le libellé "Synchronisation des notes". Il s'agit d'une limite clé de l'implémentation actuelle : une seule pièce jointe peut comporter le libellé "Synchronisation des notes".

Si plusieurs pièces jointes ont défini maxPoints, la suppression de la pièce jointe avec "Synchronisation des notes" n'active pas "Synchronisation des notes" sur les autres pièces jointes. 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 s'ajuste en conséquence. Il n'existe aucun mécanisme permettant de voir par programmation quelle pièce jointe comporte le libellé "Synchronisation des notes" ni de voir le nombre de pièces jointes d'un devoir particulier.

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

Cette section décrit la définition du dénominateur pour une note de pièce jointe, c'est-à-dire la note maximale possible que tous les élèves peuvent obtenir pour leurs devoirs. Pour ce faire, définissez la valeur maxPoints de la pièce jointe.

Seule une modification mineure de notre implémentation existante est nécessaire pour activer les fonctionnalités de notation. Lors de la création d'une pièce jointe, ajoutez la valeur maxPoints dans le même objet AddOnAttachment qui contient studentWorkReviewUri, teacherViewUri et d'autres champs de pièces jointes.

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 pouvoir vérifier que les notes sont définies correctement. Définissez maxPoints sur 50 à titre de démonstration :

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 stockez également la valeur maxPoints dans votre base de données de pièces jointes locale. Cela vous évite d'avoir à effectuer un appel d'API supplémentaire ultérieurement lors de la notation des devoirs des élèves. Notez toutefois qu'il est possible que les enseignants modifient les paramètres de note du devoir indépendamment de votre module complémentaire. Envoyez une GET requête au courses.courseWork point de terminaison pour afficher la valeur maxPoints au niveau du devoir. Pour ce faire, transmettez itemId dans le champ CourseWork.id.

Mettez à jour votre modèle de base de données pour qu'il contienne également la valeur maxPoints de la pièce jointe. 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 pièce jointe a maintenant une note maximale. Vous devriez maintenant pouvoir tester ce comportement. Ajoutez une pièce jointe à un nouveau devoir et observez que la fiche de pièce jointe affiche le libellé "Synchronisation des notes" et que la valeur "Points" du devoir change.

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

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

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

Le problème est que la définition de pointsEarned nécessite le teacher champ d'application OAuth. Vous ne devez pas accorder le champ d'application teacher aux utilisateurs élèves. Cela pourrait entraîner un comportement inattendu lorsque les élèves interagissent avec votre module complémentaire, par exemple en chargeant l'iframe de la vue de l'enseignant au lieu de l'iframe de la vue de l'élève. Vous avez donc deux possibilités pour définir pointsEarned :

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

Les sections suivantes présentent les compromis de chaque approche avant de montrer chaque implémentation. Notez que les exemples fournis illustrent les deux approches pour transmettre une note à Classroom. Consultez les instructions spécifiques à la langue ci-dessous pour savoir comment sélectionner une approche lors de l'exécution des exemples fournis :

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

Utilisez les identifiants de l'utilisateur connecté pour émettre la requête afin de définir pointsEarned. Cela devrait sembler assez intuitif, car cela reflète le reste de l'implémentation jusqu'à présent et ne nécessite que peu d'efforts pour être réalisé.

Toutefois, sachez que l'enseignant n'interagit avec le devoir de l'élève que dans l'iframe de la vue de l'élève. Cela a des implications importantes :

• Aucune note n'est renseignée dans Classroom tant que l'enseignant n'a pas effectué d'action dans l'interface utilisateur Classroom.
• Un enseignant peut être amené à ouvrir chaque devoir d'élève pour renseigner toutes les notes des élèves.
• Il existe un bref délai entre la réception de la note par Classroom et son affichage dans l'interface utilisateur Classroom. Le délai est généralement de cinq à dix secondes, mais peut aller jusqu'à 30 secondes.

La combinaison de ces facteurs signifie que les enseignants peuvent avoir à effectuer un travail manuel considérable et chronophage pour renseigner complètement les notes d'une classe.

Pour implémenter cette approche, ajoutez un appel d'API supplémentaire à votre route de vue de l'élève existante.

Après avoir récupéré le devoir de l'élève et les enregistrements de pièces jointes, évaluez le devoir de l'élève et stockez la note obtenue. Définissez la note dans le pointsEarned champ d'un AddOnAttachmentStudentSubmission objet. Enfin, émettez une requête PATCH au courses.courseWork.addOnAttachments.studentSubmissions point de terminaison avec l'instance AddOnAttachmentStudentSubmission dans le corps de la requête. Notez que nous devons également spécifier pointsEarned dans updateMask dans 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 les notes à l'aide des identifiants de l'enseignant hors connexion

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

Un avantage essentiel de cette approche est que les notes sont renseignées sans nécessiter d'action de l'enseignant dans l'interface utilisateur Classroom, ce qui évite les problèmes mentionnés ci-dessus. Par conséquent, les utilisateurs finaux perçoivent l'expérience de notation comme transparente et efficace. De plus, cette approche vous permet de choisir le moment où 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 (facultativement) créez une instance de service Classroom.
4. Définissez 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 route de la vue de l'é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, le schéma de votre 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 cadre du flux d'authentification.

Toutefois, vous devez maintenant effectuer des appels en tant que personne 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 définir une note pour une activité, effectuez un appel pour définir pointsEarned en tant qu'enseignant du cours. Il existe plusieurs façons d'y parvenir :

• Stockez un mappage local des identifiants de l'enseignant aux ID de cours. Notez toutefois que le même enseignant ne sera pas toujours associé à un cours particulier.
• Émettez des requêtes GET au point de terminaison courses de l'API Classroom pour obtenir le ou les enseignants actuels. Interrogez ensuite les enregistrements utilisateur locaux pour trouver les identifiants d'enseignant correspondants.
• Lors de la création d'une pièce jointe de module complémentaire, stockez un ID d'enseignant dans la base de données de pièces jointes locale. Récupérez ensuite les identifiants de l'enseignant à partir de l'attachmentId transmis à l'iframe de la vue de l'élève.

Cet exemple illustre la dernière option, car vous définissez les notes lorsque l'élève termine 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 qui diffuse l'iframe de la vue de l'é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 stockage local. Cela devrait être simple compte tenu de la préparation des deux étapes précédentes. Vous pouvez également les utiliser 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,
    credentials=teacher_credentials)

Définir la note d'un devoir

La procédure à partir de là 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 dans 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 devoir dans l'iframe de la vue de l'élève. Vous devriez pouvoir voir la note 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 provisoire dans l'interface utilisateur avant d'ouvrir l'iframe de la vue de l'élève. Vous pouvez également la voir dans la liste des élèves lorsque vous ouvrez le devoir, ainsi que dans la zone "Note" à côté de l'iframe de la vue de l'élève.
• Si vous avez choisi de transmettre une note lorsque l'enseignant ouvre l'iframe de la vue de l'élève, la note devrait s'afficher dans la zone "Note" peu de temps après le chargement de l'iframe. Comme mentionné ci-dessus, cela peut prendre jusqu'à 30 secondes. Par la suite, la note de l'élève spécifique devrait également s'afficher dans les autres vues du carnet de notes Classroom.

Vérifiez que la note correcte s'affiche pour l'élève.

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