Tutoriels

Cette série de tutoriels illustre les éléments mobiles d'un environnement Module complémentaire Classroom. Chaque étape du tutoriel aborde des concepts, en les implémentant dans une seule application Web. L'objectif est de vous aider pour la configuration et le lancement d'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 Google Workspace Marketplace console Google Cloud. Pour en savoir plus sur la SDK Marketplace, consultez le site Google Workspace Marketplace des fiches.

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 ;
  • Effectuez des appels d'API pour associer votre module complémentaire à un devoir.
  • Répondez aux principales exigences liées à l'ajout de modules complémentaires et aux fonctionnalités requises.

Ce guide part du principe que vous maîtrisez la programmation et les principes de base du de développement. Nous vous recommandons vivement de lire le document Configuration du projet avant de commencer les tutoriels. Cette page contient des informations des détails de configuration qui ne sont pas entièrement traités dans les tutoriels.

Exemples de mise en œuvre

Un exemple de référence complet est disponible en Python. Implémentations partielles sont également disponibles en Java et en Node.js. Ces implémentations sont sources de l'exemple de code dans les pages suivantes.

Emplacement de téléchargement

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

Vous pouvez télécharger l'exemple Node.js sous forme de fichier ZIP:

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, Le module complémentaire Classroom est uniquement disponible via https://. Par conséquent, vous avez besoin d'un serveur avec chiffrement SSL pour déployer votre application ou la tester 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 à utiliser avec ces exemples. Consultez les guide de création de projets Google Cloud pour obtenir un aperçu des pour commencer. La page Configurer un projet Google Cloud du premier tutoriel, quant à lui, décrit la configuration spécifique les mesures à prendre.

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 dans le répertoire d'exemple décompressé. Reportez-vous à la section Comprendre les 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 que 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 la liste déroulante.
  • Sur la page suivante: <ph type="x-smartling-placeholder">
      </ph>
    • Définissez le Type d'application sur Application Web.
    • Sous URI de redirection autorisés, cliquez sur Ajouter un URI. Ajoutez le complet (un chemin d'accès) pour une route de rappel pour votre application. Par exemple : https://my.domain.com/auth-callback ou https://localhost:5000/callback Vous créez et gérez cette route dans la suite de 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 s'affiche avec les identifiants que vous venez de créer. Sélectionnez l'icône TÉLÉCHARGER JSON. Copiez le fichier JSON téléchargé sur votre serveur. .

Conditions préalables spécifiques à la langue

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

Python

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

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

python3 -m ensurepip --upgrade

Nous vous recommandons également de configurer et d'activer un nouveau environnement.

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

Il y a un requirements.txt dans chaque sous-répertoire du tutoriel du que vous avez téléchargés. Vous pouvez installer rapidement les bibliothèques requises pip Utilisez 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 à partir des liens fournis.

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

Installez Java 11 ou une version ultérieure 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 qu'une sans que vous ayez à installer Maven lui-même.

Dans le répertoire dans lequel vous avez téléchargé ou cloné le projet, exécutez la les commandes suivantes pour vous assurer que vous disposez de tous les éléments nécessaires pour exécuter le 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 dépôt contient plusieurs répertoires dont les noms commencent par un nombre, comme /01-basic-app/. Les numéros correspondent à des étapes spécifiques du tutoriel. Chaque répertoire contient une application Web entièrement fonctionnelle qui implémente les fonctionnalités décrit dans un tutoriel particulier. Par exemple, /01-basic-app/ contient l'implémentation finale de l'option Create an add-on (Créer un module complémentaire). de ce tutoriel.

Contenu du répertoire

Le contenu de l'annuaire diffère 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écifier le serveur que vous souhaitez utiliser dans ce fichier, puis exécutez-la démarrer le serveur.
    • requirements.txt : modules Python requis pour exécuter l'application Web. Ceux-ci peuvent être installés automatiquement à l'aide de pip install -r requirements.txt.

    • client_secret.json : fichier du code secret du client téléchargé depuis Google Google Cloud. Notez qu'elle n'est pas incluse dans l'exemple d'archive. vous devez renommer et copier le fichier d'identifiants téléchargé racine du 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 des modèles Jinja pour différentes pages.

  • Répertoire /static/ avec les images, CSS et le code JavaScript annexe .

  • routes.py : méthodes de gestionnaire pour les routes de l'application Web.

  • __init__.py : initialiseur du module webapp. Ce L'initialiseur démarre le serveur Flask et charge les options de configuration défini dans config.py.

  • Fichiers supplémentaires requis par une étape spécifique du tutoriel.

Node.js

Chaque étape de la présentation est disponible 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 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 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 à exécuter l'application. Ce répertoire comprend les éléments suivants: + Le répertoire java.com.addons.spring contient le répertoire Fichiers Application.java et Controller.java. La Application.java est responsable de l'exécution du serveur d'applications, tandis que le fichier Controller.java gère la logique du point de terminaison. + Le répertoire resources contient le répertoire templates avec les fichiers HTML et JavaScript. Il contient également les application.properties qui spécifie le port d'exécution du les chemins d'accès au fichier keystore et au templates. Cet exemple inclut le fichier keystore dans le répertoire resources. Vous pouvez les stocker où vous le souhaitez que vous préférez, mais veillez à mettre à jour les application.properties contenant le chemin d'accès en conséquence.
    • pom.xml contient les informations nécessaires à la création du projet. 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 de secrets/*.p12 (l'objectif de la keystore est abordée dans la section ci-dessous). Pour les tutoriels 2 et au-delà, vous devez également inclure le chemin d'accès client_secret.json pour vous assurer de ne pas inclure vos dans un dépôt distant. Pour le tutoriel 3 et les suivants, vous doit ajouter le chemin d'accès au fichier de base de données H2 et au datastore de fichiers usine. Pour en savoir plus sur la configuration de ces datastores, disponible dans le troisième tutoriel sur la gestion des visites répétées.
    • mvnw et mvnw.cmd sont les exécutables du wrapper Maven pour Unix. Windows. Par exemple, si vous exécutez ./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 afin de le tester. Suivez ces instructions pour Exécutez 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 précédemment. Lieu le fichier JSON qui se trouve dans le répertoire racine avec le serveur de votre application ; fichier de lancement.

Configurer le serveur

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

  1. localhost non sécurisé. Notez qu'il s'agit d'un test direct, dans une fenêtre de navigateur uniquement. des domaines non sécurisés ne peuvent pas être chargés 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)

  2. Sécurisez localhost. Vous devez spécifier un tuple de fichiers de clé SSL pour le 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)

  3. Gunicorn. Cela convient à un serveur prêt pour la production déploiement cloud. Nous vous recommandons de définir une variable d'environnement PORT pour 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 conformément à la configuration à l'étape précédente.

python main.py

Cliquez sur l'URL qui s'affiche pour afficher votre application Web dans un navigateur pour vérifier que elle fonctionne correctement.

Node.js

Configurer le serveur

Pour exécuter le serveur via HTTPS, vous devez créer un autocertificat utilisé pour exécuter l'application via HTTPS. Ces identifiants doivent être enregistré en tant que sslcert/cert.pem et sslcert/key.pem à la racine du dépôt . Vous devrez peut-être ajouter ces clés à votre trousseau de système d'exploitation afin que votre navigateur pour les accepter.

Assurez-vous que *.pem se trouve dans le fichier .gitignore, car vous ne voulez pas pour effectuer un commit du fichier dans Git.

Lancer le serveur

Vous pouvez exécuter l'application à l'aide de la commande suivante en remplaçant step01 pour 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 alors lancé à l'adresse 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 autocertificat 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 à exécuter HTTPS

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

Cet exemple inclut le fichier keystore dans le répertoire de ressources. Vous pouvez stockez-les où vous le souhaitez, mais veillez à mettre à jour 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 le fichier .gitignore, car vous ne voulez pas pour effectuer un commit du fichier dans Git.

Lancer le serveur

Pour lancer le serveur, exécutez la méthode main dans Application.java. . Dans IntelliJ, par exemple, vous pouvez effectuer un clic droit Application.java > Run 'Application' dans src/main/java/com/addons/spring ou ouvrez Application.java. pour cliquer sur la flèche verte située à gauche du main(String[] args) signature de la méthode. Vous pouvez également exécuter le projet dans un terminal période:

./mvnw spring-boot:run

Ou sous Windows :

mvnw.cmd spring-boot:run

Cela lance le serveur à https://localhost:5000 ou sur le port que vous spécifié dans application.properties.