Les modules complémentaires Google Classroom sont désormais disponibles pour tous les développeurs. Pour en savoir plus, consultez la documentation sur les modules complémentaires.

Tutoriels

Cette série de procédures pas à pas illustre tous les éléments mobiles d'un module complémentaire Classroom fonctionnel. Chaque étape de la procédure pas à pas aborde des concepts spécifiques et les met en œuvre dans une seule application Web. L'objectif est de vous aider à configurer et à lancer un module complémentaire fonctionnel.

Votre module complémentaire doit interagir avec un projet Google Cloud. Si vous ne connaissez pas Google Cloud, nous vous recommandons de lire les guides de démarrage. Vous gérez les identifiants, l'accès à l'API et le SDK Google Workspace Marketplace dans la console Google Cloud. Pour en savoir plus sur le SDK Marketplace, consultez la page du guide sur la fiche Google Workspace Marketplace .

Ce guide couvre les sujets suivants :

Utiliser Google Cloud pour créer une page à afficher dans un iframe dans Classroom
Ajouter l'authentification unique (SSO) Google et autoriser les utilisateurs à se connecter
Effectuer des appels d'API pour associer votre module complémentaire à un devoir
Répondre aux exigences clés de la demande de module complémentaire et aux fonctionnalités requises

Ce guide part du principe que vous connaissez la programmation et les concepts fondamentaux du développement Web. Nous vous recommandons vivement de lire le guide de configuration du projet avant de commencer les procédures pas à pas. Cette page contient des détails de configuration importants qui ne sont pas entièrement couverts dans les procédures pas à pas.

Exemples de mise en œuvre

Un exemple de référence complet est disponible en Python. Des mises en œuvre partielles sont également disponibles en Java et Node.js. Ces mises en œuvre sont les sources de l'exemple de code que vous trouverez dans les pages suivantes.

Où télécharger

Les exemples Python et Java sont disponibles dans les dépôts GitHub suivants :

L'exemple Node.js peut être téléchargé sous forme de fichier zip :

Archive Node.js

Prérequis

Consultez les sections suivantes pour préparer un nouveau projet de module complémentaire.

Certificat HTTPS

Bien que vous puissiez héberger votre application dans n'importe quel environnement de développement, votre module complémentaire Classroom n'est disponible que via https://. Vous avez donc besoin d'un serveur avec chiffrement SSL pour déployer votre application ou la tester dans l'iframe du module complémentaire.

Il est possible d'utiliser localhost avec un certificat SSL. Envisagez d'utiliser mkcert si vous devez créer un certificat pour le développement local.

Projet Google Cloud

Vous devez configurer un projet Google Cloud pour l'utiliser avec ces exemples. Consultez le guide de création d'un projet Google Cloud pour obtenir une présentation des étapes nécessaires pour commencer. La section Configurer un projet Google Cloud de la première procédure pas à pas décrit également les actions de configuration spécifiques à effectuer.

Une fois terminé, téléchargez votre ID client OAuth 2.0 sous forme de fichier JSON. Vous devez ajouter ce fichier d'identifiants au répertoire d'exemple décompressé. Pour connaître les emplacements spécifiques, consultez la section Interpréter les fichiers.

Identifiants OAuth

Pour créer des identifiants OAuth, procédez comme suit :

Accédez à la page Identifiants Google Cloud. Assurez-vous que le bon projet est sélectionné en haut de l'écran.
Cliquez sur CRÉER DES IDENTIFIANTS , puis sélectionnez ID client OAuth dans le menu déroulant.
Sur la page suivante :
- Définissez le type d'application sur Application Web.
- Sous URI de redirection autorisés, cliquez sur AJOUTER UN URI. Ajoutez le chemin complet d'une route de rappel pour votre application. Par exemple, https://my.domain.com/auth-callback ou https://localhost:5000/callback. Vous créerez et gérerez cette route plus tard dans cette procédure pas à pas. Vous pouvez modifier ou ajouter d'autres routes de ce type à tout moment.
- Cliquez sur CRÉER.
Une boîte de dialogue s'affiche alors avec les identifiants que vous venez de créer. Sélectionnez l'option TÉLÉCHARGER JSON. Copiez le fichier JSON téléchargé dans le répertoire de votre serveur.

Prérequis spécifiques à la langue

Consultez le fichier README de chaque dépôt pour obtenir la liste la plus récente des prérequis.

Python

Notre exemple Python utilise le framework Flask. Vous pouvez télécharger le code source complet à partir des liens fournis.

Si nécessaire, installez Python 3.7 ou version ultérieure et assurez-vous que pip est disponible.

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

Un fichier requirements.txt est présent dans chaque sous-répertoire de la procédure pas à pas des exemples téléchargés. Vous pouvez installer rapidement les bibliothèques requises à l'aide de pip. Utilisez les commandes suivantes pour installer les bibliothèques requises pour la première procédure pas à pas.

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 à partir des liens fournis.

Cet exemple nécessite Node.js v16.13 ou version ultérieure.

Installez les modules de nœuds 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 à partir des liens fournis.

Installez Java 11 ou version ultérieure si ce n'est pas déjà fait sur votre ordinateur.

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 un build réussi sans que vous ayez à installer Maven lui-même.

Dans le répertoire où vous avez téléchargé ou cloné le projet, exécutez les commandes suivantes pour vous assurer que vous disposez des prérequis nécessaires à l'exécution du projet.

java --version
./mvnw --version

Ou sous Windows :

java -version
mvnw.cmd --version

Interpréter les fichiers

Les sections suivantes décrivent la mise en page des répertoires d'exemple.

Noms de répertoire

Chaque dépôt contient plusieurs répertoires dont le nom commence par un chiffre, par exemple /01-basic-app/. Les chiffres correspondent à des étapes spécifiques de la procédure pas à pas. Chaque répertoire contient une application Web entièrement fonctionnelle qui met en œuvre les fonctionnalités décrites dans une procédure pas à pas particulière. Par exemple, le /01-basic-app/ répertoire contient la mise en œuvre finale de la procédure pas à pas Créer un module complémentaire.

Contenu du répertoire

Le contenu du répertoire varie en fonction du langage de mise en œuvre :

Python

La racine du répertoire contient les fichiers suivants :
- main.py : point d'entrée de l'application Python. Spécifiez la configuration du serveur que vous souhaitez utiliser dans ce fichier, puis exécutez-le pour démarrer le serveur.
- requirements.txt : modules Python requis pour exécuter l'application Web. Ils peuvent être installés automatiquement à l'aide de pip install -r requirements.txt.
- client_secret.json : fichier de code secret du client téléchargé depuis Google Cloud. Notez qu'il n'est pas inclus dans l'archive d'exemple. Vous devez renommer et copier votre fichier d'identifiants téléchargé dans chaque racine de répertoire.
  
  Important : Vous devez fournir le fichier de code secret du client à partir de votre projet Google Cloud avant de pouvoir exécuter les exemples.
config.py : options de configuration pour le serveur Flask.
Le répertoire webapp contient le contenu de l'application Web. Il comprend les éléments suivants :
Le répertoire /templates/ avec des modèles Jinja pour différentes pages.
Le répertoire /static/ avec des images, des fichiers CSS et des fichiers JavaScript auxiliaires.
routes.py : méthodes de gestion pour les routes de l'application Web.
__init__.py : initialiseur pour le module webapp. Cet initialiseur démarre le serveur Flask et charge les options de configuration définies dans config.py.
Fichiers supplémentaires requis par une étape particulière de la procédure pas à pas.

Node.js

Chaque étape de la procédure pas à pas se trouve dans son propre <step> sous-dossier. Chaque étape contient les éléments suivants :

Les fichiers statiques tels que JavaScript, CSS et les images se trouvent dans le ./<step>/public dossier.
Les routeurs Express se trouvent dans les dossiers ./<step>/routes.
Les modèles HTML se trouvent dans les dossiers ./<step>/views.
L'application de serveur est ./<step>/app.js.

Java

Le répertoire du projet comprend les éléments suivants :

Le répertoire src.main contient le code source et la configuration permettant d'exécuter l'application. Ce répertoire comprend les éléments suivants : + Le répertoire java.com.addons.spring contient les fichiers Application.java et Controller.java. Le Application.java fichier est responsable de l'exécution du serveur d'applications, tandis que le Controller.java fichier gère la logique du point de terminaison. + Le répertoire resources contient le répertoire templates avec des fichiers HTML et JavaScript. Il contient également le application.properties fichier qui spécifie le port d'exécution du serveur, le chemin d'accès au fichier de keystore et le chemin d'accès au templates répertoire. Cet exemple inclut le fichier de keystore dans le resources répertoire. Vous pouvez le stocker où vous le souhaitez, mais assurez-vous de mettre à jour le application.properties fichier avec le chemin d'accès approprié.
- pom.xml contient les informations nécessaires pour créer le projet et définir les dépendances requises.
- .gitignore contient les noms de fichiers qui ne doivent pas être importés dans Git. Assurez-vous d'ajouter le chemin d'accès à votre keystore dans ce fichier .gitignore. Dans l'exemple fourni, il s'agit de secrets/*.p12 (l'objectif du keystore est abordé dans la section ci-dessous). Pour la procédure pas à pas 2 et les suivantes, vous devez également inclure le chemin d'accès à votre fichier client_secret.json pour vous assurer de ne pas inclure vos secrets dans un dépôt distant. Pour la procédure pas à pas 3 et les suivantes, vous devez ajouter le chemin d'accès au fichier de base de données H2 et à la fabrique de datastore de fichiers. Pour en savoir plus sur la configuration de ces datastores, consultez la troisième procédure pas à pas sur la gestion des visites répétées.
- mvnw et mvnw.cmd sont les exécutables du wrapper Maven pour Unix et Windows, respectivement. Par exemple, l'exécution de ./mvnw --version sur Unix génère la version d'Apache Maven, entre autres informations.
- Le répertoire .mvn contient la configuration du wrapper Maven.

Exécuter l'exemple de serveur

Vous devez lancer votre serveur pour le tester. Suivez ces instructions pour exécuter l'exemple de serveur dans la langue de votre choix :

Python

Identifiants OAuth

Créez et téléchargez vos identifiants OAuth comme décrit précédemment. Placez le fichier JSON dans le répertoire racine, à côté du fichier de lancement du serveur de votre application.

Configurer le serveur

Vous disposez de plusieurs options pour exécuter le serveur Web. À la fin de votre fichier Python, ajoutez l'un des éléments suivants :

localhost non sécurisé. Notez que cette option ne convient que pour les tests directs dans une fenêtre de navigateur. Les domaines non sécurisés ne peuvent pas être chargés dans l'iframe du module complémentaire Classroom.
```
if __name__ == "__main__":
  # Disable OAuthlib's HTTPs verification.
  os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1"

  # Run the web app at http://localhost:5000.
  app.run(debug=True)
```

localhost sécurisé. Vous devez spécifier un tuple de fichiers de clé SSL pour l'argument ssl_context.

if __name__ == "__main__":
  # Run the web app at https://localhost:5000.
  app.run(host="localhost",
          ssl_context=("localhost.pem", "localhost-key.pem"),
          debug=True)

Serveur Gunicorn. Cette option convient à un serveur prêt pour la production ou à un déploiement cloud. Nous vous recommandons de définir une variable d'environnement PORT à utiliser avec cette option de lancement.

if __name__ == "__main__":
  # Run the web app at https://<your domain>:<server_port>.
  # Defaults to https://<your domain>:8080.
  server_port = os.environ.get("PORT", "8080")
  app.run(debug=True, port=server_port, host="0.0.0.0")

Lancer le serveur

Exécutez votre application Python pour lancer le serveur tel qu'il est configuré à l'étape précédente.

python main.py

Cliquez sur l'URL qui s'affiche pour afficher votre application Web dans un navigateur et vérifier qu'elle s'exécute correctement.

Node.js

Configurer le serveur

Pour exécuter le serveur via HTTPS, vous devez créer un auto-certificat qui sera utilisé pour exécuter l'application via HTTPS. Ces identifiants doivent être enregistrés sous le nom sslcert/cert.pem et sslcert/key.pem dans le dossier racine du dépôt. Vous devrez peut-être ajouter ces clés à votre trousseau de clés de système d'exploitation pour que votre navigateur les accepte.

Assurez-vous que *.pem se trouve dans votre fichier .gitignore, car vous ne souhaitez pas valider le fichier dans Git.

Lancer le serveur

Vous pouvez exécuter l'application avec la commande suivante en remplaçant step01 par l'étape correcte que vous souhaitez exécuter en tant que serveur (par exemple, step01 pour 01-basic-app et step02 pour 02-sign-in).

npm run step01

npm run step02

Le serveur Web est lancé sur https://localhost:5000.

Vous pouvez arrêter le serveur avec Control + C dans votre terminal.

Java

Configurer le serveur

Pour exécuter le serveur via HTTPS, vous devez créer un auto-certificat qui sera utilisé pour exécuter l'application via HTTPS.

Envisagez d'utiliser mkcert pour le développement local. Une fois mkcert installé, les commandes suivantes génèrent un certificat stocké localement pour s'exécuter via HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Cet exemple inclut le fichier de keystore dans le répertoire des ressources. Vous pouvez le stocker où vous le souhaitez, mais assurez-vous de mettre à jour le fichier application.properties avec le chemin d'accès approprié. Le nom de domaine est celui sur lequel vous exécutez le projet (par exemple, localhost).

Assurez-vous que *.p12 se trouve dans votre fichier .gitignore, car vous ne souhaitez pas valider le fichier dans Git.

Lancer le serveur

Lancez le serveur en exécutant la méthode main dans le fichier Application.java. Dans IntelliJ, par exemple, vous pouvez effectuer un clic droit sur Application.java > Run 'Application' dans le répertoire src/main/java/com/addons/spring, ou ouvrir le fichier Application.java pour cliquer sur la flèche verte à gauche de la signature de la méthode main(String[] args). Vous pouvez également exécuter le projet dans une fenêtre de terminal :

./mvnw spring-boot:run

Ou sous Windows :

mvnw.cmd spring-boot:run

Le serveur est lancé sur https://localhost:5000 ou sur le port que vous avez spécifié dans application.properties.

Tutoriels Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Exemples de mise en œuvre

Où télécharger

Prérequis

Certificat HTTPS

Projet Google Cloud

Identifiants OAuth

Prérequis spécifiques à la langue

Python

Node.js

Java

Interpréter les fichiers

Noms de répertoire

Contenu du répertoire

Python

Node.js

Java

Exécuter l'exemple de serveur

Python

Node.js

Java

Tutoriels