Como desenvolvedor de complementos do Google Workspace, talvez você precise depurar o código para testar mudanças ou resolver problemas complexos. A depuração de complementos do Google Workspace pode ser feita de várias maneiras diferentes, dependendo da arquitetura do app, do que ele faz, de como ele é implantado e das suas preferências.
Nesta página, explicamos como depurar um complemento do Google Workspace usando o ngrok, uma plataforma de entrada unificada que pode ser usada para testar ambientes de desenvolvimento locais. Neste guia, você testará alterações de código em um ambiente local e solucionará problemas em um ambiente remoto.
Depurar a partir do ambiente de desenvolvimento local
Nesta seção, você interage com o complemento do Google Workspace que é executado no seu ambiente local.
Figura 1. Depurar em um ambiente de desenvolvimento local.
Pré-requisitos
Node.js
- Versões mais recentes de
node
enpm
instaladas no ambiente local. Versão mais recente do
nodemon
instalada no ambiente local, ela é usada para atualizações automáticas:npm install -g nodemon
Um projeto do Google Cloud. Siga as seções Pré-requisitos e Configurar o ambiente do Guia de início rápido.
O código do complemento do Google Workspace para depurar no seu ambiente local. Usamos os recursos de link de visualização do exemplo de código
3p-resources
do repositório do GitHubgoogleworkspace/add-ons-samples
neste guia para fins ilustrativos.Um IDE configurado no seu ambiente local que pode depurar. Usamos o ambiente de desenvolvimento integrado
Visual Studio Code
e os recursos de depuração padrão neste guia para fins ilustrativos.Uma conta do
ngrok
.Versão mais recente do
gcloud
instalada e inicializada no ambiente local.
Python
- Versão mais recente do
python3
instalada no ambiente local. - Com a versão mais recente do
pip
e dovirtualenv
instaladas no ambiente local, eles são usados para gerenciar pacotes do Python e ambientes virtuais, respectivamente. - Um projeto do Google Cloud. Siga as seções Pré-requisitos e Configurar o ambiente do Guia de início rápido.
- O código do complemento do Google Workspace para depurar no seu ambiente
local. Usamos os recursos de link de visualização do exemplo de código
3p-resources
do repositório do GitHubgoogleworkspace/add-ons-samples
neste guia para fins ilustrativos. - Um IDE configurado no seu ambiente local que pode depurar. Usamos o
ambiente de desenvolvimento integrado
Visual Studio Code
e os recursos de depuração padrão neste guia para fins ilustrativos. - Uma conta do
ngrok
. - Versão mais recente do
gcloud
instalada e inicializada no ambiente local.
Java
- Versão estável mais recente do
Java SE 11's JDK
instalada no ambiente local. - Versão mais recente do
Apache Maven
instalada no ambiente local. Ela é usada para gerenciar projetos Java. - Um projeto do Google Cloud. Siga as seções Pré-requisitos e Configurar o ambiente do Guia de início rápido.
- O código do complemento do Google Workspace para depurar no seu ambiente
local. Usamos os recursos de link de visualização do exemplo de código
3p-resources
do repositório do GitHubgoogleworkspace/add-ons-samples
neste guia para fins ilustrativos. - Um IDE configurado no seu ambiente local que pode depurar. Usamos o
ambiente de desenvolvimento integrado
Visual Studio Code
e os recursos de depuração padrão neste guia para fins ilustrativos. - Uma conta do
ngrok
. - Versão mais recente do
gcloud
instalada e inicializada no ambiente local.
Disponibilizar o serviço de localhost publicamente
Conecte o ambiente local à Internet para que o
complemento do Google Workspace possa acessá-lo. O aplicativo ngrok
é usado
para redirecionar solicitações HTTP feitas a um URL público para seu ambiente local.
- Em um navegador no ambiente local, faça login na conta do
ngrok
. - Instale o aplicativo e configure o
authtoken
no ambiente local. - Crie um domínio estático na sua
conta
ngrok
, que é mencionado comoNGROK_STATIC_DOMAIN
nas instruções deste guia.
Criar e instalar a implantação do complemento
Configure o complemento do Google Workspace para enviar todas as solicitações HTTP para seu domínio estático. O arquivo de implantação terá a seguinte aparência:
{ "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" } ] } } }
Substitua
NGROK_STATIC_DOMAIN
pelo domínio estático na sua conta dongrok
.Defina o projeto do Google Cloud para usar:
gcloud config set project PROJECT_ID
Consiga novas credenciais de usuário que serão usadas no Application Default Credentials:
gcloud auth application-default login
Substitua
PROJECT_ID
pelo ID do projeto do projeto do Google Cloud do app.Crie a implantação:
gcloud workspace-add-ons deployments create manageSupportCases \ --deployment-file=DEPLOYMENT_FILE_PATH
Substitua
DEPLOYMENT_FILE_PATH
pelo caminho do arquivo de implantação.Instale a implantação:
gcloud workspace-add-ons deployments install manageSupportCases
Figura 2. O complemento do Google Workspace envia todas as solicitações HTTP
para o domínio estático. O serviço público ngrok
funciona como uma ponte entre o
complemento do Google Workspace e o código do aplicativo executado
localmente.
Testar o complemento do Google Workspace
É possível implantar, testar, depurar e recarregar localmente seu complemento do Google Workspace.
Node.js
No ambiente de desenvolvimento integrado
Visual Studio Code
instalado no seu ambiente local, faça o seguinte:- Em uma nova janela, abra a pasta
add-ons-samples/node/3p-resources
. Configure o aplicativo para execução local e recarregue automaticamente a depuração adicionando uma dependência e dois scripts no arquivo
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" } ... }
No diretório raiz, instale o aplicativo:
npm install
Crie e configure uma inicialização chamada
Debug Watch
que aciona o scriptdebug-watch
criando o arquivo.vscode/launch.json
no diretório raiz:{ "version": "0.2.0", "configurations": [{ "type": "node", "request": "launch", "name": "Debug Watch", "cwd": "${workspaceRoot}", "runtimeExecutable": "npm", "runtimeArgs": ["run-script", "debug-watch"] }] }
Adicione um ponto de interrupção que pause o processamento da solicitação HTTP no arquivo
index.js
e comece a executar e depurar com a configuraçãoDebug Watch
adicionada anteriormente. O aplicativo está em execução e detectando solicitações HTTP na porta9000
.Figura 3. O aplicativo está em execução e detectando solicitações HTTP na porta
9000
.
- Em uma nova janela, abra a pasta
Inicie o aplicativo
ngrok
no ambiente local:ngrok http --domain=NGROK_STATIC_DOMAIN 9000
Substitua
NGROK_STATIC_DOMAIN
pelo domínio estático na sua conta dongrok
. Todas as solicitações agora são redirecionadas para o ambiente local e para a porta usada pelo aplicativo.Figura 4. O terminal com o servidor
ngrok
em execução e redirecionando.Uma interface da Web também é iniciada no seu localhost pelo aplicativo
ngrok
. É possível monitorar todas as atividades abrindo-a em um navegador.Figura 5. A interface da Web hospedada pelo aplicativo
ngrok
que não mostra solicitações HTTP.Para testar seu complemento do Google Workspace, acesse a prévia do URL de um caso em um novo arquivo do Documentos Google com uma conta de testador:
Crie um novo arquivo dos Documentos Google.
Digite o link a seguir e pressione
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Clique no link.
No
Visual Studio Code
do seu ambiente local, é possível conferir que a execução foi pausada no ponto de interrupção definido.Figura 6. A execução é pausada no ponto de interrupção que foi definido.
Quando você retoma a execução do depurador de
Visual Studio Code
antes de os complementos do Google Workspace expirarem, o complemento exibirá a visualização do link no documento Google do cache.É possível verificar os registros de solicitação e resposta HTTP na interface da Web hospedada pelo aplicativo
ngrok
no ambiente local.Figura 7. A solicitação HTTP da interface da Web hospedada pelo aplicativo
ngrok
.Para mudar o comportamento do aplicativo, substitua
Case
porCase:
in-line51
doindex.js
. Quando você salva o arquivo,nodemon
recarrega automaticamente o aplicativo com o código-fonte atualizado eVisual Studio Code
permanece no modo de depuração.Figura 8. O aplicativo está em execução e detectando solicitações HTTP na porta
9000
com a mudança de código carregada.Desta vez, em vez de clicar no link e esperar alguns segundos em um novo documento Google, você pode selecionar a última solicitação HTTP registrada na interface da Web hospedada pelo aplicativo
ngrok
no seu ambiente local e clicar emReplay
. Assim como na última vez, seu complemento do Google Workspace não respondeu porque está sendo depurado ativamente.Ao retomar a execução do depurador de
Visual Studio Code
, você pode ver na interface da Web hospedada pelo aplicativongrok
no ambiente local que o aplicativo gera uma resposta com a versão atualizada do cartão de visualização.
Python
No ambiente de desenvolvimento integrado
Visual Studio Code
instalado no seu ambiente local, faça o seguinte:- Em uma nova janela, abra a pasta
add-ons-samples/python/3p-resources/create_link_preview
. Crie um novo ambiente virtual para o Python
env
e ative-o:virtualenv env
source env/bin/activate
Instale todas as dependências do projeto usando
pip
no ambiente virtual:pip install -r requirements.txt
Crie o arquivo
.vscode/launch.json
no diretório raiz e configure uma inicialização chamadaDebug Watch
que aciona o aplicativo do módulofunctions-framework
na porta9000
no modo de depuração no ambiente virtualenv
:{ "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" ] }] }
Adicione um ponto de interrupção que pause o processamento da solicitação HTTP no arquivo
main.py
e comece a executar e depurar com a configuraçãoDebug Watch
adicionada anteriormente. O aplicativo está em execução e detectando solicitações HTTP na porta9000
.Figura 3. O aplicativo está em execução e detectando solicitações HTTP na porta
9000
.
- Em uma nova janela, abra a pasta
Inicie o aplicativo
ngrok
no ambiente local:ngrok http --domain=NGROK_STATIC_DOMAIN 9000
Substitua
NGROK_STATIC_DOMAIN
pelo domínio estático na sua conta dongrok
. Todas as solicitações agora são redirecionadas para o ambiente local e para a porta usada pelo aplicativo.Figura 4. O terminal com o servidor
ngrok
em execução e redirecionando.Uma interface da Web também é iniciada no seu localhost pelo aplicativo
ngrok
. É possível monitorar todas as atividades abrindo-a em um navegador.Figura 5. A interface da Web hospedada pelo aplicativo
ngrok
que não mostra solicitações HTTP.Para testar seu complemento do Google Workspace, acesse a prévia do URL de um caso em um novo arquivo do Documentos Google com uma conta de testador:
Crie um novo arquivo dos Documentos Google.
Digite o link a seguir e pressione
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Clique no link.
No
Visual Studio Code
do seu ambiente local, é possível conferir que a execução foi pausada no ponto de interrupção definido.Figura 6. A execução é pausada no ponto de interrupção que foi definido.
Quando você retoma a execução do depurador de
Visual Studio Code
antes de os complementos do Google Workspace expirarem, o complemento exibirá a visualização do link no documento Google do cache.É possível verificar os registros de solicitação e resposta HTTP na interface da Web hospedada pelo aplicativo
ngrok
no ambiente local.Figura 7. A solicitação HTTP da interface da Web hospedada pelo aplicativo
ngrok
.Para mudar o comportamento do aplicativo, substitua
Case
porCase:
in-line56
do arquivomain.py
. Quando você salva o arquivo, oVisual Studio Code
recarrega automaticamente o aplicativo com o código-fonte atualizado e permanece no modo de depuração.Figura 8. O aplicativo está em execução e detectando solicitações HTTP na porta
9000
com a mudança de código carregada.Desta vez, em vez de clicar no link e esperar alguns segundos em um novo documento Google, você pode selecionar a última solicitação HTTP registrada na interface da Web hospedada pelo aplicativo
ngrok
no seu ambiente local e clicar emReplay
. Assim como na última vez, seu complemento do Google Workspace não respondeu porque está sendo depurado ativamente.Ao retomar a execução do depurador de
Visual Studio Code
, você pode ver na interface da Web hospedada pelo aplicativongrok
no ambiente local que o aplicativo gera uma resposta com a versão atualizada do cartão de visualização.
Java
No ambiente de desenvolvimento integrado
Visual Studio Code
instalado no seu ambiente local, faça o seguinte:- Em uma nova janela, abra a pasta
add-ons-samples/java/3p-resources
. Configure o projeto Maven para executar localmente o aplicativo
CreateLinkPreview
na porta9000
adicionando o plug-in de build do Cloud Functions Frameworkfunction-maven-plugin
ao arquivopom.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> ...
Agora é possível iniciá-la localmente no modo de depuração:
mvnDebug function:run Preparing to execute Maven in debug mode Listening for transport dt_socket at address: 8000
Crie o arquivo
.vscode/launch.json
no diretório raiz e configure uma inicialização chamadaRemote Debug Watch
que é anexada ao aplicativo iniciado anteriormente com a porta8000
:{ "version": "0.2.0", "configurations": [{ "type": "java", "request": "attach", "name": "Remote Debug Watch", "projectName": "http-function", "hostName": "localhost", "port": 8000 }] }
Adicione um ponto de interrupção que pause o processamento da solicitação HTTP no arquivo
CreateLinkPreview.java
e comece a anexar e depurar com a configuraçãoRemote Debug Watch
adicionada anteriormente. O aplicativo está em execução e recebendo solicitações HTTP na porta9000
.Figura 3.O aplicativo está em execução e detectando solicitações HTTP na porta
9000
.
- Em uma nova janela, abra a pasta
Inicie o aplicativo
ngrok
no ambiente local:ngrok http --domain=NGROK_STATIC_DOMAIN 9000
Substitua
NGROK_STATIC_DOMAIN
pelo domínio estático na sua conta dongrok
. Todas as solicitações agora são redirecionadas para o ambiente local e para a porta usada pelo aplicativo.Figura 4. O terminal com o servidor
ngrok
em execução e redirecionando.Uma interface da Web também é iniciada no seu localhost pelo aplicativo
ngrok
. É possível monitorar todas as atividades abrindo-a em um navegador.Figura 5. A interface da Web hospedada pelo aplicativo
ngrok
que não mostra solicitações HTTP.Para testar seu complemento do Google Workspace, acesse a prévia do URL de um caso em um novo arquivo do Documentos Google com uma conta de testador:
Crie um novo arquivo dos Documentos Google.
Digite o link a seguir e pressione
enter
:https://example.com/support/case/?name=Name1&description=Description1&priority=P1
Clique no link.
No
Visual Studio Code
do seu ambiente local, é possível conferir que a execução foi pausada no ponto de interrupção definido.Figura 6. A execução é pausada no ponto de interrupção que foi definido.
Quando você retoma a execução do depurador de
Visual Studio Code
antes de os complementos do Google Workspace expirarem, o complemento exibirá a visualização do link no documento Google do cache.É possível verificar os registros de solicitação e resposta HTTP na interface da Web hospedada pelo aplicativo
ngrok
no ambiente local.Figura 7. A solicitação HTTP da interface da Web hospedada pelo aplicativo
ngrok
.Para mudar o comportamento do aplicativo, substitua
Case
porCase:
in-line78
do arquivoCreateLinkPreview.java
, reinicie o processomvnDebug
e reinicieRemote Debug Watch
para reanexar e reiniciar a depuração.Desta vez, em vez de clicar no link e esperar alguns segundos em um novo documento Google, você pode selecionar a última solicitação HTTP registrada na interface da Web hospedada pelo aplicativo
ngrok
no seu ambiente local e clicar emReplay
. Assim como na última vez, seu complemento do Google Workspace não respondeu porque está sendo depurado ativamente.Ao retomar a execução do depurador de
Visual Studio Code
, você pode ver na interface da Web hospedada pelo aplicativongrok
no ambiente local que o aplicativo gera uma resposta com a versão atualizada do cartão de visualização.
Depurar do ambiente remoto
Nesta seção, você interage com seu complemento do Google Workspace, que é executado em um ambiente remoto.
Figura 9. Depurar em ambiente remoto.
Pré-requisitos
- Seu complemento do Google Workspace foi implantado e instalado.
- O aplicativo em execução no ambiente remoto com o depurador ativado em uma determinada porta é referenciado como
REMOTE_DEBUG_PORT
nas instruções deste guia. - O ambiente local pode
ssh
para o ambiente remoto. - Um IDE configurado no seu ambiente local que pode depurar. Usamos o
ambiente de desenvolvimento integrado
Visual Studio Code
e os recursos de depuração padrão neste guia para fins ilustrativos.
Conecte seus ambientes locais e remotos
No ambiente local em que você quer iniciar uma conexão do cliente de depuração, configure um túnel SSH:
ssh -L LOCAL_DEBUG_PORT:localhost:REMOTE_DEBUG_PORT REMOTE_USERNAME@REMOTE_ADDRESS
Substitua:
LOCAL_DEBUG_PORT
: a porta de depuração no ambiente local.REMOTE_USERNAME
: o nome de usuário no ambiente remoto.REMOTE_ADDRESS
: o endereço do ambiente remoto.REMOTE_DEBUG_PORT
: a porta de depuração no ambiente remoto.
A porta de depuração no ambiente local agora está vinculada à porta de depuração no ambiente remoto.
Começar a depurar
No ambiente de desenvolvimento integrado Visual Studio Code
instalado no seu ambiente local, faça o
seguinte:
- Em uma nova janela, abra o código-fonte do app.
Crie o arquivo
.vscode/launch.json
no diretório raiz e configure um lançamento chamadoDebug Remote
, que é conectado à porta de depuração no ambiente 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 }] }
Substitua
LOCAL_DEBUG_PORT
pela porta de depuração no ambiente local.Adicione um ponto de interrupção ao código-fonte do app que pause o processamento da solicitação HTTP e comece a execução e depuração com a configuração
Debug Remote
adicionada anteriormente.
Interaja com o complemento do Google Workspace instalado. Seu
complemento do Google Workspace não responde porque está sendo
depurado
no ambiente de desenvolvimento integrado Visual Studio Code
.
Temas relacionados
Saiba como consultar registros de erros.