Créer un module complémentaire Classroom

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

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

Dans ce tutoriel, vous allez:

• Créez un projet Google Cloud pour votre module complémentaire.
• Créez une application Web squelette avec des espaces réservés pour les boutons de connexion.
• Publiez une fiche Play Store Google Workspace Marketplace pour votre module complémentaire.

Une fois que vous avez terminé, vous pouvez installer votre module complémentaire et le charger dans l'iFrame des modules complémentaires Classroom.

Conditions préalables

Sélectionnez une langue pour afficher les prérequis appropriés:

python -m ensurepip --upgrade

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

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

npm install

java --version
./mvnw --version

java -version
mvnw.cmd --version

Configurer un projet Google Cloud

L'accès à l'API Classroom et aux méthodes d'authentification requises sont contrôlés par des projets Google Cloud. Les instructions suivantes vous guident à travers 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 indiquer n'importe quel nom pour le nouveau projet. Cliquez sur Créer.

La création du projet peut prendre quelques instants. Une fois cela fait, veillez à sélectionner le projet. Vous pouvez le choisir 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 de notifications en haut à droite.

Associer le SDK Google Workspace Marketplace au projet Google Cloud

Accédez au navigateur de la bibliothèque d'API. Recherchez Google Workspace Marketplace SDK. Le SDK doit apparaître dans la liste des résultats.

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

Configurer le SDK Google Workspace Marketplace

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

Configuration de l'application

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

• Définissez la Visibilité de l'application sur Public ou Private.

  • Le paramètre public est destiné aux applications qui seront à terme publiées auprès des utilisateurs finaux. Une application publique doit être soumise à un processus d'approbation avant d'être publiée auprès des utilisateurs finaux. Toutefois, vous pouvez spécifier des utilisateurs autorisés à l'installer et à la tester en tant que brouillon. Il s'agit d'un état de prépublication qui vous permet de tester et de développer votre module complémentaire avant de l'envoyer pour approbation.
  • Le paramètre "Privé" est adapté au développement et aux tests internes. Une application privée ne peut être installée que par des utilisateurs appartenant au même domaine que celui où le projet a été créé. Par conséquent, vous devez définir la visibilité sur "Privée" uniquement si le projet a été créé dans un domaine associé à un abonnement Google Workspace for Education. Sinon, vos utilisateurs tests ne pourront pas lancer les modules complémentaires Classroom.

• Définissez Paramètres d'installation sur Admin Only install si vous souhaitez limiter l'installation aux administrateurs de domaine.

• Sous Intégration d'applications, sélectionnez Module complémentaire Classroom. Vous êtes invité à saisir l'URI de configuration de pièce jointe sécurisé. Il s'agit de l'URL qui devrait être chargée lorsqu'un utilisateur ouvrira 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 des 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 l'utilisation de caractères génériques pour le moment. Ajoutez au moins le domaine racine de votre serveur de contenu, tel que https://localhost:5000/ ou https://cdn.myedtech.com/.

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

• Renseignez les champs appropriés pour votre organisation sous Liens pour les développeurs.

Fiche Play Store

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

• Sous Informations sur 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 d'application et des descriptions. Ils apparaîtront sur la fiche Play Store Google Workspace Marketplace de votre module complémentaire. Cliquez sur OK pour enregistrer.
• Choisissez une catégorie pour votre module complémentaire.
• Sous Éléments graphiques, fournissez des images pour les champs obligatoires. Ceux-ci peuvent être modifiés ultérieurement et peuvent être des espaces réservés pour le moment.
• Sous Liens d'assistance, indiquez 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.

Si vous avez défini la visibilité de l'application sur Privé à l'étape précédente, cliquez sur PUBLIER. Votre application est immédiatement disponible pour l'installation. Si vous définissez la visibilité de l'application sur Public, ajoutez des adresses e-mail dans la zone Testeurs de brouillons pour tous les utilisateurs tests, puis cliquez sur Enregistrer le brouillon.

Écran de consentement OAuth

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

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

• Définissez User Type (Type d'utilisateur) sur External (Externe). Cliquez sur Créer.
• Sur la page suivante, renseignez les informations requises sur l'application, ainsi que les coordonnées. Indiquez tous les domaines hébergeant votre application sous Domaines autorisés. Cliquez sur ENREGISTRER ET CONTINUER.

• Ajoutez les champs d'application OAuth requis par votre application Web. Consultez le guide de configuration OAuth pour une discussion approfondie sur les champs d'application et leur objectif.

  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 dont votre application a besoin de la part des utilisateurs finaux.

  Cliquez sur SAVE AND CONTINUE (ENREGISTRER ET CONTINUER).

• Listez les adresses e-mail de tous les comptes de test sur la page Utilisateurs tests. Cliquez sur ENREGISTRER ET CONTINUER.

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

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 Marketplace. Cliquez sur l'URL de l'application en haut de la page pour afficher la liste, puis sélectionnez Installer.

Créer une application Web de base

Configurer une application Web squelette avec deux routes Les prochaines étapes du tutoriel développeront cette application. Pour l'instant, créez simplement une page de destination pour le module complémentaire /addon-discovery et une page d'index fictive / pour notre "site de l'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, l'un pour fermer l'iFrame du module complémentaire et l'autre 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. Vous allez découvrir une méthode permettant de faire passer l'utilisateur dans un nouvel onglet en toute sécurité pour une autorisation dans le tutoriel suivant.

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, 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 /.

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

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

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."

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)

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

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

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

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

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

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

/** 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

Lancez votre serveur. Ensuite, connectez-vous à Google Classroom en tant qu'utilisateur test Enseignant. Accédez à l'onglet Travaux et devoirs et créez un devoir. Sélectionnez votre module complémentaire dans le sélecteur Modules complémentaires. 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 Marketplace.

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