Pièces jointes au type de contenu

Gérer les paramètres de requête de la vue de découverte des pièces jointes

Comme indiqué précédemment, Google Classroom transmet des paramètres de requête lors du chargement de la vue de découverte des pièces jointes dans l'iframe :

• courseId : ID du cours Classroom actuel.
• itemId: identifiant unique du devoir, du matériel de cours ou de l'annonce qui reçoit la pièce jointe du module complémentaire.
• itemType : "courseWork", "courseWorkMaterials" ou "announcement".
• addOnToken: jeton utilisé pour autoriser certaines actions de module complémentaire Classroom.
• login_hint : ID Google de l'utilisateur actuel.

Ce tutoriel aborde courseId, itemId, itemType et addOnToken. Conservez-les et transmettez-les lorsque vous appelez l'API Classroom.

Comme à l'étape précédente du tutoriel, stockez les valeurs des paramètres de requête transmis dans notre session. Il est important de le faire lors de la première ouverture de la vue de découverte des pièces jointes, car c'est la seule possibilité pour Classroom de transmettre ces paramètres de requête.

# Retrieve the itemId, courseId, and addOnToken query parameters.
if flask.request.args.get("itemId"):
    flask.session["itemId"] = flask.request.args.get("itemId")
if flask.request.args.get("itemType"):
    flask.session["itemType"] = flask.request.args.get("itemType")
if flask.request.args.get("courseId"):
    flask.session["courseId"] = flask.request.args.get("courseId")
if flask.request.args.get("addOnToken"):
    flask.session["addOnToken"] = flask.request.args.get("addOnToken")

Ajouter un stockage persistant pour les pièces jointes de type contenu

Vous avez besoin d'un enregistrement local de toutes les pièces jointes créées. Cela vous permet de rechercher le contenu sélectionné par l'enseignant à l'aide des identifiants fournis par Classroom.

Configurez un schéma de base de données pour une Attachment. L'exemple fourni présente des pièces jointes qui affichent une image et une légende. Une Attachment contient les attributs suivants :

• attachment_id : identifiant unique d'une pièce jointe. Attribué par Classroom et renvoyé dans la réponse lors de la création d'une pièce jointe.
• image_filename : nom de fichier local de l'image à afficher.
• image_caption : légende à afficher avec l'image.

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

Configurer de nouveaux itinéraires

Commencez cette étape du tutoriel en configurant de nouvelles pages dans notre application. Elles permettent à un utilisateur de créer et d'afficher du contenu via notre module complémentaire.

Ajouter des itinéraires de création de pièces jointes

Vous avez besoin de pages pour que l'enseignant puisse sélectionner du contenu et envoyer des requêtes de création de pièces jointes. Implémentez l'itinéraire /attachment-options pour afficher les options de contenu que l'enseignant peut sélectionner. Vous avez également besoin de modèles pour les pages de sélection de contenu et de confirmation de création. Les exemples fournis contiennent des modèles pour ces éléments et peuvent également afficher les requêtes et les réponses de l'API Classroom.

Notez que vous pouvez également modifier la page de destination de la vue de découverte des pièces jointes existante pour afficher les options de contenu au lieu de créer la nouvelle page /attachment-options. Nous vous recommandons de créer une page pour cet exercice afin de conserver le comportement SSO implémenté lors de la deuxième étape du tutoriel, comme la révocation des autorisations de l'application. Ces éléments devraient vous être utiles lors de la création et du test de votre module complémentaire.

Dans l'exemple fourni, un enseignant peut choisir parmi un petit ensemble d'images légendées. Nous avons fourni quatre images de monuments célèbres dont les légendes sont dérivées des noms de fichiers.

@app.route("/attachment-options", methods=["GET", "POST"])
def attachment_options():
    """
    Render the attachment options page from the "attachment-options.html"
    template.

    This page displays a grid of images that the user can select using
    checkboxes.
    """

    # A list of the filenames in the static/images directory.
    image_filenames = os.listdir(os.path.join(app.static_folder, "images"))

    # The image_list_form_builder method creates a form that displays a grid
    # of images, checkboxes, and captions with a Submit button. All images
    # passed in image_filenames will be shown, and the captions will be the
    # title-cased filenames.

    # The form must be built dynamically due to limitations in WTForms. The
    # image_list_form_builder method therefore also returns a list of
    # attribute names in the form, which will be used by the HTML template
    # to properly render the form.
    form, var_names = image_list_form_builder(image_filenames)

    # If the form was submitted, validate the input and create the attachments.
    if form.validate_on_submit():

        # Build a dictionary that maps image filenames to captions.
        # There will be one dictionary entry per selected item in the form.
        filename_caption_pairs = construct_filename_caption_dictionary_list(
            form)

        # Check that the user selected at least one image, then proceed to
        # make requests to the Classroom API.
        if len(filename_caption_pairs) > 0:
            return create_attachments(filename_caption_pairs)
        else:
            return flask.render_template(
                "create-attachment.html",
                message="You didn't select any images.",
                form=form,
                var_names=var_names)

    return flask.render_template(
        "attachment-options.html",
        message=("You've reached the attachment options page. "
                "Select one or more images and click 'Create Attachment'."),
        form=form,
        var_names=var_names,
    )

Envoyer des requêtes de création de pièces jointes

Maintenant que vous savez quels éléments de contenu l'enseignant souhaite joindre, envoyez des requêtes à l'API Classroom pour créer des pièces jointes dans notre devoir. Stockez les détails des pièces jointes dans votre base de données après avoir reçu une réponse de l'API Classroom.

Commencez par obtenir une instance du service Classroom :

def create_attachments(filename_caption_pairs):
    """
    Create attachments and show an acknowledgement page.

    Args:
        filename_caption_pairs: A dictionary that maps image filenames to
            captions.
    """
    # Get the Google Classroom service.
    classroom_service = googleapiclient.discovery.build(
        serviceName="classroom",
        version="v1",
        credentials=credentials)

Envoyez une CREATE requête au courses.courseWork.addOnAttachments point de terminaison. Pour chaque image sélectionnée par l'enseignant, commencez par créer un AddOnAttachment objet :

# Create a new attachment for each image that was selected.
attachment_count = 0
for key, value in filename_caption_pairs.items():
    attachment_count += 1

    # Create a dictionary with values for the AddOnAttachment object fields.
    attachment = {
        # Specifies the route for a teacher user.
        "teacherViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True),
        },
        # Specifies the route for a student user.
        "studentViewUri": {
            "uri":
                flask.url_for(
                    "load_content_attachment", _scheme='https', _external=True)
        },
        # The title of the attachment.
        "title": f"Attachment {attachment_count}",
    }

Au moins les champs teacherViewUri, studentViewUri et title doivent être fournis pour chaque pièce jointe. teacherViewUri et studentViewUri représentent les URL chargées lorsque la pièce jointe est ouverte par le type d'utilisateur correspondant.

Envoyez l'objet AddOnAttachment dans le corps d'une requête au point de terminaison addOnAttachments approprié. Fournissez les identifiants courseId, itemId, itemType et addOnToken avec chaque requête.

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

# Issue a request to create the attachment.
resp = parent.addOnAttachments().create(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"],
    addOnToken=flask.session["addOnToken"],
    body=attachment).execute()

Créez une entrée pour cette pièce jointe dans votre base de données locale afin de pouvoir charger le contenu approprié ultérieurement. Classroom renvoie une valeur id unique dans la réponse à la requête de création. Utilisez-la donc comme clé primaire dans notre base de données. Notez également que Classroom transmet le paramètre de requête attachmentId lors de l'ouverture des vues de l'enseignant et de l'élève :

# Store the value 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)
db.session.add(new_attachment)
db.session.commit()

Envisagez de rediriger l'utilisateur vers une page de confirmation à ce stade, en lui indiquant qu'il a bien créé des pièces jointes.

Autoriser les pièces jointes de votre module complémentaire

C'est le bon moment pour ajouter les adresses appropriées au champ "Préfixes d'URI de pièces jointes autorisés" de la page "Configuration de l'application" du SDK Google Workspace Marketplace. Votre module complémentaire ne peut créer des pièces jointes qu'à partir de l'un des préfixes d'URI listés sur cette page. Il s'agit d'une mesure de sécurité visant à réduire le risque d'attaques dites "de l'homme du milieu" (attaques "man in the middle").

L'approche la plus simple consiste à fournir votre domaine de premier niveau dans ce champ, par exemple https://example.com. https://localhost:<your port number>/ fonctionnerait si vous utilisiez votre ordinateur local comme serveur Web.

Ajouter des itinéraires pour les vues de l'enseignant et de l'élève

Il existe quatre iframes dans lesquels un module complémentaire Google Classroom peut être chargé. Jusqu'à présent, vous n'avez créé que des itinéraires qui diffusent l'iframe de la vue de découverte des pièces jointes. Ensuite, ajoutez des itinéraires pour diffuser également les iframes des vues de l'enseignant et de l'élève.

L'iframe de la vue de l'enseignant est nécessaire pour afficher un aperçu de l'expérience de l'élève, mais peut éventuellement inclure des informations supplémentaires ou des fonctionnalités de modification.

La vue de l'élève est la page présentée à chaque élève lorsqu'il ouvre une pièce jointe de module complémentaire.

Pour cet exercice, créez un seul itinéraire /load-content-attachment qui diffuse à la fois les vues de l'enseignant et de l'élève. Utilisez les méthodes de l'API Classroom pour déterminer si l'utilisateur est un enseignant ou un élève lorsque la page se charge.

@app.route("/load-content-attachment")
def load_content_attachment():
    """
    Load the attachment for the user's role."""

    # Since this is a landing page for the Teacher and Student View iframes, we
    # need to preserve the incoming query parameters.
    if flask.request.args.get("itemId"):
        flask.session["itemId"] = flask.request.args.get("itemId")
    if flask.request.args.get("itemType"):
        flask.session["itemType"] = flask.request.args.get("itemType")
    if flask.request.args.get("courseId"):
        flask.session["courseId"] = flask.request.args.get("courseId")
    if flask.request.args.get("attachmentId"):
        flask.session["attachmentId"] = flask.request.args.get("attachmentId")

N'oubliez pas que vous devez également authentifier l'utilisateur à ce stade. Vous devez également gérer le paramètre de requête login_hint ici et rediriger l'utilisateur vers votre flux d'autorisation si nécessaire. Pour en savoir plus sur ce flux, consultez les consignes de connexion abordées dans les tutoriels précédents.

Envoyez ensuite une requête au point de terminaison getAddOnContext qui correspond au type d'élément.

# Create an instance of the Classroom service.
classroom_service = googleapiclient.discovery.build(
    serviceName="classroom"
    version="v1",
    credentials=credentials)

# Use the itemType to determine which stream item type the teacher created
match flask.session["itemType"]:
    case "announcements":
        parent = classroom_service.courses().announcements()
    case "courseWorkMaterials":
        parent = classroom_service.courses().courseWorkMaterials()
    case _:
        parent = classroom_service.courses().courseWork()

addon_context_response = parent.getAddOnContext(
    courseId=flask.session["courseId"],
    itemId=flask.session["itemId"]).execute()

Cette méthode renvoie des informations sur le rôle de l'utilisateur actuel dans le cours. Modifiez la vue présentée à l'utilisateur en fonction de son rôle. Exactement l'un des studentContext ou teacherContext champs est renseigné dans l'objet de réponse. Examinez-les pour déterminer comment vous adresser à l'utilisateur.

Dans tous les cas, utilisez la valeur du paramètre de requête attachmentId pour savoir quelle pièce jointe récupérer dans notre base de données. Ce paramètre de requête est fourni lors de l'ouverture des URI des vues de l'enseignant ou de l'élève.

# Determine which view we are in by testing the returned context type.
user_context = "student" if addon_context_response.get(
    "studentContext") else "teacher"

# Look up the attachment in the database.
attachment = Attachment.query.get(flask.session["attachmentId"])

# Set the text for the next page depending on the user's role.
message_str = f"I see that you're a {user_context}! "
message_str += (
    f"I've loaded the attachment with ID {attachment.attachment_id}. "
    if user_context == "teacher" else
    "Please enjoy this image of a famous landmark!")

# Show the content with the customized message text.
return flask.render_template(
    "show-content-attachment.html",
    message=message_str,
    image_filename=attachment.image_filename,
    image_caption=attachment.image_caption,
    responses=response_strings)

Tester le module complémentaire

Pour tester la création de pièces jointes, procédez comme suit :

• Connectez-vous à [Google Classroom] en tant qu'utilisateur test Enseignant.
• Accédez à l'onglet Travaux et devoirs , puis créez un devoir.
• Cliquez sur le bouton Modules complémentaires sous la zone de texte, puis sélectionnez votre module complémentaire. L'iframe s'ouvre et le module complémentaire charge l'URI de configuration des pièces jointes que vous avez spécifié dans la page "Configuration de l'application" du SDK Google Workspace Marketplace.
• Choisissez un élément de contenu à joindre au devoir.
• Fermez l'iframe une fois le flux de création de pièces jointes terminé.

Une fiche de pièce jointe devrait s'afficher dans l'interface utilisateur de création de devoirs dans Google Google Classroom. Cliquez sur la fiche pour ouvrir l'iframe de la vue de l'enseignant et vérifiez que la pièce jointe correcte s'affiche. Cliquez sur le bouton Attribuer.

Pour tester l'expérience de l'élève, procédez comme suit :

• Connectez-vous ensuite à Classroom en tant qu'utilisateur test élève dans le même cours que l'utilisateur test enseignant.
• Recherchez le devoir test dans l'onglet "Travaux et devoirs".
• Développez le devoir, puis cliquez sur la fiche de pièce jointe pour ouvrir l'iframe de la vue de l'élève.

Vérifiez que la pièce jointe correcte s'affiche pour l'élève.

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