En tant que développeur de modules complémentaires Google Workspace, vous devrez peut-être déboguer du code pour tester des modifications ou résoudre des problèmes complexes. Le débogage des modules complémentaires Google Workspace peut être effectué de différentes manières en fonction de l'architecture de votre application, de son fonctionnement, de son mode de déploiement et de vos préférences.
Cette page explique comment déboguer un module complémentaire Google Workspace à l'aide de ngrok, une plate-forme d'entrée unifiée que vous pouvez utiliser pour tester des environnements de développement locaux. Dans ce guide, vous allez tester les modifications de code dans un environnement local et résoudre les problèmes dans un environnement distant.
Déboguer à partir d'un environnement de développement local
Dans cette section, vous allez interagir avec le module complémentaire Google Workspace qui s'exécute dans votre environnement local.
Figure 1. Effectuez le débogage dans un environnement de développement local.
Prérequis
Node.js
- Les dernières versions de
node
etnpm
sont installées dans votre environnement local. Dernière version de
nodemon
installée dans votre environnement local. Elle est utilisée pour l'actualisation automatique:npm install -g nodemon
Un projet Google Cloud. Vous pouvez suivre les sections Prérequis et Configurer l'environnement du guide de démarrage rapide.
Le code du module complémentaire Google Workspace à déboguer dans votre environnement local. Nous utilisons les fonctionnalités du lien d'aperçu de l'exemple de code
3p-resources
du dépôt GitHubgoogleworkspace/add-ons-samples
de ce guide à titre d'illustration.IDE configuré dans votre environnement local et capable de procéder au débogage Nous utilisons l'IDE
Visual Studio Code
et ses fonctionnalités de débogage par défaut dans ce guide à des fins d'illustration.Un compte
ngrok
La dernière version de
gcloud
est installée et initialisée dans votre environnement local.
Python
- Dernière version de
python3
installée dans votre environnement local. - Les dernières versions de
pip
etvirtualenv
installées dans votre environnement local permettent de gérer respectivement les packages Python et les environnements virtuels. - Un projet Google Cloud. Vous pouvez suivre les sections Prérequis et Configurer l'environnement du guide de démarrage rapide.
- Le code du module complémentaire Google Workspace à déboguer dans votre environnement local. Nous utilisons les fonctionnalités du lien d'aperçu de l'exemple de code
3p-resources
du dépôt GitHubgoogleworkspace/add-ons-samples
de ce guide à titre d'illustration. - IDE configuré dans votre environnement local et capable de procéder au débogage Nous utilisons l'IDE
Visual Studio Code
et ses fonctionnalités de débogage par défaut dans ce guide à des fins d'illustration. - Un compte
ngrok
- La dernière version de
gcloud
est installée et initialisée dans votre environnement local.
Java
- Dernière version stable d'
Java SE 11's JDK
installée dans votre environnement local. - La dernière version de
Apache Maven
installée dans votre environnement local permet de gérer les projets Java. - Un projet Google Cloud. Vous pouvez suivre les sections Prérequis et Configurer l'environnement du guide de démarrage rapide.
- Le code du module complémentaire Google Workspace à déboguer dans votre environnement local. Nous utilisons les fonctionnalités du lien d'aperçu de l'exemple de code
3p-resources
du dépôt GitHubgoogleworkspace/add-ons-samples
de ce guide à titre d'illustration. - IDE configuré dans votre environnement local et capable de procéder au débogage Nous utilisons l'IDE
Visual Studio Code
et ses fonctionnalités de débogage par défaut dans ce guide à des fins d'illustration. - Un compte
ngrok
- La dernière version de
gcloud
est installée et initialisée dans votre environnement local.
Rendre le service localhost disponible 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 adressées à une URL publique vers votre environnement local.
- Dans un navigateur de votre environnement local, connectez-vous à votre compte
ngrok
. - Installez l'application et configurez le
authtoken
dans votre environnement local. - Créez un domaine statique dans votre compte
ngrok
. Il est référencéNGROK_STATIC_DOMAIN
dans les instructions de ce guide.
Créer et installer le déploiement du module complémentaire
Configurez le module complémentaire Google Workspace pour qu'il envoie toutes ses requêtes HTTP à votre domaine statique. Le 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" } ] } } }
Remplacez
NGROK_STATIC_DOMAIN
par le domaine statique de votre comptengrok
.Définissez le projet Google Cloud à utiliser:
gcloud config set project PROJECT_ID
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 du projet Google Cloud de l'application.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 au fichier de déploiement.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 passerelle entre le module complémentaire Google Workspace et le code de l'application qui s'exécute localement.
Tester le module complémentaire Google Workspace
Vous pouvez déployer, tester, déboguer et recharger automatiquement votre module complémentaire Google Workspace localement.
Node.js
Depuis l'IDE
Visual Studio Code
installé dans votre environnement local, procédez comme suit:- Dans une nouvelle fenêtre, ouvrez le dossier
add-ons-samples/node/3p-resources
. Configurez l'application pour l'exécution locale et l'actualisation automatique du débogage 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" } ... }
Depuis le répertoire racine, installez l'application:
npm install
Créez et configurez un lancement nommé
Debug Watch
qui déclenche le scriptdebug-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"] }] }
Ajoutez un point d'arrêt qui suspend le traitement des requêtes HTTP dans le fichier
index.js
, puis commencez l'exécution et le débogage avec la configurationDebug Watch
ajoutée précédemment. L'application s'exécute maintenant et écoute les requêtes HTTP sur le port9000
.Figure 3. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port
9000
.
- Dans une nouvelle fenêtre, ouvrez le dossier
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 comptengrok
. Toutes les requêtes sont maintenant 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 redirigeant.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 l'ouvrant dans un navigateur.Figure 5 : Interface Web hébergée par l'application
ngrok
n'affichant aucune requête HTTP.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 testeur:
Créez un document Google Docs.
Saisissez le lien suivant, puis appuyez sur
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Cliquez sur le lien.
Dans le fichier
Visual Studio Code
de votre environnement local, vous pouvez constater 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.
Lorsque vous reprenez l'exécution à partir du débogueur de
Visual Studio Code
avant que les modules complémentaires Google Workspace n'expirent, le module complémentaire Google Workspace affiche l'aperçu du lien dans le document Google Docs à partir du cache.Vous pouvez consulter les journaux des requêtes et des réponses HTTP à partir de l'interface Web hébergée par l'application
ngrok
dans votre environnement local.Figure 7. Requête HTTP provenant de l'interface Web hébergée par l'application
ngrok
.Pour modifier le comportement de l'application, remplacez
Case
parCase:
51
intégré dans leindex.js
. Lorsque vous enregistrez le fichier,nodemon
recharge automatiquement l'application avec le code source mis à jour etVisual Studio Code
reste en mode débogage.Figure 8. L'application s'exécute et écoute les requêtes HTTP sur le port
9000
avec la modification du code chargée.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 sur l'interface Web hébergée par l'application
ngrok
dans votre environnement local, puis cliquer surReplay
. Comme la dernière fois, votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage.Lorsque vous reprenez l'exécution à partir du débogueur de
Visual Studio Code
, vous pouvez voir depuis l'interface Web hébergée par l'applicationngrok
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
Depuis l'IDE
Visual Studio Code
installé dans votre environnement local, procédez comme suit:- Dans une nouvelle fenêtre, ouvrez le dossier
add-ons-samples/python/3p-resources/create_link_preview
. Créez un environnement virtuel pour Python
env
et activez-le:virtualenv env
source env/bin/activate
Installez toutes les dépendances du projet à l'aide de
pip
dans l'environnement virtuel:pip install -r requirements.txt
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 modulefunctions-framework
sur le port9000
en mode débogage sur l'environnement virtuelenv
:{ "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" ] }] }
Ajoutez un point d'arrêt qui suspend le traitement des requêtes HTTP dans le fichier
main.py
, puis commencez l'exécution et le débogage avec la configurationDebug Watch
ajoutée précédemment. L'application s'exécute maintenant et écoute les requêtes HTTP sur le port9000
.Figure 3. L'application est en cours d'exécution et écoute les requêtes HTTP sur le port
9000
.
- Dans une nouvelle fenêtre, ouvrez le dossier
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 comptengrok
. Toutes les requêtes sont maintenant 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 redirigeant.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 l'ouvrant dans un navigateur.Figure 5 : Interface Web hébergée par l'application
ngrok
n'affichant aucune requête HTTP.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 testeur:
Créez un document Google Docs.
Saisissez le lien suivant, puis appuyez sur
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Cliquez sur le lien.
Dans le fichier
Visual Studio Code
de votre environnement local, vous pouvez constater 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.
Lorsque vous reprenez l'exécution à partir du débogueur de
Visual Studio Code
avant que les modules complémentaires Google Workspace n'expirent, le module complémentaire Google Workspace affiche l'aperçu du lien dans le document Google Docs à partir du cache.Vous pouvez consulter les journaux des requêtes et des réponses HTTP à partir de l'interface Web hébergée par l'application
ngrok
dans votre environnement local.Figure 7. Requête HTTP provenant de l'interface Web hébergée par l'application
ngrok
.Pour modifier le comportement de l'application, remplacez
Case
par l'56
intégréeCase:
du fichiermain.py
. Lorsque vous enregistrez le fichier,Visual Studio Code
actualise automatiquement l'application avec le code source mis à jour et reste en mode débogage.Figure 8. L'application s'exécute et écoute les requêtes HTTP sur le port
9000
avec la modification du code chargée.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 sur l'interface Web hébergée par l'application
ngrok
dans votre environnement local, puis cliquer surReplay
. Comme la dernière fois, votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage.Lorsque vous reprenez l'exécution à partir du débogueur de
Visual Studio Code
, vous pouvez voir depuis l'interface Web hébergée par l'applicationngrok
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
Depuis l'IDE
Visual Studio Code
installé dans votre environnement local, procédez comme suit:- Dans une nouvelle fenêtre, ouvrez le dossier
add-ons-samples/java/3p-resources
. Configurez le projet Maven pour qu'il exécute l'application
CreateLinkPreview
sur le port9000
localement en ajoutant le plug-in de compilationfunction-maven-plugin
du framework Cloud Functions dans le fichierpom.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> ...
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
Créez le fichier
.vscode/launch.json
dans le répertoire racine et configurez un lancement nomméRemote Debug Watch
qui sera associé à l'application précédemment lancée avec le port8000
:{ "version": "0.2.0", "configurations": [{ "type": "java", "request": "attach", "name": "Remote Debug Watch", "projectName": "http-function", "hostName": "localhost", "port": 8000 }] }
Ajoutez un point d'arrêt qui suspend le traitement des requêtes HTTP dans le fichier
CreateLinkPreview.java
, puis commencez l'association et le débogage avec la configurationRemote Debug Watch
ajoutée précédemment. L'application est maintenant en cours d'exécution et écoute les requêtes HTTP sur le port9000
.Figure 3 : L'application est en cours d'exécution et écoute les requêtes HTTP sur le port
9000
.
- Dans une nouvelle fenêtre, ouvrez le dossier
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 comptengrok
. Toutes les requêtes sont maintenant 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 redirigeant.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 l'ouvrant dans un navigateur.Figure 5 : Interface Web hébergée par l'application
ngrok
n'affichant aucune requête HTTP.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 testeur:
Créez un document Google Docs.
Saisissez le lien suivant, puis appuyez sur
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Cliquez sur le lien.
Dans le fichier
Visual Studio Code
de votre environnement local, vous pouvez constater 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.
Lorsque vous reprenez l'exécution à partir du débogueur de
Visual Studio Code
avant que les modules complémentaires Google Workspace n'expirent, le module complémentaire Google Workspace affiche l'aperçu du lien dans le document Google Docs à partir du cache.Vous pouvez consulter les journaux des requêtes et des réponses HTTP à partir de l'interface Web hébergée par l'application
ngrok
dans votre environnement local.Figure 7. Requête HTTP provenant de l'interface Web hébergée par l'application
ngrok
.Pour modifier le comportement de l'application, remplacez
Case
parCase:
78
intégré dans le fichierCreateLinkPreview.java
, redémarrez le processusmvnDebug
, puis relancezRemote Debug Watch
pour réassocier et redémarrer le débogage.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 sur l'interface Web hébergée par l'application
ngrok
dans votre environnement local, puis cliquer surReplay
. Comme la dernière fois, votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage.Lorsque vous reprenez l'exécution à partir du débogueur de
Visual Studio Code
, vous pouvez voir depuis l'interface Web hébergée par l'applicationngrok
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 depuis 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éboguer depuis un environnement distant
Prérequis
- Votre module complémentaire Google Workspace est déployé et installé.
- Votre application s'exécutant dans votre environnement distant avec le débogueur activé sur un port donné est référencé
REMOTE_DEBUG_PORT
dans les instructions de ce guide. - Votre environnement local peut
ssh
vers votre environnement distant. - IDE configuré dans votre environnement local et capable de procéder au débogage Nous utilisons l'IDE
Visual Studio Code
et ses fonctionnalités de débogage par défaut dans ce guide à des fins d'illustration.
Connectez vos environnements local et distant
Dans l'environnement local à partir duquel vous souhaitez établir 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 distantREMOTE_DEBUG_PORT
: port de débogage dans votre environnement distant.
Le port de débogage de votre environnement local est désormais associé au port de débogage de votre environnement distant.
Démarrer le débogage
Depuis l'IDE Visual Studio Code
installé dans votre environnement local, procédez comme suit:
- Dans une nouvelle fenêtre, ouvrez le code source de votre application.
Créez le fichier
.vscode/launch.json
dans le répertoire racine et configurez un lancement nomméDebug Remote
qui se connecte au port de débogage de 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 de votre environnement local.Ajoutez un point d'arrêt dans le code source de votre application qui suspend le traitement des requêtes HTTP, et commencez 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 que vous avez installé. Votre module complémentaire Google Workspace ne répond pas, car il est en cours de débogage actif dans l'IDE Visual Studio Code
.
Articles associés
Découvrez comment interroger les journaux d'erreurs.