Créer un module complémentaire Classroom

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

Dans ce tutoriel, vous allez jeter les bases du développement d'une application Web et de sa publication en tant que module complémentaire Classroom. Les prochaines étapes du tutoriel développent cette application.

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

• Créez un projet Google Cloud pour votre application Web.
• Créez une application Web squelette avec des boutons de connexion d'espace réservé.
• Publiez une fiche Play Store privée Google Workspace Marketplace (GWM) pour votre application Web.

Une fois l'opération terminée, vous pouvez installer votre module complémentaire et le charger dans l'iFrame du module complémentaire Classroom.

Important :Avant de suivre ces tutoriels, consultez le guide de configuration du projet et suivez les étapes 1 à 6 du parcours développeur.

Prérequis

Choisissez une langue ci-dessous pour consulter les prérequis appropriés:

Python

Notre exemple Python utilise le framework Flask. Vous pouvez télécharger le code source complet de tous les tutoriels sur la page "Présentation". Le code de ce tutoriel spécifique se trouve dans le répertoire /flask/01-basic-app/.

Si nécessaire, installez Python 3.7+, puis assurez-vous que pip est disponible.

python -m ensurepip --upgrade

Nous vous recommandons également de configurer et d'activer un nouvel environnement virtuel Python.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

Chaque sous-répertoire du tutoriel des exemples téléchargés contient un requirements.txt. Vous pouvez installer rapidement les bibliothèques requises à l'aide de pip. Utilisez le code suivant pour installer les bibliothèques requises pour ce tutoriel.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

Notre exemple Node.js utilise le framework Express. Vous pouvez télécharger le code source complet de tous les tutoriels sur la page "Présentation".

Si nécessaire, installez NodeJS v16.13+.

Installez les modules de nœud requis à l'aide de npm.

npm install

Java

Notre exemple Java utilise le framework Spring Boot. Vous pouvez télécharger le code source complet de tous les tutoriels sur la page "Présentation".

Installez Java 11+ si ce n'est pas déjà fait.

Les applications Spring Boot peuvent utiliser Gradle ou Maven pour gérer les builds et les dépendances. Cet exemple inclut le wrapper Maven qui garantit la réussite de la compilation sans que vous ayez besoin d'installer Maven lui-même.

Pour pouvoir exécuter l'exemple fourni, exécutez les commandes suivantes dans le répertoire où vous avez téléchargé le projet afin de vous assurer que vous disposez des conditions préalables.

java --version
./mvnw --version

Ou sous Windows :

java -version
mvnw.cmd --version

Configurer un projet Google Cloud

L'accès à l'API Classroom et les méthodes d'authentification requises sont contrôlés par les projets Google Cloud. Les instructions suivantes vous expliquent les étapes minimales à suivre pour créer et configurer un projet à utiliser avec votre module complémentaire.

Créer le projet

Créez un projet Google Cloud en accédant à la page de création de projet. Vous pouvez attribuer n'importe quel nom au nouveau projet. Cliquez sur Créer.

La création complète du projet prend quelques instants. Une fois que vous avez terminé, veillez à sélectionner le projet. Vous pouvez le sélectionner dans le menu déroulant du sélecteur de projet en haut de l'écran ou cliquer sur SÉLECTIONNER UN PROJET dans le menu des notifications en haut à droite.

Important :Assurez-vous d'avoir sélectionné le bon projet avant de continuer.

Associer le SDK GWM au projet Google Cloud

Accédez au navigateur Bibliothèque d'API. Recherchez Google Workspace Marketplace SDK. Le SDK doit s'afficher dans la liste des résultats.

Sélectionnez la fiche du SDK Google Workspace Marketplace, puis cliquez sur Activer.

Configurer le SDK GWM

GWM fournit la liste via laquelle les utilisateurs et les administrateurs installent votre module complémentaire. Pour continuer, configurez l'écran de consentement OAuth, ainsi que la configuration de l'application et la fiche Play Store du SDK GWM.

Écran de consentement OAuth

L'écran de consentement OAuth s'affiche lorsque les utilisateurs autorisent votre application pour la première fois. Il les invite à autoriser votre application à accéder à leurs informations personnelles et à leurs informations de compte, conformément aux champs d'application que vous activez.

Accédez à la page de création de l'écran de consentement OAuth. Fournissez les informations suivantes :

• Définissez Type d'utilisateur sur Externe. Cliquez sur Créer.
• Sur la page suivante, renseignez les informations requises sur l'application et les coordonnées. Indiquez tous les domaines qui hébergent votre application sous Domaines autorisés. Cliquez sur ENREGISTRER ET CONTINUER.

• Ajoutez tous les champs d'application OAuth requis par votre application Web. Consultez le guide de configuration OAuth pour une présentation approfondie des champs d'application et de leur fonction.

  Vous devez demander au moins l'un des champs d'application suivants pour que Google puisse envoyer le paramètre de requête login_hint. Une explication plus détaillée de ce comportement est disponible dans notre guide de configuration OAuth:

  • https://www.googleapis.com/auth/userinfo.email (déjà inclus)
  • https://www.googleapis.com/auth/userinfo.profile (déjà inclus)

  Les champs d'application suivants sont spécifiques aux modules complémentaires Classroom:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

  Incluez également tous les autres champs d'application d'API Google requis par votre application de la part des utilisateurs finaux.

  Cliquez sur SAVE AND CONTINUE (ENREGISTRER ET CONTINUER).

• Répertoriez les adresses e-mail de tous les comptes de test sur la page Utilisateurs de test. Cliquez sur ENREGISTRER ET CONTINUER.

Vérifiez que vos paramètres sont corrects, puis revenez au tableau de bord.

Configuration de l'application

Accédez à la page Configuration de l'application du SDK GWM. Fournissez les informations suivantes :

• Définissez Visibilité de l'application sur Private. Ce paramètre est adapté à des fins de test et de développement. Il s'agit du choix approprié pour ces tutoriels. Choisissez Public uniquement si vous êtes prêt à être utilisé par le grand public.

  Avertissement :Vérifiez que le paramètre Visibilité de l'application est correct avant d'enregistrer. Une fois la visibilité de l'application définie, vous ne pouvez plus la modifier. Vous devez créer un projet Google Cloud pour définir une visibilité d'application différente.

• Définissez Installation Settings (Paramètres d'installation) sur Admin Only install si vous souhaitez restreindre l'installation aux administrateurs de domaine.

• Sous Intégration d'une application, sélectionnez Module complémentaire Classroom. Vous êtes invité à indiquer l'URI de configuration des pièces jointes sécurisé. Il s'agit de l'URL qui doit être chargée lorsqu'un utilisateur ouvre votre module complémentaire. Pour les besoins de ce tutoriel, il doit s'agir de https://<your domain>/addon-discovery.

• Les préfixes d'URI de pièces jointes autorisés permettent de valider les URI définis dans AddOnAttachment à l'aide des méthodes courses.*.addOnAttachments.create et courses.*.addOnAttachments.patch. La validation est une correspondance de préfixe de chaîne littérale et ne permet pas d'utiliser des caractères génériques pour le moment. Vous pouvez les laisser vides pour le moment.

• Ajoutez les mêmes champs d'application OAuth que ceux fournis dans votre écran de consentement OAuth à l'étape précédente.

  Avertissement :Votre module complémentaire ne peut pas être publié si la configuration de l'application spécifie des champs d'application différents de ceux indiqués sur votre écran de consentement OAuth.

• Remplissez les champs appropriés pour votre organisation sous Developer Links (Liens pour les développeurs).

Fiche Play Store

Accédez à la page Fiche Play Store du SDK GWM. Fournissez les informations suivantes :

• Sous App Details (Détails de l'application), ajoutez une langue ou développez le menu déroulant à côté de la langue déjà répertoriée. Indiquez un nom et une description de l'application. Ils apparaîtront sur la fiche Play Store GWM de votre module complémentaire. Cliquez sur OK pour enregistrer.
• Sélectionnez la catégorie pour votre module complémentaire.
• Sous Éléments graphiques, fournissez des images pour les champs obligatoires. Ils peuvent être modifiés ultérieurement et peuvent servir d'espaces réservés si vous avez défini la visibilité des applications sur Privé à l'étape précédente.
• Sous Liens d'assistance, fournissez les URL demandées. Il peut s'agir d'espaces réservés si vous avez défini la visibilité de l'application sur Privé à l'étape précédente.

Cliquez sur PUBLIER pour enregistrer vos paramètres. Si vous avez défini la visibilité de l'application sur Privé à l'étape précédente, votre application est immédiatement disponible pour l'installation. Si vous définissez la visibilité de l'application sur Public, votre application est envoyée pour examen par l'équipe GWM avant de pouvoir être installée.

Installer le module complémentaire

Vous pouvez maintenant installer votre module complémentaire à l'aide du lien situé en haut de la page Fiche Play Store du SDK GWM. Cliquez sur l'URL de l'application en haut de la page pour consulter la liste, puis sélectionnez Installer.

Remarque :Vous ne pouvez installer le module complémentaire que si vous êtes connecté avec un compte que vous avez spécifié en tant qu'utilisateur test lors de la configuration de votre écran de consentement OAuth.

Créer une application Web de base

Configurez une application Web squelette avec deux routes. Les prochaines étapes du tutoriel vont développer cette application. Par conséquent, pour l'instant, il vous suffit de créer une page de destination pour le module complémentaire /addon-discovery et une page d'index fictive / pour notre "site d'entreprise".

Implémentez ces deux points de terminaison:

• /: affiche un message de bienvenue et un bouton permettant de fermer l'onglet actuel et l'iFrame du module complémentaire.
• /addon-discovery: affiche un message de bienvenue et deux boutons: un pour fermer l'iFrame du module complémentaire, et un pour ouvrir un site Web dans un nouvel onglet.

Notez que nous ajoutons des boutons pour créer et fermer des fenêtres ou l'iFrame. Dans le tutoriel suivant, vous découvrirez comment rediriger l'utilisateur de manière sécurisée dans un nouvel onglet pour l'autorisation.

Créer un script utilitaire

Créez un répertoire static/scripts. Créez un fichier addon-utils.js. Ajoutez les deux fonctions suivantes.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function above, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Créer des routes

Implémentez les points de terminaison /addon-discovery et /.

Python

Configurer le répertoire de l'application

Pour les besoins de cet exemple, structurez la logique d'application sous la forme d'un module Python. Il s'agit du répertoire webapp dans l'exemple fourni.

Créez un répertoire pour le module "server", par exemple, webapp. Déplacez le répertoire static dans le répertoire du module. Créez également un répertoire template dans le répertoire du module. Vos fichiers HTML s'y trouvent également.

Compiler le module "server"*

Créez le fichier __init__.py dans le répertoire de votre module et ajoutez les importations et les déclarations suivantes.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Créez ensuite un fichier pour gérer les routes de l'application Web. Il s'agit de webapp/routes.py dans l'exemple fourni. Implémentez les deux routes dans ce fichier.

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Notez que nos routes transmettent une variable message à leurs modèles Jinja respectifs. Cela est utile pour identifier la page vers laquelle l'utilisateur a été dirigé.

Créer des fichiers de configuration et de lancement

Dans le répertoire racine de votre application, créez les fichiers main.py et config.py. Configurez votre clé secrète dans config.py.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

Dans votre fichier main.py, importez votre module et démarrez le serveur Flask.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

Les itinéraires sont enregistrés dans le fichier app.js avec les lignes suivantes.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/classroom-addon', addonRouter);

Ouvrez /01-basic-app/routes/index.js et examinez le code. Cet itinéraire est atteint lorsque l'utilisateur final visite le site Web de l'entreprise. L'itinéraire renvoie une réponse à l'aide du modèle de guidon index et transmet au modèle un objet de données contenant les variables title et message.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

Ouvrez la deuxième route /01-basic-app/routes/classroom-addon.js et examinez le code. Cet itinéraire est atteint lorsque la visite de l'utilisateur final est le module complémentaire. Notez que cet itinéraire utilise le modèle de guidon discovery et la mise en page addon.hbs pour afficher la page différemment du site Web de l'entreprise.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
});
});

Java

L'exemple de code Java utilise des modules pour empaqueter les étapes du tutoriel séquentiel. Comme il s'agit du premier tutoriel, le code se trouve sous le module step_01_basic_app. Il n'est pas prévu que vous implémentez votre projet à l'aide de modules. Nous vous suggérons plutôt de compiler sur un seul projet à mesure que vous suivez chaque étape du tutoriel.

Créez une classe de contrôleur Controller.java dans cet exemple de projet pour définir les points de terminaison. Dans ce fichier, importez l'annotation @GetMapping à partir de la dépendance spring-boot-starter-web.

import org.springframework.web.bind.annotation.GetMapping;

Incluez l'annotation du contrôleur du framework Spring au-dessus de la définition de classe pour indiquer l'objectif de la classe.

@org.springframework.stereotype.Controller
public class Controller {

Ensuite, implémentez les deux routes et une route supplémentaire pour la gestion des erreurs.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Tester le module complémentaire

Important :Bien que vous puissiez tester votre application directement à l'aide d'un navigateur Web, vous devez principalement la tester dans les iFrames des modules complémentaires Classroom. Le chargement de votre application Web dans un iFrame peut produire des comportements atypiques. Consultez notre guide sur les paramètres iFrame et de requête pour obtenir une description de chaque iFrame. Toutes les instructions fournies dans ce tutoriel supposent que le module complémentaire est utilisable dans le contexte d'un iFrame.

Lancez votre serveur. Connectez-vous ensuite à Google Classroom en tant qu'utilisateur test Teacher. Accédez à l'onglet Travaux et devoirs et 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é sur la page Configuration de l'application du SDK GWM.

Félicitations ! Vous êtes prêt à passer à l'étape suivante: connecter des utilisateurs avec l'authentification unique Google.