Testar e depurar complementos HTTP do Google Workspace

Como desenvolvedor de complementos do Google Workspace, talvez você precise depurar o código para testar mudanças ou solucionar problemas complexos. A depuração de complementos do Google Workspace pode ser feita de várias formas, dependendo da arquitetura do seu app, da função dele, da forma como o app é implantado e das suas preferências.

Esta página explica como depurar um complemento HTTP do Google Workspace usando ngrok, uma plataforma de entrada unificada que pode ser usada para testar ambientes de desenvolvimento local. Neste guia, você vai testar as mudanças no código em um ambiente local e resolver problemas em um ambiente remoto.

Depurar no 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

• As versões mais recentes de node e npm instaladas no seu ambiente local.

• A versão mais recente do nodemon instalada no seu ambiente local. Ele é usado para recarga automática:

  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 ambiente local. Usamos os recursos de link de visualização do exemplo de código 3p-resources do repositório do GitHub googleworkspace/add-ons-samples neste guia para fins de ilustração.

• Um ambiente de desenvolvimento integrado configurado no ambiente local que pode depurar. Usamos o Visual Studio Code IDE e os recursos de depuração padrão dele neste guia para fins de ilustração.

• Uma conta do ngrok.

• Ter a versão mais recente do gcloud instalada e inicializada no ambiente local.

Python

• A versão mais recente do python3 instalada no ambiente local.
• Ter a versão mais recente do pip e do virtualenv instalada no ambiente local. Eles são usados para gerenciar pacotes e ambientes virtuais do Python, 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 ambiente local. Usamos os recursos de link de visualização do exemplo de código 3p-resources do repositório do GitHub googleworkspace/add-ons-samples neste guia para fins de ilustração.
• Um ambiente de desenvolvimento integrado configurado no ambiente local que pode depurar. Usamos o Visual Studio Code IDE e os recursos de depuração padrão dele neste guia para fins de ilustração.
• Uma conta do ngrok.
• Ter a versão mais recente do gcloud instalada e inicializada no ambiente local.

Java

• A versão estável mais recente do Java SE 11's JDK instalada no seu ambiente local.
• A versão mais recente do Apache Maven instalada no ambiente local. Ele é usado 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 ambiente local. Usamos os recursos de link de visualização do exemplo de código 3p-resources do repositório do GitHub googleworkspace/add-ons-samples neste guia para fins de ilustração.
• Um ambiente de desenvolvimento integrado configurado no ambiente local que pode depurar. Usamos o Visual Studio Code IDE e os recursos de depuração padrão dele neste guia para fins de ilustração.
• Uma conta do ngrok.
• Ter a versão mais recente do gcloud instalada e inicializada no ambiente local.

Disponibilizar o serviço localhost publicamente

É necessário conectar seu ambiente local à Internet para que o complemento do Google Workspace possa acessá-lo. O aplicativo ngrok é usado para redirecionar solicitações HTTP feitas para um URL público ao seu ambiente local.

1. Em um navegador no seu ambiente local, faça login na sua conta do ngrok.
2. Instale o aplicativo e configure o authtoken no ambiente local.
3. Crie um domínio estático na sua conta ngrok, que é referenciada como NGROK_STATIC_DOMAIN nas instruções deste guia.

Criar e instalar a implantação do complemento

1. Configure o complemento do Google Workspace para enviar todas as solicitações HTTP ao seu domínio estático. O arquivo de implantação vai ficar assim:

   {
     "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"
       }
     }
   }
   

   Substitua NGROK_STATIC_DOMAIN pelo domínio estático na sua conta ngrok.

2. Defina o projeto do Google Cloud a ser usado:

   gcloud config set project PROJECT_ID

3. 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 Google Cloud do app.

4. 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.

5. 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 que é executado localmente.

Testar o complemento do Google Workspace

É possível implantar, testar, depurar e recarregar automaticamente o complemento do Google Workspace localmente.

Observação: o complemento do Google Workspace é executado com o Cloud Functions Framework nos exemplos.

Node.js

1. No ambiente de desenvolvimento integrado Visual Studio Code instalado no ambiente local, faça o seguinte:

   1. Em uma nova janela, abra a pasta add-ons-samples/node/3p-resources.

   2. Configure o aplicativo para execução local e depuração de recarga automática 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"
          }
          ...
      }
      

   3. No diretório raiz, instale o aplicativo:

      npm install

   4. Crie e configure uma inicialização chamada Debug Watch que aciona o script debug-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"]
          }]
      }
      

   5. Adicione um ponto de interrupção que pausa o processamento da solicitação HTTP no arquivo index.js e inicie a execução e depuração com a configuração Debug Watch adicionada antes. O aplicativo agora está em execução e detectando solicitações HTTP na porta 9000.

      

      Figura 3. O aplicativo está em execução e detectando solicitações HTTP na porta 9000.

2. Inicie o aplicativo ngrok no seu ambiente local:

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   Substitua NGROK_STATIC_DOMAIN pelo domínio estático na sua conta ngrok. Agora, todas as solicitações são redirecionadas para o ambiente local e a porta usada pelo aplicativo.

   

   Figura 4. O terminal com o servidor ngrok em execução e redirecionamento.

3. Uma interface da Web também é iniciada no host local pelo aplicativo ngrok. É possível monitorar todas as atividades abrindo-as em um navegador.

   

   Figura 5. A interface da Web hospedada pelo aplicativo ngrok não mostra solicitações HTTP.

4. Teste seu complemento do Google Workspace com uma prévia do URL de um caso em um novo documento do Google com uma conta de teste:

   • Crie um documento Google.

     Criar um arquivo do Documentos Google

   • Digite o seguinte link e pressione enter:

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

   • Clique no link.

5. No Visual Studio Code no seu ambiente local, é possível ver que a execução é pausada no ponto de interrupção definido.

   

   Figura 6. A execução é pausada no ponto de interrupção definido.

6. Quando você retoma a execução do depurador Visual Studio Code antes que os complementos do Google Workspace expirem, o complemento mostra a visualização do link no Google Docs do cache.

7. É possível verificar os registros de solicitação e resposta HTTP na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local.

   

   Figura 7. A solicitação HTTP da interface da Web hospedada pelo aplicativo ngrok.

8. Para mudar o comportamento do aplicativo, substitua Case por Case: na linha 51 do index.js. Quando você salva o arquivo, o nodemon recarrega automaticamente o aplicativo com o código-fonte atualizado, e o Visual 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.

9. Dessa vez, em vez de clicar no link e esperar alguns segundos em um novo documento do Google, selecione a última solicitação HTTP registrada na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local e clique em Replay. Assim como da última vez, seu complemento do Google Workspace não responde porque está sendo depurado.

10. Quando você retoma a execução do depurador Visual Studio Code, é possível conferir na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local que o aplicativo gera uma resposta com a versão atualizada do card de visualização.

Python

1. No ambiente de desenvolvimento integrado Visual Studio Code instalado no ambiente local, faça o seguinte:

   1. Em uma nova janela, abra a pasta add-ons-samples/python/3p-resources/create_link_preview.

   2. Crie e ative um ambiente virtual para Python env:

      virtualenv env
      source env/bin/activate

   3. Instale todas as dependências do projeto usando pip no ambiente virtual:

      pip install -r requirements.txt

   4. Crie o arquivo .vscode/launch.json no diretório raiz e configure uma inicialização com o nome Debug Watch que aciona o aplicativo do módulo functions-framework na porta 9000 no modo de depuração no ambiente virtual 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. Adicione um ponto de interrupção que pausa o processamento da solicitação HTTP no arquivo main.py e inicie a execução e depuração com a configuração Debug Watch adicionada antes. O aplicativo agora está em execução e detectando solicitações HTTP na porta 9000.

      

      Figura 3. O aplicativo está em execução e detectando solicitações HTTP na porta 9000.

2. Inicie o aplicativo ngrok no seu ambiente local:

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   Substitua NGROK_STATIC_DOMAIN pelo domínio estático na sua conta ngrok. Agora, todas as solicitações são redirecionadas para o ambiente local e a porta usada pelo aplicativo.

   

   Figura 4. O terminal com o servidor ngrok em execução e redirecionamento.

3. Uma interface da Web também é iniciada no host local pelo aplicativo ngrok. É possível monitorar todas as atividades abrindo-o em um navegador.

   

   Figura 5. A interface da Web hospedada pelo aplicativo ngrok não mostra solicitações HTTP.

4. Teste seu complemento do Google Workspace com uma prévia do URL de um caso em um novo documento do Google com uma conta de teste:

   • Crie um documento Google.

     Criar um arquivo do Documentos Google

   • Digite o seguinte link e pressione enter:

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

   • Clique no link.

5. No Visual Studio Code no seu ambiente local, é possível ver que a execução é pausada no ponto de interrupção definido.

   

   Figura 6. A execução é pausada no ponto de interrupção definido.

6. Quando você retoma a execução do depurador Visual Studio Code antes que os complementos do Google Workspace expirem, o complemento mostra a visualização do link no Google Docs do cache.

7. É possível verificar os registros de solicitação e resposta HTTP na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local.

   

   Figura 7. A solicitação HTTP da interface da Web hospedada pelo aplicativo ngrok.

8. Para mudar o comportamento do aplicativo, substitua Case por Case: na linha 56 do arquivo main.py. Quando você salva o arquivo, o Visual 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.

9. Dessa vez, em vez de clicar no link e esperar alguns segundos em um novo documento do Google, selecione a última solicitação HTTP registrada na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local e clique em Replay. Assim como da última vez, seu complemento do Google Workspace não responde porque está sendo depurado.

10. Quando você retoma a execução do depurador Visual Studio Code, é possível conferir na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local que o aplicativo gera uma resposta com a versão atualizada do card de visualização.

Java

1. No ambiente de desenvolvimento integrado Visual Studio Code instalado no ambiente local, faça o seguinte:

   1. Em uma nova janela, abra a pasta add-ons-samples/java/3p-resources.

   2. Configure o projeto do Maven para executar o aplicativo CreateLinkPreview na porta 9000 localmente adicionando o plug-in de build do framework do Cloud Functions function-maven-plugin ao arquivo 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. Agora você pode iniciá-lo localmente no modo de depuração:

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

   4. Crie o arquivo .vscode/launch.json no diretório raiz e configure uma inicialização chamada Remote Debug Watch que se conecte ao aplicativo iniciado anteriormente na porta 8000:

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

   5. Adicione um ponto de interrupção que pausa o processamento da solicitação HTTP no arquivo CreateLinkPreview.java e inicie a anexação e depuração com a configuração Remote Debug Watch adicionada anteriormente. O aplicativo está em execução e detectando solicitações HTTP na porta 9000.

      

      Figura 3. O aplicativo está em execução e detectando solicitações HTTP na porta 9000.

2. Inicie o aplicativo ngrok no seu ambiente local:

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000

   Substitua NGROK_STATIC_DOMAIN pelo domínio estático na sua conta ngrok. Agora, todas as solicitações são redirecionadas para o ambiente local e a porta usada pelo aplicativo.

   

   Figura 4. O terminal com o servidor ngrok em execução e redirecionamento.

3. Uma interface da Web também é iniciada no host local pelo aplicativo ngrok. É possível monitorar todas as atividades abrindo-o em um navegador.

   

   Figura 5. A interface da Web hospedada pelo aplicativo ngrok não mostra solicitações HTTP.

4. Teste seu complemento do Google Workspace com uma prévia do URL de um caso em um novo documento do Google com uma conta de teste:

   • Crie um documento Google.

     Criar um arquivo do Documentos Google

   • Digite o seguinte link e pressione enter:

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

   • Clique no link.

5. No Visual Studio Code no seu ambiente local, é possível ver que a execução é pausada no ponto de interrupção definido.

   

   Figura 6. A execução é pausada no ponto de interrupção definido.

6. Quando você retoma a execução do depurador Visual Studio Code antes que os complementos do Google Workspace expirem, o complemento mostra a visualização do link no Google Docs do cache.

7. É possível verificar os registros de solicitação e resposta HTTP na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local.

   

   Figura 7. A solicitação HTTP da interface da Web hospedada pelo aplicativo ngrok.

8. Para mudar o comportamento do aplicativo, substitua Case por Case: na linha 78 do arquivo CreateLinkPreview.java, reinicie o processo mvnDebug e reinicie o Remote Debug Watch para reativar e reiniciar o processo de depuração.

9. Dessa vez, em vez de clicar no link e esperar alguns segundos em um novo documento do Google, selecione a última solicitação HTTP registrada na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local e clique em Replay. Assim como da última vez, seu complemento do Google Workspace não responde porque está sendo depurado.

10. Quando você retoma a execução do depurador Visual Studio Code, é possível conferir na interface da Web hospedada pelo aplicativo ngrok no seu ambiente local que o aplicativo gera uma resposta com a versão atualizada do card de visualização.

Depurar no ambiente remoto

Nesta seção, você interage com o complemento do Google Workspace que é executado em um ambiente remoto.

Figura 9. Fazer a depuração no ambiente remoto.

Pré-requisitos

• O complemento do Google Workspace é implantado e instalado.
• O aplicativo está em execução no ambiente remoto com o depurador ativado em uma determinada porta e é referenciado como REMOTE_DEBUG_PORT nas instruções deste guia.
• O ambiente local pode ssh para o ambiente remoto.
• Um ambiente de desenvolvimento integrado é configurado no seu ambiente local e pode depurar. Usamos o Visual Studio Code IDE e os recursos de depuração padrão neste guia para fins de ilustração.

Conectar os ambientes local e remoto

No ambiente local de onde você quer iniciar uma conexão de 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 ambiente local, faça o seguinte:

1. Em uma nova janela, abra o código-fonte do app.

2. Crie o arquivo .vscode/launch.json no diretório raiz e configure uma inicialização chamada Debug Remote que se conecte à 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.

3. Adicione um ponto de interrupção no código-fonte do app que pausa o processamento da solicitação HTTP e inicie a execução e depuração com a configuração Debug Remote adicionada antes.

   Interaja com o complemento do Google Workspace instalado. Seu complemento do Google Workspace não responde porque está sendo ativamente depurado no ambiente de desenvolvimento integrado Visual Studio Code.

Temas relacionados

• Saiba como consultar registros de erros.