Cette série de tutoriels présente tous les éléments mobiles d'un module complémentaire Classroom fonctionnel. Chaque étape du tutoriel traite de concepts spécifiques, en les implémentant 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 aux API et le SDK GWM dans la console Google Cloud. Pour en savoir plus sur le SDK GWM, consultez la page du guide sur la fiche Google Workspace Marketplace.
Ce guide couvre les sujets suivants :
- Utilisez Google Cloud pour créer une page à afficher dans un iFrame dans Classroom.
- Ajoutez l'authentification unique (SSO) Google et autorisez les utilisateurs à se connecter.
- Effectuez des appels d'API pour joindre votre module complémentaire à un devoir.
- Respectez les principales exigences concernant l'envoi de modules complémentaires et les fonctionnalités requises.
Dans ce guide, nous partons 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 tutoriels. Cette page contient des détails de configuration importants qui ne sont pas entièrement abordés dans les tutoriels.
Exemples de mise en œuvre
Des exemples de référence complets sont disponibles dans les langages JavaScript, Python et Java. Ces implémentations sont les sources de l'exemple de code trouvé dans les pages suivantes.
Où télécharger
Vous pouvez télécharger des archives complètes de nos exemples à l'aide des liens ci-dessous.
Prérequis
Consultez les sections suivantes pour préparer un nouveau projet de modules complémentaires.
Certificat HTTPS
Vous pouvez héberger votre application dans n'importe quel environnement de développement, mais le module complémentaire Classroom n'est disponible que via https://
. Par conséquent, vous avez 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. Utilisez mkcert si vous devez créer un certificat pour le développement local.
Projet Google Cloud
Vous devez configurer un projet Google Cloud à utiliser avec ces exemples. Consultez le guide de création de projet Google Cloud pour obtenir un aperçu des étapes nécessaires pour commencer. La section Configurer un projet Google Cloud du premier tutoriel décrit également les actions de configuration spécifiques à effectuer.
Lorsque vous avez 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'exemples décompressé. Consultez la section Comprendre les fichiers pour des emplacements spécifiques.
Identifiants OAuth
Pour créer des identifiants OAuth, procédez comme suit:
- Accédez à la page Identifiants Google Cloud. Assurez-vous d'avoir sélectionné le bon projet en haut de l'écran.
- Cliquez sur CRÉER DES IDENTIFIANTS et sélectionnez ID client OAuth dans la liste déroulante.
- 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 d'accès complet pour une route de rappel pour votre application. Exemples :
https://my.domain.com/auth-callback
ouhttps://localhost:5000/callback
. Vous créerez et gérerez cet itinéraire plus tard dans ce tutoriel. Vous pouvez modifier ou ajouter d'autres itinéraires de ce type à tout moment. - Cliquez sur CRÉER.
- Une boîte de dialogue contenant les identifiants que vous venez de créer s'affiche. Sélectionnez l'option TÉLÉCHARGER JSON. Copiez le fichier
.json
téléchargé dans le répertoire de votre serveur.
Conditions préalables spécifiques aux langues
Consultez le fichier README de chaque archive pour obtenir la liste la plus récente des conditions préalables.
Python
Notre exemple Python utilise le framework Flask. Vous pouvez télécharger le code source complet en cliquant sur le lien ci-dessus.
Si nécessaire, installez Python 3.7+, puis 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
Il existe un requirements.txt
dans chaque sous-répertoire du tutoriel des exemples téléchargés. Vous pouvez installer rapidement les bibliothèques requises à l'aide de pip
. Exécutez les commandes suivantes pour installer les bibliothèques requises pour le premier 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 en cliquant sur le lien ci-dessus.
Cet exemple nécessite Node.js v16.13 ou une version ultérieure.
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 en cliquant sur le lien ci-dessus.
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.
Dans le répertoire dans lequel vous avez téléchargé ou cloné le projet, exécutez les commandes suivantes pour vous assurer que vous disposez des conditions préalables à l'exécution du projet.
java --version
./mvnw --version
Ou sous Windows :
java -version
mvnw.cmd --version
Comprendre les fichiers
Les sections suivantes décrivent la mise en page des exemples de répertoires.
Noms des répertoires
Chaque archive contient plusieurs répertoires dont le nom commence par un chiffre, tel que /01-basic-app/
. Les chiffres correspondent à des étapes spécifiques de la procédure. Chaque répertoire contient une application Web entièrement fonctionnelle qui implémente les fonctionnalités décrites dans un tutoriel particulier. Par exemple, le répertoire /01-basic-app/
contient l'implémentation finale du tutoriel Créer un module complémentaire.
Contenu du répertoire
Le contenu du répertoire varie en fonction du langage d'implémentation:
Python
La racine du répertoire contient les fichiers suivants:
main.py
: point d'entrée de l'application Python. Spécifiez la configuration de serveur que vous souhaitez utiliser dans ce fichier, puis exécutez-la pour démarrer le serveur.requirements.txt
: modules Python requis pour exécuter l'application Web. Ils peuvent être installés automatiquement à l'aide depip install -r requirements.txt
.client_secret.json
: fichier secret du client téléchargé à partir de Google Cloud. Notez que cela n'est pas inclus dans l'exemple d'archive. Vous devez renommer et copier le fichier d'identifiants téléchargé à la racine de chaque répertoire.
config.py
: options de configuration du serveur Flask.Le répertoire
webapp
comporte le contenu de l'application Web. Elle comprend les éléments suivants :Répertoire
/templates/
avec les modèles Jinja pour différentes pages.Le répertoire
/static/
contenant des images, des fichiers CSS et des fichiers JavaScript auxiliairesroutes.py
: méthodes de gestionnaire pour les routes de l'application Web.__init__.py
est l'initialiseur du modulewebapp
. Cet initialiseur démarre le serveur Flask et charge les options de configuration définies dansconfig.py
.Fichiers supplémentaires requis par une étape de tutoriel spécifique.
Node.js
Chaque étape de la présentation se trouve dans son propre sous-dossier <step>
. Chaque étape contient:
- Les fichiers statiques tels que JavaScript, CSS et les images se trouvent dans le dossier
./<step>/public
. - Les routeurs Express se trouvent dans les dossiers
./<step>/routes
. - Les modèles HTML se trouvent dans les dossiers
./<step>/views
. - L'application du 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 correctement. Ce répertoire comprend les éléments suivants : + Le répertoirejava.com.addons.spring
contient les fichiersApplication.java
etController.java
. Le fichierApplication.java
est responsable de l'exécution du serveur d'applications, tandis que le fichierController.java
gère la logique du point de terminaison. +resources
contient le répertoiretemplates
avec les fichiers HTML et JavaScript. Il contient également le fichierapplication.properties
qui spécifie le port sur lequel exécuter le serveur, le chemin d'accès au fichier keystore et le chemin d'accès au répertoiretemplates
. Cet exemple inclut le fichier keystore dans le répertoireresources
. Vous pouvez le stocker où vous le souhaitez, mais veillez à mettre à jour le fichierapplication.properties
avec le chemin d'accès en conséquence.pom.xml
contient les informations nécessaires pour compiler le projet et définir les dépendances requises..gitignore
contient des noms de fichiers qui ne doivent pas être importés dans Git. Veillez à ajouter le chemin d'accès à votre keystore dans ce.gitignore
. Dans l'exemple fourni, il s'agit desecrets/*.p12
(l'objectif du keystore est abordé dans la section ci-dessous). Pour les étapes suivantes du tutoriel 2, vous devez également inclure le chemin d'accès au fichierclient_secret.json
pour vous assurer de ne pas inclure vos secrets dans un dépôt distant. Pour le tutoriel 3 et les versions ultérieures, vous devez ajouter le chemin d'accès au fichier de base de données H2 et à la fabrique du datastore de fichiers. Pour en savoir plus sur la configuration de ces datastores, consultez le troisième tutoriel sur la gestion des visites répétées.mvnw
etmvnw.cmd
sont les exécutables de wrapper Maven pour Unix et Windows, respectivement. Par exemple, l'exécution de./mvnw --version
sur Unix renvoie la version d'Apache Maven, entre autres.- 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 les instructions ci-dessous pour exécuter l'exemple de serveur dans le langage de votre choix:
Python
Identifiants OAuth
Créez et téléchargez vos identifiants OAuth comme décrit ci-dessus. Placez le fichier .json
dans le répertoire racine avec le 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)
Sécurisez
localhost
. Vous devez spécifier un tuple de fichiers de clé SSL pour l'argumentssl_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)
Gunicorn. Cela 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 que configuré à l'étape précédente.
python main.py
Cliquez sur l'URL qui s'affiche pour afficher votre application Web dans un navigateur afin de vérifier qu'elle fonctionne correctement.
Node.js
Configurer le serveur
Pour exécuter le serveur via HTTPS, vous devez créer un autocertificat permettant d'exécuter l'application via HTTPS. Ces identifiants doivent être enregistrés sous sslcert/cert.pem
et sslcert/key.pem
dans le dossier racine du dépôt. Vous devrez peut-être ajouter ces clés à la chaîne de clés de votre 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 effectuer de commit sur git.
Lancer le serveur
Vous pouvez exécuter l'application à l'aide de 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
ou
npm run step02
Le serveur Web est lancé à l'adresse https://localhost:5000
.
Vous pouvez arrêter le serveur en indiquant Control + C
dans votre terminal.
Java
Configurer le serveur
Pour exécuter le serveur via HTTPS, vous devez créer un autocertificat permettant d'exécuter l'application via HTTPS.
Envisagez d'utiliser mkcert pour le développement local.
Une fois que vous avez installé mkcert
, les commandes suivantes génèrent un certificat stocké localement à exécuter via HTTPS.
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
Cet exemple inclut le fichier keystore dans le répertoire "resources". Vous pouvez le stocker où vous le souhaitez, mais veillez à mettre à jour le fichier application.properties
avec le chemin d'accès en conséquence. Le nom de domaine est le domaine 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 effectuer de commit sur 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 située à 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
Cette action lance le serveur à l'adresse https://localhost:5000
ou sur le port que vous avez spécifié dans application.properties
.