In qualità di sviluppatore di componenti aggiuntivi di Google Workspace, potresti dover eseguire il debug del codice per testare le modifiche o risolvere problemi complessi. Il debug dei componenti aggiuntivi di Google Workspace può essere eseguito in molti modi diversi a seconda dell'architettura e dello scopo dell'app, del modo in cui viene eseguito il deployment dell'app e delle tue preferenze.
In questa pagina viene spiegato come eseguire il debug di un componente aggiuntivo di Google Workspace utilizzando ngrok, una piattaforma di traffico in entrata unificata che puoi utilizzare per testare gli ambienti di sviluppo locale. In questa guida testerai le modifiche al codice in un ambiente locale e risolverai i problemi in un ambiente remoto.
Debug dall'ambiente di sviluppo locale
In questa sezione interagisci con il componente aggiuntivo di Google Workspace che viene eseguito nel tuo ambiente locale.
Figura 1. Debug in un ambiente di sviluppo locale.
Prerequisiti
Node.js
- Le versioni più recenti di
node
enpm
installate nel tuo ambiente locale. La versione più recente di
nodemon
installata nel tuo ambiente locale; viene utilizzata a scopo di ricaricamento automatico:npm install -g nodemon
Un progetto Google Cloud. Puoi seguire le sezioni Prerequisiti e Configurare l'ambiente della Guida rapida.
Il codice del componente aggiuntivo di Google Workspace di cui eseguire il debug nel tuo ambiente locale. Utilizziamo le funzionalità dei link di anteprima dell'esempio di codice
3p-resources
del repository GitHubgoogleworkspace/add-ons-samples
in questa guida a scopo illustrativo.Un IDE configurato nel tuo ambiente locale che possa eseguire il debug. Utilizziamo l'IDE
Visual Studio Code
e le sue funzionalità di debug predefinite in questa guida a scopo illustrativo.Un account
ngrok
.La versione più recente di
gcloud
installata e inizializzata nel tuo ambiente locale.
Python
- La versione più recente di
python3
installata nel tuo ambiente locale. - La versione più recente di
pip
evirtualenv
installata nel tuo ambiente locale vengono utilizzate per gestire rispettivamente i pacchetti Python e gli ambienti virtuali. - Un progetto Google Cloud. Puoi seguire le sezioni Prerequisiti e Configurare l'ambiente della Guida rapida.
- Il codice del componente aggiuntivo di Google Workspace di cui eseguire il debug nel tuo ambiente locale. Utilizziamo le funzionalità dei link di anteprima dell'esempio di codice
3p-resources
del repository GitHubgoogleworkspace/add-ons-samples
in questa guida a scopo illustrativo. - Un IDE configurato nel tuo ambiente locale che possa eseguire il debug. Utilizziamo l'IDE
Visual Studio Code
e le sue funzionalità di debug predefinite in questa guida a scopo illustrativo. - Un account
ngrok
. - La versione più recente di
gcloud
installata e inizializzata nel tuo ambiente locale.
Java
- La versione stabile più recente di
Java SE 11's JDK
installata nel tuo ambiente locale. - La versione più recente di
Apache Maven
installata nel tuo ambiente locale viene utilizzata per gestire i progetti Java. - Un progetto Google Cloud. Puoi seguire le sezioni Prerequisiti e Configurare l'ambiente della Guida rapida.
- Il codice del componente aggiuntivo di Google Workspace di cui eseguire il debug nel tuo ambiente locale. Utilizziamo le funzionalità dei link di anteprima dell'esempio di codice
3p-resources
del repository GitHubgoogleworkspace/add-ons-samples
in questa guida a scopo illustrativo. - Un IDE configurato nel tuo ambiente locale che possa eseguire il debug. Utilizziamo l'IDE
Visual Studio Code
e le sue funzionalità di debug predefinite in questa guida a scopo illustrativo. - Un account
ngrok
. - La versione più recente di
gcloud
installata e inizializzata nel tuo ambiente locale.
Rendi disponibile pubblicamente il servizio localhost
Devi connettere il tuo ambiente locale a internet in modo che il componente aggiuntivo di Google Workspace possa accedervi. L'applicazione ngrok
viene utilizzata per reindirizzare le richieste HTTP effettuate a un URL pubblico al tuo ambiente locale.
- In un browser nel tuo ambiente locale, accedi al tuo account
ngrok
. - Installa l'applicazione e configura
authtoken
nel tuo ambiente locale. - Crea un dominio statico nel tuo account
ngrok
, che verrà indicato comeNGROK_STATIC_DOMAIN
nelle istruzioni di questa guida.
Crea e installa il deployment dei componenti aggiuntivi
Configura il componente aggiuntivo di Google Workspace in modo che invii tutte le relative richieste HTTP al tuo dominio statico. Il file di deployment dovrebbe avere il seguente aspetto:
{ "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" } ] } } }
Sostituisci
NGROK_STATIC_DOMAIN
con il dominio statico nel tuo accountngrok
.Imposta il progetto Google Cloud in modo da utilizzare:
gcloud config set project PROJECT_ID
Acquisisci nuove credenziali utente da utilizzare per Credenziali predefinite dell'applicazione:
gcloud auth application-default login
Sostituisci
PROJECT_ID
con l'ID progetto del progetto Google Cloud dell'app.Crea il deployment:
gcloud workspace-add-ons deployments create manageSupportCases \ --deployment-file=DEPLOYMENT_FILE_PATH
Sostituisci
DEPLOYMENT_FILE_PATH
con il percorso del file di deployment.Installa il deployment:
gcloud workspace-add-ons deployments install manageSupportCases
Figura 2. Il componente aggiuntivo di Google Workspace
invia tutte le sue richieste HTTP al dominio statico. Il servizio pubblico ngrok
funge da ponte tra il componente aggiuntivo di Google Workspace e il codice dell'applicazione che viene eseguito localmente.
Testa il componente aggiuntivo di Google Workspace
Puoi eseguire il deployment, testare, eseguire il debug e ricaricare automaticamente il tuo componente aggiuntivo di Google Workspace in locale.
Node.js
Dall'IDE
Visual Studio Code
installato nel tuo ambiente locale:- In una nuova finestra, apri la cartella
add-ons-samples/node/3p-resources
. Configura l'applicazione per l'esecuzione locale e il debug del ricaricamento automatico aggiungendo una dipendenza e due script nel file
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" } ... }
Dalla directory root, installa l'applicazione:
npm install
Crea e configura un lancio denominato
Debug Watch
che attivi lo scriptdebug-watch
creando il file.vscode/launch.json
nella directory root:{ "version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Debug Watch", "cwd": "${workspaceRoot}", "runtimeExecutable": "npm", "runtimeArgs": ["run-script", "debug-watch"] }] }
Aggiungi un punto di interruzione che metta in pausa l'elaborazione della richiesta HTTP nel file
index.js
e avvia l'esecuzione e il debug con la configurazioneDebug Watch
aggiunta in precedenza. L'applicazione ora è in esecuzione e rimane in attesa delle richieste HTTP sulla porta9000
.Figura 3. L'applicazione è in esecuzione e rimane in attesa delle richieste HTTP sulla porta
9000
.
- In una nuova finestra, apri la cartella
Avvia l'applicazione
ngrok
nel tuo ambiente locale:ngrok http --domain=NGROK_STATIC_DOMAIN 9000
Sostituisci
NGROK_STATIC_DOMAIN
con il dominio statico nel tuo accountngrok
. Tutte le richieste vengono ora reindirizzate al tuo ambiente locale e alla porta utilizzata dall'applicazione.Figura 4. Terminale con server
ngrok
in esecuzione e reindirizzamento.Un'interfaccia web viene avviata sul tuo localhost anche dall'applicazione
ngrok
; puoi monitorare tutte le attività aprendola in un browser.Figura 5. Interfaccia web ospitata dall'applicazione
ngrok
che non mostra richieste HTTP.Testa il tuo componente aggiuntivo di Google Workspace visualizzando l'anteprima dell'URL di una richiesta in un nuovo documento Google con un account tester:
Crea un nuovo documento Google.
Digita il seguente link e premi
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Fai clic sul link.
In
Visual Studio Code
nel tuo ambiente locale, puoi vedere che l'esecuzione è in pausa nel punto di interruzione impostato.Figura 6. L'esecuzione è in pausa nel punto di interruzione impostato.
Quando riprendi l'esecuzione dal debugger di
Visual Studio Code
prima del timeout dei componenti aggiuntivi di Google Workspace, il componente aggiuntivo di Google Workspace mostrerà l'anteprima del link nel documento Google dalla cache.Puoi controllare i log delle richieste e delle risposte HTTP dall'interfaccia web ospitata dall'applicazione
ngrok
nel tuo ambiente locale.Figura 7. La richiesta HTTP dall'interfaccia web ospitata dall'applicazione
ngrok
.Per modificare il comportamento dell'applicazione, sostituisci
Case
conCase:
incorporato51
diindex.js
. Quando salvi il file,nodemon
ricarica automaticamente l'applicazione con il codice sorgente aggiornato eVisual Studio Code
rimane in modalità di debug.Figura 8. L'applicazione è in esecuzione e rimane in attesa delle richieste HTTP sulla porta
9000
con la modifica del codice caricata.Questa volta, invece di fare clic sul link e attendere qualche secondo in un nuovo documento Google, puoi selezionare l'ultima richiesta HTTP registrata nell'interfaccia web ospitata dall'applicazione
ngrok
nel tuo ambiente locale e fare clic suReplay
. Come l'ultima volta, il componente aggiuntivo di Google Workspace non risponde perché è in fase di debug attivo.Quando riprendi l'esecuzione dal debugger di
Visual Studio Code
, potrai vedere dall'interfaccia web ospitata dall'applicazionengrok
nel tuo ambiente locale che l'applicazione genera una risposta con la versione aggiornata della scheda di anteprima.
Python
Dall'IDE
Visual Studio Code
installato nel tuo ambiente locale:- In una nuova finestra, apri la cartella
add-ons-samples/python/3p-resources/create_link_preview
. Crea un nuovo ambiente virtuale per Python
env
e attivalo:virtualenv env
source env/bin/activate
Installa tutte le dipendenze del progetto utilizzando
pip
nell'ambiente virtuale:pip install -r requirements.txt
Crea il file
.vscode/launch.json
nella directory root e configura un avvio denominatoDebug Watch
che attivi l'applicazione dal modulofunctions-framework
sulla porta9000
in modalità di debug nell'ambiente virtualeenv
:{ "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" ] }] }
Aggiungi un punto di interruzione che metta in pausa l'elaborazione della richiesta HTTP nel file
main.py
e avvia l'esecuzione e il debug con la configurazioneDebug Watch
aggiunta in precedenza. L'applicazione ora è in esecuzione e rimane in attesa delle richieste HTTP sulla porta9000
.Figura 3. L'applicazione è in esecuzione e rimane in attesa delle richieste HTTP sulla porta
9000
.
- In una nuova finestra, apri la cartella
Avvia l'applicazione
ngrok
nel tuo ambiente locale:ngrok http --domain=NGROK_STATIC_DOMAIN 9000
Sostituisci
NGROK_STATIC_DOMAIN
con il dominio statico nel tuo accountngrok
. Tutte le richieste vengono ora reindirizzate al tuo ambiente locale e alla porta utilizzata dall'applicazione.Figura 4. Terminale con server
ngrok
in esecuzione e reindirizzamento.Un'interfaccia web viene avviata sul tuo localhost anche dall'applicazione
ngrok
; puoi monitorare tutte le attività aprendola in un browser.Figura 5. Interfaccia web ospitata dall'applicazione
ngrok
che non mostra richieste HTTP.Testa il tuo componente aggiuntivo di Google Workspace visualizzando l'anteprima dell'URL di una richiesta in un nuovo documento Google con un account tester:
Crea un nuovo documento Google.
Digita il seguente link e premi
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Fai clic sul link.
In
Visual Studio Code
nel tuo ambiente locale, puoi vedere che l'esecuzione è in pausa nel punto di interruzione impostato.Figura 6. L'esecuzione è in pausa nel punto di interruzione impostato.
Quando riprendi l'esecuzione dal debugger di
Visual Studio Code
prima del timeout dei componenti aggiuntivi di Google Workspace, il componente aggiuntivo di Google Workspace mostrerà l'anteprima del link nel documento Google dalla cache.Puoi controllare i log delle richieste e delle risposte HTTP dall'interfaccia web ospitata dall'applicazione
ngrok
nel tuo ambiente locale.Figura 7. La richiesta HTTP dall'interfaccia web ospitata dall'applicazione
ngrok
.Per modificare il comportamento dell'applicazione, sostituisci
Case
conCase:
incorporato56
del filemain.py
. Quando salvi il file,Visual Studio Code
ricarica automaticamente l'applicazione con il codice sorgente aggiornato e rimane in modalità di debug.Figura 8. L'applicazione è in esecuzione e rimane in attesa delle richieste HTTP sulla porta
9000
con la modifica del codice caricata.Questa volta, invece di fare clic sul link e attendere qualche secondo in un nuovo documento Google, puoi selezionare l'ultima richiesta HTTP registrata nell'interfaccia web ospitata dall'applicazione
ngrok
nel tuo ambiente locale e fare clic suReplay
. Come l'ultima volta, il componente aggiuntivo di Google Workspace non risponde perché è in fase di debug attivo.Quando riprendi l'esecuzione dal debugger di
Visual Studio Code
, potrai vedere dall'interfaccia web ospitata dall'applicazionengrok
nel tuo ambiente locale che l'applicazione genera una risposta con la versione aggiornata della scheda di anteprima.
Java
Dall'IDE
Visual Studio Code
installato nel tuo ambiente locale:- In una nuova finestra, apri la cartella
add-ons-samples/java/3p-resources
. Configura il progetto Maven per eseguire l'applicazione
CreateLinkPreview
sulla porta9000
in locale aggiungendo il plug-in di build del framework Cloud Functionsfunction-maven-plugin
nel filepom.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> ...
Ora puoi avviarlo localmente in modalità di debug:
mvnDebug function:run Preparing to execute Maven in debug mode Listening for transport dt_socket at address: 8000
Crea il file
.vscode/launch.json
nella directory root e configura un lancio denominatoRemote Debug Watch
che si collega all'applicazione avviata in precedenza con la porta8000
:{ "version": "0.2.0", "configurations": [{ "type": "java", "request": "attach", "name": "Remote Debug Watch", "projectName": "http-function", "hostName": "localhost", "port": 8000 }] }
Aggiungi un punto di interruzione che metta in pausa l'elaborazione della richiesta HTTP nel file
CreateLinkPreview.java
e avvia il collegamento e il debug con la configurazioneRemote Debug Watch
aggiunta in precedenza. L'applicazione ora è in esecuzione e rimane in attesa delle richieste HTTP sulla porta9000
.Figura 3: l'applicazione è in esecuzione e rimane in ascolto delle richieste HTTP sulla porta
9000
.
- In una nuova finestra, apri la cartella
Avvia l'applicazione
ngrok
nel tuo ambiente locale:ngrok http --domain=NGROK_STATIC_DOMAIN 9000
Sostituisci
NGROK_STATIC_DOMAIN
con il dominio statico nel tuo accountngrok
. Tutte le richieste vengono ora reindirizzate al tuo ambiente locale e alla porta utilizzata dall'applicazione.Figura 4. Terminale con server
ngrok
in esecuzione e reindirizzamento.Un'interfaccia web viene avviata sul tuo localhost anche dall'applicazione
ngrok
; puoi monitorare tutte le attività aprendola in un browser.Figura 5. Interfaccia web ospitata dall'applicazione
ngrok
che non mostra richieste HTTP.Testa il tuo componente aggiuntivo di Google Workspace visualizzando l'anteprima dell'URL di una richiesta in un nuovo documento Google con un account tester:
Crea un nuovo documento Google.
Digita il seguente link e premi
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Fai clic sul link.
In
Visual Studio Code
nel tuo ambiente locale, puoi vedere che l'esecuzione è in pausa nel punto di interruzione impostato.Figura 6. L'esecuzione è in pausa nel punto di interruzione impostato.
Quando riprendi l'esecuzione dal debugger di
Visual Studio Code
prima del timeout dei componenti aggiuntivi di Google Workspace, il componente aggiuntivo di Google Workspace mostrerà l'anteprima del link nel documento Google dalla cache.Puoi controllare i log delle richieste e delle risposte HTTP dall'interfaccia web ospitata dall'applicazione
ngrok
nel tuo ambiente locale.Figura 7. La richiesta HTTP dall'interfaccia web ospitata dall'applicazione
ngrok
.Per modificare il comportamento dell'applicazione, sostituisci
Case
conCase:
incorporato78
del fileCreateLinkPreview.java
, riavvia il processomvnDebug
e riavviaRemote Debug Watch
per ricollegare e riavviare il debug.Questa volta, invece di fare clic sul link e attendere qualche secondo in un nuovo documento Google, puoi selezionare l'ultima richiesta HTTP registrata nell'interfaccia web ospitata dall'applicazione
ngrok
nel tuo ambiente locale e fare clic suReplay
. Come l'ultima volta, il componente aggiuntivo di Google Workspace non risponde perché è in fase di debug attivo.Quando riprendi l'esecuzione dal debugger di
Visual Studio Code
, potrai vedere dall'interfaccia web ospitata dall'applicazionengrok
nel tuo ambiente locale che l'applicazione genera una risposta con la versione aggiornata della scheda di anteprima.
Debug dall'ambiente remoto
In questa sezione interagisci con il componente aggiuntivo di Google Workspace che viene eseguito in un ambiente remoto.
Figura 9. Debug dall'ambiente remoto.
Prerequisiti
- Il componente aggiuntivo di Google Workspace di cui è stato eseguito il deployment e l'installazione.
- L'applicazione in esecuzione nell'ambiente remoto con il debugger
abilitato su una determinata porta, viene indicata come
REMOTE_DEBUG_PORT
nelle istruzioni di questa guida. - Il tuo ambiente locale può
ssh
rispetto al tuo ambiente remoto. - Un IDE configurato nel tuo ambiente locale che possa eseguire il debug. In questa guida utilizziamo l'IDE
Visual Studio Code
e le sue funzionalità predefinite di debug a scopo illustrativo.
Connetti i tuoi ambienti locali e remoti
Configura un tunnel SSH nell'ambiente locale in cui vuoi avviare una connessione client di debug:
ssh -L LOCAL_DEBUG_PORT:localhost:REMOTE_DEBUG_PORT REMOTE_USERNAME@REMOTE_ADDRESS
Sostituisci quanto segue:
LOCAL_DEBUG_PORT
: la porta di debug nel tuo ambiente locale.REMOTE_USERNAME
: il nome utente nel tuo ambiente remoto.REMOTE_ADDRESS
: l'indirizzo del tuo ambiente remoto.REMOTE_DEBUG_PORT
: la porta di debug nell'ambiente remoto.
La porta di debug nel tuo ambiente locale è ora collegata alla porta di debug nell'ambiente remoto.
Avvia debug
Dall'IDE Visual Studio Code
installato nel tuo ambiente locale:
- In una nuova finestra, apri il codice sorgente dell'app.
Crea il file
.vscode/launch.json
nella directory root e configura un lancio denominatoDebug Remote
che si collega alla porta di debug nel tuo ambiente locale: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 }] }
Sostituisci
LOCAL_DEBUG_PORT
con la porta di debug nel tuo ambiente locale.Aggiungi un punto di interruzione nel codice sorgente dell'app che metta in pausa l'elaborazione della richiesta HTTP e avvia l'esecuzione e il debug con la configurazione
Debug Remote
aggiunta in precedenza.
Interagire con il componente aggiuntivo di Google Workspace installato. Il componente aggiuntivo di Google Workspace non risponde perché è in corso il debug attivo nell'IDE Visual Studio Code
.
Argomenti correlati
Scopri come eseguire query sui log degli errori.