Configuration d'un projet Google Cloud

Cette page contient les informations dont vous avez besoin pour créer et configurer des projets Google Cloud pour les modules complémentaires Classroom. Les projets Google Cloud sont utilisés pour implémenter l'authentification unique Google via OAuth 2.0 (authentification unique Google), pour autoriser les requêtes effectuées par votre module complémentaire et pour gérer la fiche d'un module complémentaire dans le Google Workspace Marketplace.

Pour obtenir des informations plus générales sur la publication d'un module complémentaire sur Marketplace, consultez Publier une application.

Création de projets Google Cloud

Il existe deux types de projets à créer : un projet privé utilisé pour le développement et un projet public accessible aux utilisateurs finaux. Les libellés "publique" et "privée" font référence à la visibilité de votre application dans Google Workspace Marketplace. Une application Marketplace privée ne peut être installée que par les utilisateurs du domaine dans lequel elle a été créée, tandis qu'une application Marketplace publique est disponible pour n'importe quel domaine Google Workspace. Il doit s'agir de deux applications distinctes, car un projet ne peut pas être à la fois public et privé. Les applications publiques doivent être examinées et approuvées avant d'être disponibles sur le Marketplace.

Pour obtenir des informations générales sur la création de projets Google Cloud, consultez Créer un projet Google Cloud.

Créer un projet Google Cloud public

Ce projet représente l'application de module complémentaire accessible aux administrateurs, aux enseignants et aux élèves. Un projet public doit être examiné et approuvé par l'équipe Google Workspace Marketplace avant de pouvoir être lancé ou installé.

  1. Créez un projet Google Cloud dans votre domaine de production.

    Créer un projet Google Cloud

  2. Activez l'API Classroom dans votre projet Cloud.

    Activer l'API Classroom

  3. Activez le SDK Google Workspace Marketplace dans votre projet Cloud.

    Activer le SDK Google Workspace Marketplace

  4. Définissez la configuration de l'application visibilité de l'application du SDK Marketplace sur Publique et cochez la case Non répertoriée.

  5. Remplissez les champs obligatoires sur la page Fiche Play Store du SDK Marketplace, puis cliquez sur PUBLIER.

  6. Votre application sera examinée par l'équipe Google Workspace Marketplace. Il communiquera avec vous à l'aide de l'adresse e-mail du développeur spécifiée dans le SDK Marketplace. Une fois l'application approuvée, décochez la case Non répertoriée pour que les enseignants et les administrateurs puissent la trouver dans le Marketplace.

Créer un projet Google Cloud privé

Ce projet privé représente l'application de module complémentaire utilisée pour le développement. Elle n'est pas accessible aux utilisateurs en dehors du domaine dans lequel elle a été créée, mais elle n'a pas besoin d'être approuvée avant l'installation. Google vous recommande donc d'utiliser ce projet pour développer et tester votre module complémentaire dans un environnement contrôlé.

Pour créer un projet privé, vous devez avoir accès à un domaine Google Workspace for Education avec la licence Teaching and Learning ou Plus. Si vous n'avez pas encore accès à un tel domaine, suivez ces étapes pour configurer un domaine de démonstration Google Workspace for Education, le mettre à niveau vers une licence Plus et lui permettre d'accéder à l'API des modules complémentaires Classroom :

  1. Suivez la procédure pour obtenir un domaine de test pour les développeurs.

  2. Connectez-vous en tant qu'administrateur dans le domaine de démonstration, puis créez un projet Google Cloud.

    Créer un projet Google Cloud

    Si vous ne parvenez pas à accéder à la console Google Cloud ni à créer des projets Cloud, vérifiez les éléments suivants dans la console d'administration :

    • Accédez à la page Paramètres du compte > Paramètres d'accès basés sur l'âge, puis sélectionnez l'option Tous les utilisateurs de ce groupe ou de cette unité organisationnelle ont au moins 18 ans.
    • Sous Applications > Services Google supplémentaires :
    • Google Cloud Platform est activé pour tous les utilisateurs.
    • Le paramètre de création de projet est Autoriser les utilisateurs à créer des projets.
    • Le paramètre d'accès à Cloud Shell est Autoriser l'accès à Cloud Shell.

  3. Remplissez et envoyez le formulaire de demande de mise à niveau du domaine de démonstration. En envoyant ce formulaire, vous demandez à Google de migrer votre domaine de démonstration vers Google Workspace for Education Plus avec dix licences et d'autoriser votre projet Cloud à accéder à l'API des modules complémentaires Classroom.

    Vous recevrez un e-mail une fois les processus de mise à niveau et d'ajout à la liste d'autorisation terminés. Attribuez des licences Plus à vos comptes d'enseignant de test dans la console d'administration. Sous Annuaire > Utilisateurs, créez ou sélectionnez vos comptes enseignants de test. Dans la section Licences de chaque enseignant, vérifiez que Google Workspace for Education Plus est défini sur Attribué.

  4. Activez l'API Classroom dans votre projet Cloud.

    Activer l'API Classroom

  5. Activez le SDK Google Workspace Marketplace dans votre projet Cloud.

    Activer le SDK Google Workspace Marketplace

  6. Définissez la configuration de l'application Visibilité de l'application du SDK Marketplace sur privée.

  7. Remplissez les champs obligatoires sur la page Fiche Play Store du SDK Marketplace, puis cliquez sur PUBLIER. Une fois la fiche de l'application publiée, les utilisateurs du domaine peuvent la trouver et l'installer sur le Google Workspace Marketplace ou en accédant à l'URL de l'application affichée sur la page de la fiche du Play Store.

OAuth 2.0

L'accès à l'API Classroom nécessite le consentement de l'utilisateur pour accéder à ses données. Ces jetons sont obtenus en demandant à Google d'accéder aux habilitations OAuth pour l'utilisateur connecté et en recevant un jeton qui peut être utilisé par la suite pour effectuer des appels d'API à Google Classroom. Les autorisations doivent être configurées dans la fiche Google Workspace Marketplace pour que l'administrateur du domaine puisse donner son consentement au nom des utilisateurs de son domaine s'ils installent le module complémentaire.

Étant donné que les niveaux d'accès Classroom sont sensibles, vous devez demander la validation OAuth avant de lancer votre module complémentaire. Dans le cas contraire, les utilisateurs verront un message d'avertissement indiquant que l'application n'est pas validée, et seul un petit nombre d'entre eux pourront accéder à votre produit. Pour en savoir plus sur la validation, consultez la présentation de la séquence d'examen.

Consultez la page Champs d'application OAuth pour les API Google pour obtenir la liste détaillée de tous les champs d'application disponibles et de leurs utilisations. Pour obtenir des informations générales sur la configuration d'OAuth, consultez la page Configurer OAuth dans la documentation Workspace.

Autorisations utilisateur

Votre application Web doit demander au moins un des niveaux d'accès suivants :

  • https://www.googleapis.com/auth/userinfo.email, qui permet à une application d'afficher l'adresse e-mail de l'utilisateur.
  • https://www.googleapis.com/auth/userinfo.profile, qui permet à une application de voir des informations personnelles telles que le portrait, le prénom et le nom de famille, ainsi que d'autres informations personnelles que l'utilisateur a rendues publiques.

Une fois qu'un utilisateur a autorisé l'un de ces niveaux d'accès dans votre module complémentaire, il est identifié par le paramètre de requête login_hint. Ce paramètre est transmis à n'importe quelle URL de votre application Web lorsqu'un iFrame est ouvert. Si un utilisateur n'a autorisé aucun de ces niveaux d'accès, login_hint ne sera pas envoyé.

login_hint est un paramètre OpenID Connect standard que vous pouvez éventuellement transmettre à Google lorsque vous utilisez Se connecter avec Google ou demandez un jeton OAuth. Il est destiné à fluidifier l'expérience d'autorisation pour l'utilisateur final.

Niveaux d'accès des modules complémentaires Classroom

Les niveaux d'accès suivants sont spécifiques aux modules complémentaires Classroom :

  • https://www.googleapis.com/auth/classroom.addons.teacher, qui permet d'accéder à toutes les méthodes d'API.
  • https://www.googleapis.com/auth/classroom.addons.student, qui permet d'accéder aux opérations de validation du lancement et de lecture des pièces jointes.

Même avec un jeton d'accès OAuth valide indiquant les identifiants de l'utilisateur, les appels d'API sont soumis à des exigences supplémentaires :

  • Toutes les méthodes exigent que l'utilisateur soit un enseignant ou un élève du cours spécifié par courseId dans la requête.
  • Pour créer, modifier ou supprimer des pièces jointes, ou pour renvoyer des notes, l'utilisateur doit être un enseignant.
  • Les appels à un post Google Classroom spécifique sont soumis aux vérifications suivantes.
    • Lorsqu'un module complémentaire comporte déjà au moins une pièce jointe dans un post, il peut envoyer des requêtes pour :
      • Validation du lancement d'iFrame
      • Opérations de lecture, de mise à jour et de suppression des pièces jointes
      • Mises à jour des notes sur ce post
    • Lorsque l'iFrame de découverte des pièces jointes est ouvert pour la première fois, il est possible que le module complémentaire n'ait pas encore de pièce jointe dans le post. Un paramètre de requête addOnToken est fourni. Il peut être utilisé pour envoyer des requêtes pour les éléments suivants :
      • Créer une pièce jointe sous le post (addOnToken est obligatoire)
      • Validation du lancement (addOnToken est validé s'il est fourni et est requis lorsque le module complémentaire ne comporte pas de pièce jointe existante dans le post)

Validation OAuth

Un module complémentaire Classroom utilise les API Google pour accéder aux données des utilisateurs Google.

Pour en savoir plus sur la procédure de validation, consultez les questions fréquentes sur la validation OAuth des API.

Fiche Google Workspace Marketplace

Pour obtenir des informations générales sur la configuration du SDK Google Workspace Marketplace, consultez Activer et configurer le SDK Google Workspace Marketplace et Créer une fiche Google Workspace Marketplace.

Points à prendre en compte concernant les fiches

La fiche du SDK Marketplace Store de votre projet Google Cloud public spécifie le nom et les descriptions de votre application destinées aux utilisateurs finaux. Vous pouvez fournir ces informations dans plusieurs langues sous Détails de l'application.

Suivez ces consignes dans vos fiches :

  • Sous Informations sur l'application :
    • Évitez la ponctuation dans le nom de l'application. Par exemple, utilisez Mon module complémentaire par Mon entreprise au lieu de "Mon entreprise : Mon module complémentaire" ou "Mon module complémentaire, par Mon entreprise".
    • Les champs Description courte et Description détaillée ne doivent pas contenir exactement le même texte.
    • Assurez-vous d'avoir sélectionné une valeur pour le champ Prix. Ce champ inclut les options de tarification Sans frais, Payante avec un essai sans frais, Payante avec des fonctionnalités sans frais et Payante. Vous n'avez pas besoin de spécifier le montant du coût dans la fiche Marketplace.
    • Assurez-vous d'avoir sélectionné une valeur pour le champ Catégorie. Les ressources pédagogiques ou les outils pour les enseignants et les administrateurs peuvent être de bons choix pour un module complémentaire Classroom.
    • Pour en savoir plus, consultez les éléments listés dans la description des détails de l'application sur Marketplace.

S'intégrer aux services de licence et de facturation de Google

Si vous souhaitez que vos applications Google Workspace Marketplace s'intègrent aux services de facturation et de gestion des licences de Google, consultez l' API Marketplace.

Paramètres d'installation

Les modules complémentaires peuvent autoriser l'installation individuelle en plus de l'installation par l'administrateur. Cette page met en évidence certaines différences entre les deux types d'installation. Elle n'a pas vocation à promouvoir l'un ou l'autre. Vous pouvez choisir d'autoriser ou non l'installation individuelle sur la page Configuration de l'application du SDK Google Workspace Marketplace.

Installation par l'administrateur

Les installations par un administrateur permettent à un administrateur d'ajouter un module complémentaire à tous les comptes d'un domaine ou à des groupes d'accès ou unités organisationnelles spécifiques. Seul un administrateur de domaine peut effectuer une installation administrateur. L'administrateur peut éventuellement autoriser tous les niveaux d'accès au nom de tous les utilisateurs du domaine. Dans ce cas, les utilisateurs ne sont pas invités à autoriser les niveaux d'accès.

Voici quelques points à prendre en compte concernant l'installation par un administrateur.

  • Contrôle plus strict. Les administrateurs peuvent limiter l'accès à un module complémentaire à certains utilisateurs.
  • Compatibilité avec les licences : Si votre application nécessite une licence, le fait de canaliser les installations par l'intermédiaire d'un administrateur peut vous aider à vous assurer que les licences sont distribuées et utilisées de manière appropriée avec l'établissement concerné.
  • Moins de contraintes pour les utilisateurs finaux : Une installation par un administrateur réduit la charge de configuration pour les enseignants et les élèves. Cela peut se traduire par une expérience utilisateur plus fluide, avec moins de clics et moins de risques de confusion.

Consultez Installer des applications Marketplace dans votre domaine pour en savoir plus sur les installations par l'administrateur et Fonctionnement de la structure organisationnelle pour en savoir plus sur les unités organisationnelles et les groupes d'accès.

Installation individuelle

Les installations individuelles ajoutent un module complémentaire au compte de l'utilisateur. L'utilisateur est invité à autoriser les niveaux d'accès du module complémentaire lors de l'installation.

Voici quelques points à prendre en compte concernant l'installation individuelle.

  • Facilitez l'adoption. Un plus grand nombre d'utilisateurs peuvent voir et installer votre module complémentaire depuis Google Workspace Marketplace. Autoriser l'installation individuelle peut inciter davantage d'enseignants à adopter votre produit ou à le recommander.
  • Tests administrateur Un administrateur peut installer individuellement un module complémentaire pour le tester ou l'évaluer avant de l'approuver ou de l'installer pour un groupe plus large.

En plus d'installer des modules complémentaires pour les utilisateurs, les administrateurs peuvent également tenir à jour une liste d'autorisation pour permettre aux utilisateurs d'installer des modules complémentaires qui autorisent l'installation individuelle. Si un module complémentaire ne figure pas dans la liste d'autorisation, les utilisateurs peuvent toujours voir sa fiche dans Google Workspace Marketplace, mais ne peuvent pas l'installer. Ils voient alors un message expliquant qu'un administrateur de domaine n'a pas autorisé l'installation du module complémentaire. Pour en savoir plus sur ce comportement, consultez Gérer les applications Google Workspace Marketplace figurant sur votre liste d'autorisation.

Pour en savoir plus, consultez la documentation sur les paramètres d'installation de Google Workspace Marketplace.

Intégration d'une application

Vous devez fournir une URL d'iframe de lancement dans le champ URI de configuration de la pièce jointe. Cette URL est utilisée comme valeur src de l'iframe pour l'iframe de découverte des pièces jointes. L'iFrame de découverte des pièces jointes permet aux enseignants de trouver des contenus ou des activités à joindre à leurs devoirs. Vous pouvez le définir dans la console du projet Google Cloud.

Configuration de l'URI iFrame

Les préfixes d'URI pour autoriser les pièces jointes sont utilisés pour valider les URI définis dans un AddOnAttachment à l'aide des méthodes *.addOnAttachments.create et *.addOnAttachments.patch. La validation est une correspondance littérale du préfixe de chaîne et n'autorise pas l'utilisation de caractères génériques.

Vous devez également spécifier tous les préfixes d'URI à partir desquels les pièces jointes sont autorisées dans votre module complémentaire. Cette fonctionnalité renforce la sécurité en empêchant les pièces jointes provenant de sources non autorisées.

Définissez ces deux valeurs sur la page Configuration de l'application du SDK Marketplace de votre projet Google Cloud.

Comptes de test

Créez des comptes de test sur votre domaine de démonstration pour vérifier le bon fonctionnement de votre module complémentaire privé. Deux comptes élèves sont nécessaires pour tester le changement d'élève dans l'iFrame "Examen des devoirs des élèves".

Comptes de test suggérés :

  • Caroline Dupuis, tammy.teacher@<votre domaine de démonstration>
  • Sam Student, sam.student@<votre domaine de démonstration>
  • Sally Student, sally.student@<votre domaine de démonstration>

Pour créer un compte de test :

  1. Connectez-vous à la console d'administration.
  2. Accédez à Utilisateurs.
  3. Cliquez sur Ajouter un utilisateur (voir figure 1).
  4. Saisissez les informations sur l'utilisateur et attribuez-lui les rôles appropriés.

Cliquez sur &quot;Ajouter un utilisateur&quot;. Figure 1. Emplacement du lien Ajouter un utilisateur dans la console d'administration.

Pour créer un groupe de test :

  1. Connectez-vous à la console d'administration.
  2. Accédez à Groupes.
  3. Cliquez sur Créer un groupe (voir la figure 2).
  4. Saisissez les membres et les propriétaires du groupe.

Cliquez sur &quot;Créer un groupe&quot;. Figure 2 : Emplacement du lien Créer un groupe dans la console d'administration.