Tester et déboguer les modules complémentaires Google Workspace HTTP

En tant que développeur de modules complémentaires Google Workspace, vous devez peut-être déboguer du code pour tester des modifications ou résoudre des problèmes complexes. Vous pouvez déboguer les modules complémentaires Google Workspace de différentes manières, en fonction de l'architecture de votre application, de ses fonctionnalités, de son déploiement et de vos préférences.

Cette page explique comment déboguer un module complémentaire HTTP Google Workspace à l'aide de ngrok, une plate-forme d'entrée unifiée que vous pouvez utiliser pour tester les environnements de développement locaux. Dans ce guide, vous allez tester des modifications de code dans un environnement local et résoudre des problèmes dans un environnement distant.

Déboguer à partir d'un environnement de développement local

Dans cette section, vous interagissez avec votre module complémentaire Google Workspace qui s'exécute dans votre environnement local.

Figure 1. Déboguez dans un environnement de développement local.

Prérequis

Node.js

• Les dernières versions de node et npm installées dans votre environnement local.

• La dernière version de nodemon installée dans votre environnement local. Il est utilisé pour la recharge automatique :

  npm install -g nodemon

• Un projet Google Cloud. Vous pouvez suivre les sections Conditions préalables et Configurer l'environnement du guide de démarrage rapide.

• Code du module complémentaire Google Workspace à déboguer dans votre environnement local. Dans ce guide, nous utilisons les fonctionnalités de lien d'aperçu de l'exemple de code 3p-resources du dépôt GitHub googleworkspace/add-ons-samples à des fins d'illustration.

• Un IDE configuré dans votre environnement local et capable de déboguer. Dans ce guide, nous utilisons l'IDE Visual Studio Code et ses fonctionnalités de débogage par défaut à des fins d'illustration.

• Un compte ngrok.

• La dernière version de gcloud doit être installée et initialisée dans votre environnement local.

Python

• La dernière version de python3 installée dans votre environnement local.
• La dernière version de pip et virtualenv doit être installée dans votre environnement local. Ils sont utilisés pour gérer respectivement les packages Python et les environnements virtuels.
• Un projet Google Cloud. Vous pouvez suivre les sections Conditions requises et Configurer l'environnement du guide de démarrage rapide.
• Code du module complémentaire Google Workspace à déboguer dans votre environnement local. Dans ce guide, nous utilisons les fonctionnalités de lien d'aperçu de l'exemple de code 3p-resources du dépôt GitHub googleworkspace/add-ons-samples à des fins d'illustration.
• Un IDE configuré dans votre environnement local et capable de déboguer. Dans ce guide, nous utilisons l'IDE Visual Studio Code et ses fonctionnalités de débogage par défaut à des fins d'illustration.
• Un compte ngrok.
• La dernière version de gcloud doit être installée et initialisée dans votre environnement local.

Java

• Dernière version stable de Java SE 11's JDK installée dans votre environnement local.
• La dernière version de Apache Maven installée dans votre environnement local. Il sert à gérer les projets Java.
• Un projet Google Cloud. Vous pouvez suivre les sections Conditions requises et Configurer l'environnement du guide de démarrage rapide.
• Code du module complémentaire Google Workspace à déboguer dans votre environnement local. Dans ce guide, nous utilisons les fonctionnalités de lien d'aperçu de l'exemple de code 3p-resources du dépôt GitHub googleworkspace/add-ons-samples à des fins d'illustration.
• Un IDE configuré dans votre environnement local et capable de déboguer. Dans ce guide, nous utilisons l'IDE Visual Studio Code et ses fonctionnalités de débogage par défaut à des fins d'illustration.
• Un compte ngrok.
• La dernière version de gcloud doit être installée et initialisée dans votre environnement local.

Rendre le service localhost accessible publiquement

Vous devez connecter votre environnement local à Internet pour que le module complémentaire Google Workspace puisse y accéder. L'application ngrok permet de rediriger les requêtes HTTP effectuées vers une URL publique vers votre environnement local.

1. Dans un navigateur de votre environnement local, connectez-vous à votre compte ngrok.
2. Installez l'application et configurez votre authtoken dans votre environnement local.
3. Créez un domaine statique dans votre compte ngrok. Il est référencé sous le nom NGROK_STATIC_DOMAIN dans les instructions de ce guide.

Créer et installer le déploiement du module complémentaire

1. Configurez le module complémentaire Google Workspace pour qu'il envoie toutes ses requêtes HTTP à votre domaine statique. Votre fichier de déploiement doit se présenter comme suit :

   {
     "oauthScopes": [
       "https://www.googleapis.com/auth/workspace.linkpreview",
       "https://www.googleapis.com/auth/workspace.linkcreate"
     ],
     "addOns": {
       "common": {
         "name": "Manage support cases",
         "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png",
         "layoutProperties": {
           "primaryColor": "#dd4b39"
         }
       },
       "docs": {
         "linkPreviewTriggers": [
           {
             "runFunction": "NGROK_STATIC_DOMAIN",
             "patterns": [
               {
                 "hostPattern": "example.com",
                 "pathPrefix": "support/cases"
               },
               {
                 "hostPattern": "*.example.com",
                 "pathPrefix": "cases"
               },
               {
                 "hostPattern": "cases.example.com"
               }
             ],
             "labelText": "Support case",
             "localizedLabelText": {
               "es": "Caso de soporte"
             },
             "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
           }
         ],
         "createActionTriggers": [
           {
             "id": "createCase",
             "labelText": "Create support case",
             "localizedLabelText": {
               "es": "Crear caso de soporte"
             },
             "runFunction": "$URL2",
             "logoUrl": "https://developers.google.com/workspace/add-ons/images/support-icon.png"
           }
         ]
       },
       "httpOptions": {
         "granularOauthPermissionSupport": "OPT_IN"
       }
     }
   }
   

   Remplacez NGROK_STATIC_DOMAIN par le domaine statique de votre compte ngrok.

2. Définissez le projet Google Cloud à utiliser :

   gcloud config set project PROJECT_ID

3. Procurez-vous de nouveaux identifiants utilisateur à utiliser comme identifiants par défaut de l'application :

   gcloud auth application-default login

   Remplacez PROJECT_ID par l'ID de projet du projet Google Cloud de l'application.

4. Créez le déploiement :

   gcloud workspace-add-ons deployments create manageSupportCases \
       --deployment-file=DEPLOYMENT_FILE_PATH

   Remplacez DEPLOYMENT_FILE_PATH par le chemin d'accès à votre fichier de déploiement.

5. Installez le déploiement :

   gcloud workspace-add-ons deployments install manageSupportCases

   

   Figure 2. Le module complémentaire Google Workspace envoie toutes ses requêtes HTTP au domaine statique. Le service public `ngrok` sert de pont entre le module complémentaire Google Workspace et le code d'application qui s'exécute localement.

Tester le module complémentaire Google Workspace

Vous pouvez déployer, tester et déboguer votre module complémentaire Google Workspace localement, et le recharger automatiquement.

Remarque : L'exécution du module complémentaire Google Workspace s'effectue avec le framework Cloud Run Functions dans les exemples.

Node.js

1. Dans l'IDE Visual Studio Code installé dans votre environnement local, procédez comme suit :

   1. Dans une nouvelle fenêtre, ouvrez le dossier add-ons-samples/node/3p-resources.

   2. Configurez l'application pour l'exécution locale et le débogage avec rechargement automatique en ajoutant une dépendance et deux scripts dans le fichier package.json :

      {
          ...
          "dependencies": {
            ...
            "@google-cloud/functions-framework": "^3.3.0"
          },
          "scripts": {
              ...
              "start": "npx functions-framework --target=createLinkPreview --port=9000",
              "debug-watch": "nodemon --watch ./ --exec npm start"
          }
          ...
      }
      

   3. À partir du répertoire racine, installez l'application :

      npm install

   4. Créez et configurez un lancement nommé Debug Watch qui déclenche le script debug-watch en créant le fichier .vscode/launch.json dans le répertoire racine :

      {
          "version": "0.2.0",
          "configurations": [{
              "type": "node",
              "request": "launch",
              "name": "Debug Watch",
              "cwd": "${workspaceRoot}",
              "runtimeExecutable": "npm",
              "runtimeArgs": ["run-script", "debug-watch"]
          }]
      }
      

   5. Ajoutez un point d'arrêt qui met en pause le traitement des requêtes HTTP dans le fichier index.js, puis lancez l'exécution et le débogage avec la configuration Debug Watch ajoutée précédemment. L'application est maintenant en cours d'exécution et écoute les requêtes HTTP sur le port 9000.

      

      Figure 3. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port 9000.

2. Lancez l'application ngrok dans votre environnement local :

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   Remplacez NGROK_STATIC_DOMAIN par le domaine statique de votre compte ngrok. Toutes les requêtes sont désormais redirigées vers votre environnement local et le port utilisé par l'application.

   

   Figure 4. Terminal avec le serveur ngrok en cours d'exécution et de redirection.

3. Une interface Web est également démarrée sur votre hôte local par l'application ngrok. Vous pouvez surveiller toutes les activités en ouvrant le journal dans un navigateur.

   

   Figure 5. L'interface Web hébergée par l'application ngrok n'affiche aucune requête HTTP.

4. Testez votre module complémentaire Google Workspace en prévisualisant l'URL d'une demande dans un nouveau document Google Docs avec un compte de test :

   • Créez un document Google Docs.

     Créer un document Google Docs

   • Saisissez le lien suivant et appuyez sur enter :

     https://example.com/support/case/?name=Name1&description=Description1&priority=P1
     

   • Cliquez sur le lien.

5. Dans le Visual Studio Code de votre environnement local, vous pouvez voir que l'exécution est suspendue au niveau du point d'arrêt défini.

   

   Figure 6. L'exécution est suspendue au niveau du point d'arrêt défini.

6. Lorsque vous reprenez l'exécution à partir du débogueur Visual Studio Code avant l'expiration des modules complémentaires Google Workspace, le module complémentaire Google Workspace affiche l'aperçu du lien dans le document Google à partir du cache.

7. Vous pouvez consulter les journaux des requêtes et réponses HTTP à partir de l'interface Web hébergée par l'application ngrok dans votre environnement local.

   

   Figure 7. Requête HTTP depuis l'interface Web hébergée par l'application ngrok.

8. Pour modifier le comportement de l'application, remplacez Case par Case: sur la ligne 51 de index.js. Lorsque vous enregistrez le fichier, nodemon recharge automatiquement l'application avec le code source mis à jour et Visual Studio Code reste en mode débogage.

   

   Figure 8. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port 9000 avec la modification du code chargée.

9. Cette fois, au lieu de cliquer sur le lien et d'attendre quelques secondes dans un nouveau document Google Docs, vous pouvez sélectionner la dernière requête HTTP enregistrée dans l'interface Web hébergée par l'application ngrok dans votre environnement local, puis cliquer sur Replay. Comme la dernière fois, votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage.

10. Lorsque vous reprenez l'exécution à partir du débogueur Visual Studio Code, vous pouvez voir dans l'interface Web hébergée par l'application ngrok dans votre environnement local que l'application génère une réponse avec la version mise à jour de la carte d'aperçu.

Python

1. Dans l'IDE Visual Studio Code installé dans votre environnement local, procédez comme suit :

   1. Dans une nouvelle fenêtre, ouvrez le dossier add-ons-samples/python/3p-resources/create_link_preview.

   2. Créez un environnement virtuel pour Python env et activez-le :

      virtualenv env
      source env/bin/activate

   3. Installez toutes les dépendances du projet à l'aide de pip dans l'environnement virtuel :

      pip install -r requirements.txt

   4. Créez le fichier .vscode/launch.json dans le répertoire racine et configurez un lancement nommé Debug Watch qui déclenche l'application à partir du module functions-framework sur le port 9000 en mode débogage sur l'environnement virtuel env :

      {
          "version": "0.2.0",
          "configurations": [{
              "type": "python",
              "request": "launch",
              "name": "Debug Watch",
              "python": "${workspaceFolder}/env/bin/python3",
              "module": "functions_framework",
              "args": [
                  "--target", "create_link_preview",
                  "--port", "9000",
                  "--debug"
              ]
          }]
      }
      

   5. Ajoutez un point d'arrêt qui met en pause le traitement des requêtes HTTP dans le fichier main.py, puis lancez l'exécution et le débogage avec la configuration Debug Watch ajoutée précédemment. L'application est maintenant en cours d'exécution et écoute les requêtes HTTP sur le port 9000.

      

      Figure 3. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port 9000.

2. Lancez l'application ngrok dans votre environnement local :

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   Remplacez NGROK_STATIC_DOMAIN par le domaine statique de votre compte ngrok. Toutes les requêtes sont désormais redirigées vers votre environnement local et le port utilisé par l'application.

   

   Figure 4. Terminal avec le serveur ngrok en cours d'exécution et de redirection.

3. Une interface Web est également démarrée sur votre hôte local par l'application ngrok. Surveillez toutes les activités en ouvrant le journal dans un navigateur.

   

   Figure 5. L'interface Web hébergée par l'application ngrok n'affiche aucune requête HTTP.

4. Testez votre module complémentaire Google Workspace en prévisualisant l'URL d'une demande dans un nouveau document Google Docs avec un compte de test :

   • Créez un document Google Docs.

     Créer un document Google Docs

   • Saisissez le lien suivant et appuyez sur enter :

     https://example.com/support/case/?name=Name1&description=Description1&priority=P1
     

   • Cliquez sur le lien.

5. Dans le Visual Studio Code de votre environnement local, vous pouvez voir que l'exécution est suspendue au niveau du point d'arrêt défini.

   

   Figure 6. L'exécution est suspendue au niveau du point d'arrêt défini.

6. Lorsque vous reprenez l'exécution à partir du débogueur Visual Studio Code avant l'expiration des modules complémentaires Google Workspace, le module complémentaire Google Workspace affiche l'aperçu du lien dans le document Google à partir du cache.

7. Vous pouvez consulter les journaux des requêtes et réponses HTTP à partir de l'interface Web hébergée par l'application ngrok dans votre environnement local.

   

   Figure 7. Requête HTTP depuis l'interface Web hébergée par l'application ngrok.

8. Pour modifier le comportement de l'application, remplacez Case par Case: sur la ligne 56 du fichier main.py. Lorsque vous enregistrez le fichier, Visual Studio Code recharge automatiquement l'application avec le code source mis à jour et reste en mode débogage.

   

   Figure 8. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port 9000 avec la modification du code chargée.

9. Cette fois, au lieu de cliquer sur le lien et d'attendre quelques secondes dans un nouveau document Google Docs, vous pouvez sélectionner la dernière requête HTTP enregistrée dans l'interface Web hébergée par l'application ngrok dans votre environnement local, puis cliquer sur Replay. Comme la dernière fois, votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage.

10. Lorsque vous reprenez l'exécution à partir du débogueur Visual Studio Code, vous pouvez voir dans l'interface Web hébergée par l'application ngrok dans votre environnement local que l'application génère une réponse avec la version mise à jour de la carte d'aperçu.

Java

1. Dans l'IDE Visual Studio Code installé dans votre environnement local, procédez comme suit :

   1. Dans une nouvelle fenêtre, ouvrez le dossier add-ons-samples/java/3p-resources.

   2. Configurez le projet Maven pour exécuter l'application CreateLinkPreview sur le port 9000 en local en ajoutant le plug-in de compilation Cloud Functions Framework function-maven-plugin au fichier pom.xml :

      ...
      <plugin>
          <groupId>com.google.cloud.functions</groupId>
          <artifactId>function-maven-plugin</artifactId>
          <version>0.11.0</version>
          <configuration>
              <functionTarget>CreateLinkPreview</functionTarget>
              <port>9000</port>
          </configuration>
      </plugin>
      ...
      

   3. Vous pouvez maintenant le lancer localement en mode débogage :

      mvnDebug function:run
      Preparing to execute Maven in debug mode
      Listening for transport dt_socket at address: 8000

   4. Créez le fichier .vscode/launch.json dans le répertoire racine et configurez un lancement nommé Remote Debug Watch qui s'attache à l'application précédemment lancée sur le port 8000 :

      {
          "version": "0.2.0",
          "configurations": [{
              "type": "java",
              "request": "attach",
              "name": "Remote Debug Watch",
              "projectName": "http-function",
              "hostName": "localhost",
              "port": 8000
          }]
      }
      

   5. Ajoutez un point d'arrêt qui met en pause le traitement des requêtes HTTP dans le fichier CreateLinkPreview.java, puis commencez à associer et à déboguer avec la configuration Remote Debug Watch ajoutée précédemment. L'application est maintenant en cours d'exécution et écoute les requêtes HTTP sur le port 9000.

      

      Figure 3. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port 9000.

2. Lancez l'application ngrok dans votre environnement local :

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   Remplacez NGROK_STATIC_DOMAIN par le domaine statique de votre compte ngrok. Toutes les requêtes sont désormais redirigées vers votre environnement local et le port utilisé par l'application.

   

   Figure 4. Terminal avec le serveur ngrok en cours d'exécution et de redirection.

3. Une interface Web est également démarrée sur votre hôte local par l'application ngrok. Surveillez toutes les activités en ouvrant le journal dans un navigateur.

   

   Figure 5. L'interface Web hébergée par l'application ngrok n'affiche aucune requête HTTP.

4. Testez votre module complémentaire Google Workspace en prévisualisant l'URL d'une demande dans un nouveau document Google Docs avec un compte de test :

   • Créez un document Google Docs.

     Créer un document Google Docs

   • Saisissez le lien suivant et appuyez sur enter :

     https://example.com/support/case/?name=Name1&description=Description1&priority=P1
     

   • Cliquez sur le lien.

5. Dans le Visual Studio Code de votre environnement local, vous pouvez voir que l'exécution est suspendue au niveau du point d'arrêt défini.

   

   Figure 6. L'exécution est suspendue au niveau du point d'arrêt défini.

6. Lorsque vous reprenez l'exécution à partir du débogueur Visual Studio Code avant l'expiration des modules complémentaires Google Workspace, le module complémentaire Google Workspace affiche l'aperçu du lien dans le document Google à partir du cache.

7. Vous pouvez consulter les journaux des requêtes et réponses HTTP à partir de l'interface Web hébergée par l'application ngrok dans votre environnement local.

   

   Figure 7. Requête HTTP depuis l'interface Web hébergée par l'application ngrok.

8. Pour modifier le comportement de l'application, remplacez Case par Case: sur la ligne 78 du fichier CreateLinkPreview.java, redémarrez le processus mvnDebug, puis relancez Remote Debug Watch pour rattacher et redémarrer le débogage.

9. Cette fois, au lieu de cliquer sur le lien et d'attendre quelques secondes dans un nouveau document Google Docs, vous pouvez sélectionner la dernière requête HTTP enregistrée dans l'interface Web hébergée par l'application ngrok dans votre environnement local, puis cliquer sur Replay. Comme la dernière fois, votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage.

10. Lorsque vous reprenez l'exécution à partir du débogueur Visual Studio Code, vous pouvez voir dans l'interface Web hébergée par l'application ngrok dans votre environnement local que l'application génère une réponse avec la version mise à jour de la carte d'aperçu.

Déboguer à partir d'un environnement distant

Dans cette section, vous allez interagir avec votre module complémentaire Google Workspace qui s'exécute dans un environnement distant.

Figure 9. Déboguez à partir de l'environnement distant.

Prérequis

• Votre module complémentaire Google Workspace est déployé et installé.
• Votre application s'exécute dans votre environnement à distance avec le débogueur activé sur un port donné, et elle est référencée sous le nom REMOTE_DEBUG_PORT dans les instructions de ce guide.
• Votre environnement local peut ssh vers votre environnement distant.
• Un IDE est configuré dans votre environnement local et peut effectuer le débogage. Dans ce guide, nous utilisons l'Visual Studio Code IDE et ses fonctionnalités de débogage par défaut à des fins d'illustration.

Connecter vos environnements local et distant

Dans votre environnement local à partir duquel vous souhaitez lancer une connexion client de débogage, configurez un tunnel SSH :

ssh -L LOCAL_DEBUG_PORT:localhost:REMOTE_DEBUG_PORT REMOTE_USERNAME@REMOTE_ADDRESS

Remplacez les éléments suivants :

• LOCAL_DEBUG_PORT : port de débogage dans votre environnement local.
• REMOTE_USERNAME : nom d'utilisateur dans votre environnement distant.
• REMOTE_ADDRESS : adresse de votre environnement distant.
• REMOTE_DEBUG_PORT : port de débogage dans votre environnement distant.

Le port de débogage de votre environnement local est désormais associé à celui de votre environnement distant.

Démarrer le débogage

Dans l'IDE Visual Studio Code installé dans votre environnement local, procédez comme suit :

1. Dans une nouvelle fenêtre, ouvrez le code source de votre application.

2. Créez le fichier .vscode/launch.json dans le répertoire racine et configurez un lancement nommé Debug Remote qui s'attache au port de débogage dans votre environnement local :

   Node.js

   {
       "version": "0.2.0",
       "configurations": [{
           "type": "node",
           "request": "attach",
           "name": "Debug Remote",
           "address": "127.0.0.1",
           "port": LOCAL_DEBUG_PORT
       }]
   }
   

   Python

   {
       "version": "0.2.0",
       "configurations": [{
           "type": "python",
           "request": "attach",
           "name": "Debug Remote",
           "connect": {
               "host": "127.0.0.1",
               "port": LOCAL_DEBUG_PORT
           }
       }]
   }
   

   Java

   {
       "version": "0.2.0",
       "configurations": [{
           "type": "java",
           "request": "attach",
           "name": "Debug Remote",
           "hostName": "127.0.0.1",
           "port": LOCAL_DEBUG_PORT
       }]
   }
   

   Remplacez LOCAL_DEBUG_PORT par le port de débogage dans votre environnement local.

3. Ajoutez un point d'arrêt dans le code source de votre application qui met en pause le traitement des requêtes HTTP, puis lancez l'exécution et le débogage avec la configuration Debug Remote ajoutée précédemment.

   Interagissez avec le module complémentaire Google Workspace installé. Votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage dans l'IDE Visual Studio Code.

Articles associés

• Découvrez comment interroger les journaux d'erreurs.