Créer un module complémentaire Google Workspace avec Node.js

Créez des modules complémentaires Google Workspace dans des fonctions Cloud Run à l'aide de l'environnement d'exécution Node.js.

Objectifs

configurer votre environnement ;
créer et déployer une fonction Cloud Run ;
créer et déployer le module complémentaire ;
installer le module complémentaire.

Prérequis

Un projet Google Cloud.
Activez la facturation pour votre projet Cloud. Découvrez comment vérifier l'état de facturation de vos projets.
Le SDK Cloud est configuré avec le projet Cloud.

Configurer votre environnement

Ouvrir votre projet Cloud dans la console Google Cloud

Dans la console Google Cloud, accédez à la page Sélectionner un projet.
Sélectionner un projet Cloud
Sélectionnez le projet Google Cloud que vous souhaitez utiliser. Vous pouvez également cliquer sur Créer un projet et suivre les instructions à l'écran. Si vous créez un projet Google Cloud, vous devrez peut-être activer la facturation pour ce projet.

Configurer l'écran d'autorisation OAuth

Les modules complémentaires Google Workspace nécessitent une configuration de l'écran d'autorisation. La configuration de l'écran d'autorisation OAuth de votre module complémentaire définit ce que Google affiche aux utilisateurs.

Dans la console Google API, accédez à Menu > Google Auth Platform > Branding.
Accéder à la page "Branding"
Si vous avez déjà configuré Google Auth Platform, vous pouvez configurer les paramètres de l'écran d'autorisation OAuth suivants dans Branding, Audience et Accès aux données. Si le message Google Auth Platform pas encore configuré s'affiche, cliquez sur Premiers pas :

Sous Informations sur l'application, dans Nom de l'application, saisissez un nom pour l'application.
Dans Adresse e-mail d'assistance utilisateur, choisissez une adresse e-mail d'assistance à laquelle les utilisateurs peuvent vous contacter s'ils ont des questions sur leur consentement.
Cliquez sur Suivant.
Sous Audience, sélectionnez Interne.
Cliquez sur Suivant.
Sous Coordonnées, saisissez une adresse e-mail à laquelle vous recevrez des notifications en cas de modification de votre projet.
Cliquez sur Suivant.
Sous Terminer, consultez le règlement concernant les données utilisateur des services API Google. Si vous l'acceptez, sélectionnez J'accepte le règlement concernant les données utilisateur des services API Google.
Cliquez sur Continuer.
Cliquez sur Créer.

Pour l'instant, vous pouvez ignorer l'ajout de niveaux d'accès. À l'avenir, lorsque vous créerez une application à utiliser en dehors de votre organisation Google Workspace, vous devrez définir le type d'utilisateur sur Externe. Ajoutez ensuite les niveaux d'autorisation dont votre application a besoin. Pour en savoir plus, consultez le guide complet Configurer l'écran de consentement OAuth guide.

Créer et déployer une fonction Cloud Run

Cliquez sur Autoriser pour provisionner Cloud Shell et vous y connecter.

Dans le terminal Cloud Shell, activez l'API Cloud Run Functions, l'API Cloud Build, l'API Google Workspace Add-ons, l'API Compute Engine et l'API Cloud Run :

gcloud services enable cloudfunctions.googleapis.com  \
                    cloudbuild.googleapis.com  \
                    gsuiteaddons.googleapis.com  \
                    compute.googleapis.com  \
                    run.googleapis.com

Lancez l'éditeur Cloud Shell en cliquant sur Ouvrir l'éditeur dans la barre d'outils de la fenêtre Cloud Shell.

Cet éditeur de code intégré offre la commodité de visualiser et de modifier des fichiers dans le même environnement où les projets sont créés et déployés.

Dans le répertoire vide, créez le fichier function.js avec l'exemple de code suivant :

/**
 * Cloud Run function that loads the homepage for a
 * Google Workspace add-on.
 *
 * @param {Object} req Request sent from Google
 * @param {Object} res Response to send back
 */
exports.loadHomePage = function addonsHomePage (req, res) {
  res.send(createAction());
};

/** Creates a card with two widgets. */
function createAction() {
  return {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "header": {
              "title": "Cats!"
            },
            "sections": [
              {
                "widgets": [
                  {
                    "textParagraph": {
                      "text": "Your random cat:"
                    }
                  },
                  {
                    "image": {
                      "imageUrl": "https://cataas.com/cat"
                     }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  };
}

Dans le même répertoire, créez le fichier package.json avec l'exemple de code suivant :

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

Revenez au terminal Cloud Shell en cliquant sur Ouvrir le terminal.

Ajoutez le rôle Cloud Build Service Account (roles/cloudbuild.builds.builder) au compte de service Compute Engine par défaut.

Commencez par configurer l'autorisation du compte de service :

export PROJECT_ID=$(gcloud config get project)
export SERVICE_ACCOUNT_NAME=$(gcloud compute project-info describe \
  --format="value(defaultServiceAccount)")

Ensuite, accordez l'autorisation manquante au compte de service :

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:$SERVICE_ACCOUNT_NAME" \
  --role="roles/cloudbuild.builds.builder"

Exécutez la commande suivante pour déployer la fonction :
```
gcloud run deploy loadHomePage --runtime nodejs22 --trigger-http
```
Lorsque vous y êtes invité, spécifiez que vous n'autorisez pas les appels non authentifiés de la fonction. Le déploiement de la fonction peut prendre quelques minutes.

Créer un déploiement de module complémentaire

Recherchez l'adresse e-mail du compte de service pour le module complémentaire :
```
gcloud workspace-add-ons get-authorization
```

Accordez le compte de service le cloudfunctions.invoker rôle. Remplacez SERVICE_ACCOUNT_EMAIL par le serviceAccountEmail champ de l'étape précédente.

gcloud run services add-iam-policy-binding loadHomePage \
    --role roles/roles/run.invoker \
    --member serviceAccount:SERVICE_ACCOUNT_EMAIL

Obtenez l'URL de la fonction déployée. Pour obtenir l'URL, exécutez la commande suivante et recherchez le champ url dans la section httpsTrigger :
```
gcloud run services describe loadHomePage
```
Revenez à l'éditeur Cloud Shell en cliquant sur Ouvrir l'éditeur.

Dans le même répertoire que package.json, créez le fichier deployment.json avec l'exemple de code suivant. Remplacez URL par l'url de la fonction déployée à l'étape précédente.

{
  "oauthScopes": ["https://www.googleapis.com/auth/gmail.addons.execute"],
  "addOns": {
    "common": {
      "name": "My HTTP Add-on",
      "logoUrl": "https://raw.githubusercontent.com/webdog/octicons-png/main/black/beaker.png",
      "homepageTrigger": {
        "runFunction": "URL"
      }
    },
    "gmail": {},
    "drive": {},
    "calendar": {},
    "docs": {},
    "sheets": {},
    "slides": {},
    "httpOptions": {
      "granularOauthPermissionSupport": "OPT_IN"
    }
  }
}

Revenez au terminal Cloud Shell pour créer le déploiement :

gcloud workspace-add-ons deployments create quickstart \
    --deployment-file=deployment.json

Installer le module complémentaire

Installez le déploiement en mode développement :

gcloud workspace-add-ons deployments install quickstart

Ouvrez ou actualisez Gmail pour afficher le module complémentaire. Dans la barre d'outils à droite, recherchez une icône en forme de bécher.
Cliquez sur l'icône pour ouvrir le module complémentaire. Si vous y êtes invité, autorisez le module complémentaire.

Facultatif : Effectuer un nettoyage

Pour éviter les frais, supprimez les ressources que vous avez créées :

Désinstallez le module complémentaire de votre compte Google :
```
gcloud workspace-add-ons deployments uninstall quickstart
```
Pour éviter les frais liés aux ressources utilisées dans ce guide de démarrage rapide, supprimez le projet Cloud :
```
gcloud projects delete PROJECT_ID
```
Remplacez PROJECT_ID par l'ID du projet Cloud que vous avez utilisé pour le guide de démarrage rapide. Vous trouverez l'ID du projet Cloud dans la console Google API sur la page du tableau de bord.

Pour ajouter d'autres fonctionnalités à votre module complémentaire Google Workspace, consultez les ressources suivantes :

Créer un module complémentaire Google Workspace avec Node.js Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.