Google Workspace アドオンをデバッグする

Google Workspace アドオンのデベロッパーは、変更をテストしたり、複雑な問題のトラブルシューティングを行うために、コードのデバッグが必要になることがあります。Google Workspace アドオンのデバッグは、アプリのアーキテクチャ、アプリの機能、アプリのデプロイ方法、設定に応じて、さまざまな方法で実行できます。

このページでは、ngrok を使用して Google Workspace アドオンをデバッグする方法について説明します。ngrok は、ローカル開発環境のテストに使用できる統合 Ingress プラットフォームです。このガイドでは、ローカル環境でコードの変更をテストし、リモート環境で問題のトラブルシューティングを行います。

注: Google Workspace アドオンが Google Apps Script で構築されている場合は、代わりに次を使用してください。

• デプロイメントをテストする
• デバッガとブレークポイントを使用する

ローカル開発環境からデバッグする

このセクションでは、ローカル環境で実行される Google Workspace アドオンを操作します。

図 1. ローカル開発環境でデバッグする。

前提条件

Node.js

• node と npm の最新バージョンがローカル環境にインストールされている。

• 最新バージョンの nodemon がローカル環境にインストールされており、自動再読み込みのために使用されます。

  npm install -g nodemon
  

• Google Cloud プロジェクト。クイックスタート ガイドの前提条件と環境を設定するに沿って操作してください。

• ローカル環境でデバッグする Google Workspace アドオンのコード。このガイドでは、説明のために GitHub リポジトリ googleworkspace/add-ons-samples のコードサンプル 3p-resources のプレビュー リンク機能を使用します。

• デバッグ可能なローカル環境でセットアップされた IDE。説明のため、このガイドでは Visual Studio Code IDE とデフォルトのデバッグ機能を使用しています。

• ngrok アカウント。

• ローカル環境に最新バージョンの gcloud がインストールされ、初期化されている。

Python

• 最新バージョンの python3 がローカル環境にインストールされている。
• ローカル環境に最新バージョンの pip と virtualenv がインストールされており、それぞれ Python パッケージと仮想環境の管理に使用されます。
• Google Cloud プロジェクト。クイックスタート ガイドの前提条件と環境を設定するに沿って操作してください。
• ローカル環境でデバッグする Google Workspace アドオンのコード。このガイドでは、説明のために GitHub リポジトリ googleworkspace/add-ons-samples のコードサンプル 3p-resources のプレビュー リンク機能を使用します。
• デバッグ可能なローカル環境でセットアップされた IDE。説明のため、このガイドでは Visual Studio Code IDE とデフォルトのデバッグ機能を使用しています。
• ngrok アカウント。
• ローカル環境に最新バージョンの gcloud がインストールされ、初期化されている。

Java

• ローカル環境にインストールされている Java SE 11's JDK の最新の安定版。
• 最新バージョンの Apache Maven がローカル環境にインストールされており、Java プロジェクトの管理に使用されます。
• Google Cloud プロジェクト。クイックスタート ガイドの前提条件と環境を設定するに沿って操作してください。
• ローカル環境でデバッグする Google Workspace アドオンのコード。このガイドでは、説明のために GitHub リポジトリ googleworkspace/add-ons-samples のコードサンプル 3p-resources のプレビュー リンク機能を使用します。
• デバッグ可能なローカル環境でセットアップされた IDE。説明のため、このガイドでは Visual Studio Code IDE とデフォルトのデバッグ機能を使用しています。
• ngrok アカウント。
• ローカル環境に最新バージョンの gcloud がインストールされ、初期化されている。

localhost サービスを一般公開する

Google Workspace アドオンがアクセスできるように、ローカル環境をインターネットに接続する必要があります。ngrok アプリケーションは、公開 URL に対する HTTP リクエストをローカル環境にリダイレクトするために使用されます。

1. ローカル環境のブラウザで、ngrok アカウントにログインします。
2. アプリケーションをインストールして、ローカル環境に authtoken を設定します。
3. ngrok アカウントで静的ドメインを作成します。このガイドの手順では NGROK_STATIC_DOMAIN と呼びます。

アドオン デプロイメントを作成してインストールする

1. すべての HTTP リクエストを静的ドメインに送信するように Google Workspace アドオンを構成します。デプロイ ファイルは次のようになります。

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

   NGROK_STATIC_DOMAIN は、ngrok アカウントの静的ドメインに置き換えます。

2. 使用する Google Cloud プロジェクトを設定します。

   gcloud config set project PROJECT_ID
   

3. アプリケーションのデフォルト認証情報に使用する新しいユーザー認証情報を取得します。

   gcloud auth application-default login
   

   PROJECT_ID は、アプリの Google Cloud プロジェクトのプロジェクト ID に置き換えます。

4. デプロイを作成します。

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

   DEPLOYMENT_FILE_PATH は、デプロイ ファイルのパスに置き換えます。

5. Deployment をインストールします。

   gcloud workspace-add-ons deployments install manageSupportCases
   

図 2. Google Workspace アドオンは、すべての HTTP リクエストを静的ドメインに送信します。ngrok 公開サービスは、Google Workspace アドオンとローカルで実行されるアプリケーション コードとの間のブリッジとして機能します。

Google Workspace アドオンをテストする

Google Workspace アドオンは、ローカルでデプロイ、テスト、デバッグ、自動再読み込みできます。

注: Google Workspace アドオンは、例の Cloud Functions フレームワークを使用して実行されます。

Node.js

1. ローカル環境にインストールされている Visual Studio Code IDE から、次の操作を行います。

   1. 新しいウィンドウで、add-ons-samples/node/3p-resources フォルダを開きます。

   2. package.json ファイルに 1 つの依存関係と 2 つのスクリプトを追加して、ローカル実行と自動再読み込みのデバッグ用にアプリを構成します。

      {
          ...
          "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. ルート ディレクトリからアプリケーションをインストールします。

      npm install
      

   4. ルート ディレクトリに .vscode/launch.json ファイルを作成して、スクリプト debug-watch をトリガーする Debug Watch という名前の起動を作成して構成します。

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

   5. index.js ファイルに HTTP リクエストの処理を一時停止するブレークポイントを追加し、以前に追加した Debug Watch 構成で実行とデバッグを開始します。これでアプリケーションが実行され、ポート 9000 で HTTP リクエストをリッスンします。

      

      図 3. アプリケーションは実行されており、ポート 9000 で HTTP リクエストをリッスンしています。

2. ローカル環境で ngrok アプリケーションを起動します。

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000
   

   NGROK_STATIC_DOMAIN は、ngrok アカウントの静的ドメインに置き換えます。これで、すべてのリクエストがローカル環境とアプリケーションで使用されるポートにリダイレクトされます。

   

   図 4. ngrok サーバーが実行され、リダイレクトされているターミナル。

3. ウェブ インターフェースも ngrok アプリケーションによって localhost で起動され、ブラウザで開いてすべてのアクティビティをモニタリングできます。

   

   図 5. ngrok アプリケーションがホストするウェブ インターフェース。HTTP リクエストは表示されません。

4. テスター アカウントを使用して、新しい Google ドキュメントでケースの URL をプレビューして、Google Workspace アドオンをテストします。

   • 新しい Google ドキュメントを作成します。

     新しい Google ドキュメントを作成する

   • 次のリンクを入力して、enter キーを押します。

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

   • そこにあるリンクをクリックします。

5. ローカル環境の Visual Studio Code では、設定されたブレークポイントで実行が一時停止していることを確認できます。

   

   図 6. 設定されたブレークポイントで実行が一時停止します。

6. Google Workspace アドオンがタイムアウトする前に Visual Studio Code のデバッガから実行を再開すると、Google Workspace アドオンはキャッシュにある Google ドキュメントにリンク プレビューを表示します。

7. HTTP リクエストとレスポンスのログは、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースから確認できます。

   

   図 7. ngrok アプリケーションがホストするウェブ インターフェースからの HTTP リクエスト。

8. アプリケーションの動作を変更するには、Case を、index.js の Case: インライン 51 に置き換えます。ファイルを保存すると、nodemon は更新されたソースコードでアプリを自動的に再読み込みしますが、Visual Studio Code はデバッグモードのままです。

   

   図 8. コードの変更が読み込まれ、ポート 9000 でアプリケーションが実行され、HTTP リクエストをリッスンします。

9. 今回は、新しい Google ドキュメントでリンクをクリックして数秒待つ代わりに、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースで最後にログに記録された HTTP リクエストを選択し、[Replay] をクリックします。前回と同様、デバッグがアクティブであるため、Google Workspace アドオンは応答しません。

10. Visual Studio Code のデバッガから実行を再開すると、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースから、アプリケーションが更新バージョンのプレビュー カードを使用してレスポンスを生成したことを確認できます。

Python

1. ローカル環境にインストールされている Visual Studio Code IDE から、次の操作を行います。

   1. 新しいウィンドウで、add-ons-samples/python/3p-resources/create_link_preview フォルダを開きます。

   2. Python env 用の新しい仮想環境を作成し、有効にします。

      virtualenv env
      source env/bin/activate
      

   3. 仮想環境で pip を使用して、すべてのプロジェクトの依存関係をインストールします。

      pip install -r requirements.txt
      

   4. ルート ディレクトリに .vscode/launch.json ファイルを作成し、Debug Watch という名前の起動を構成します。これにより、仮想環境 env のデバッグモードのポート 9000 で、モジュール functions-framework からアプリがトリガーされます。

      {
          "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. main.py ファイルに HTTP リクエストの処理を一時停止するブレークポイントを追加し、以前に追加した Debug Watch 構成で実行とデバッグを開始します。これでアプリケーションが実行され、ポート 9000 で HTTP リクエストをリッスンします。

      

      図 3. アプリケーションは実行されており、ポート 9000 で HTTP リクエストをリッスンしています。

2. ローカル環境で ngrok アプリケーションを起動します。

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000
   

   NGROK_STATIC_DOMAIN は、ngrok アカウントの静的ドメインに置き換えます。これで、すべてのリクエストがローカル環境とアプリケーションで使用されるポートにリダイレクトされます。

   

   図 4. ngrok サーバーが実行され、リダイレクトされているターミナル。

3. ウェブ インターフェースも ngrok アプリケーションによって localhost で起動され、ブラウザで開いてすべてのアクティビティをモニタリングできます。

   

   図 5. ngrok アプリケーションがホストするウェブ インターフェース。HTTP リクエストは表示されません。

4. テスター アカウントを使用して、新しい Google ドキュメントでケースの URL をプレビューして、Google Workspace アドオンをテストします。

   • 新しい Google ドキュメントを作成します。

     新しい Google ドキュメントを作成する

   • 次のリンクを入力して、enter キーを押します。

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

   • そこにあるリンクをクリックします。

5. ローカル環境の Visual Studio Code では、設定されたブレークポイントで実行が一時停止していることを確認できます。

   

   図 6. 設定されたブレークポイントで実行が一時停止します。

6. Google Workspace アドオンがタイムアウトする前に Visual Studio Code のデバッガから実行を再開すると、Google Workspace アドオンはキャッシュにある Google ドキュメントにリンク プレビューを表示します。

7. HTTP リクエストとレスポンスのログは、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースから確認できます。

   

   図 7. ngrok アプリケーションがホストするウェブ インターフェースからの HTTP リクエスト。

8. アプリケーションの動作を変更するには、Case を、main.py ファイルの Case: インライン 56 に置き換えます。ファイルを保存すると、Visual Studio Code はアプリケーションを自動的に更新済みのソースコードで再読み込みし、デバッグモードのままです。

   

   図 8. コードの変更が読み込まれ、ポート 9000 でアプリケーションが実行され、HTTP リクエストをリッスンします。

9. 今回は、新しい Google ドキュメントでリンクをクリックして数秒待つ代わりに、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースで最後にログに記録された HTTP リクエストを選択し、[Replay] をクリックします。前回と同様、デバッグがアクティブであるため、Google Workspace アドオンは応答しません。

10. Visual Studio Code のデバッガから実行を再開すると、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースから、アプリケーションが更新バージョンのプレビュー カードを使用してレスポンスを生成したことを確認できます。

Java

1. ローカル環境にインストールされている Visual Studio Code IDE から、次の操作を行います。

   1. 新しいウィンドウで、add-ons-samples/java/3p-resources フォルダを開きます。

   2. pom.xml ファイルに Cloud Functions Framework ビルド プラグイン function-maven-plugin を追加して、ポート 9000 でアプリケーション CreateLinkPreview をローカルで実行するように Maven プロジェクトを構成します。

      ...
      <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. これで、ローカルでデバッグモードで起動できるようになりました。

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

   4. ルート ディレクトリにファイル .vscode/launch.json を作成し、ポート 8000 で以前に起動したアプリケーションに接続する Remote Debug Watch という名前の起動を構成します。

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

   5. CreateLinkPreview.java ファイルに HTTP リクエストの処理を一時停止するブレークポイントを追加し、以前に追加した Remote Debug Watch 構成でアタッチとデバッグを開始します。これでアプリケーションが実行され、ポート 9000 で HTTP リクエストをリッスンします。

      

      図 3. アプリケーションはポート 9000 で実行され、HTTP リクエストをリッスンしています。

2. ローカル環境で ngrok アプリケーションを起動します。

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000
   

   NGROK_STATIC_DOMAIN は、ngrok アカウントの静的ドメインに置き換えます。これで、すべてのリクエストがローカル環境とアプリケーションで使用されるポートにリダイレクトされます。

   

   図 4. ngrok サーバーが実行され、リダイレクトされているターミナル。

3. ウェブ インターフェースも ngrok アプリケーションによって localhost で起動され、ブラウザで開いてすべてのアクティビティをモニタリングできます。

   

   図 5. ngrok アプリケーションがホストするウェブ インターフェース。HTTP リクエストは表示されません。

4. テスター アカウントを使用して、新しい Google ドキュメントでケースの URL をプレビューして、Google Workspace アドオンをテストします。

   • 新しい Google ドキュメントを作成します。

     新しい Google ドキュメントを作成する

   • 次のリンクを入力して、enter キーを押します。

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

   • そこにあるリンクをクリックします。

5. ローカル環境の Visual Studio Code では、設定されたブレークポイントで実行が一時停止していることを確認できます。

   

   図 6. 設定されたブレークポイントで実行が一時停止します。

6. Google Workspace アドオンがタイムアウトする前に Visual Studio Code のデバッガから実行を再開すると、Google Workspace アドオンはキャッシュにある Google ドキュメントにリンク プレビューを表示します。

7. HTTP リクエストとレスポンスのログは、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースから確認できます。

   

   図 7. ngrok アプリケーションがホストするウェブ インターフェースからの HTTP リクエスト。

8. アプリの動作を変更するには、Case を CreateLinkPreview.java ファイルの Case: インライン 78 に置き換え、mvnDebug プロセスを再起動し、Remote Debug Watch を再起動してデバッグを再接続して再起動します。

9. 今回は、新しい Google ドキュメントでリンクをクリックして数秒待つ代わりに、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースで最後にログに記録された HTTP リクエストを選択し、[Replay] をクリックします。前回と同様、デバッグがアクティブであるため、Google Workspace アドオンは応答しません。

10. Visual Studio Code のデバッガから実行を再開すると、ローカル環境の ngrok アプリケーションによってホストされているウェブ インターフェースから、アプリケーションが更新バージョンのプレビュー カードを使用してレスポンスを生成したことを確認できます。

リモート環境からデバッグする

このセクションでは、リモート環境で実行される Google Workspace アドオンを操作します。

図 9. リモート環境からデバッグする。

前提条件

• Google Workspace アドオンがデプロイされ、インストールされている。
• 特定のポートでデバッガを有効にして、リモート環境で実行されるアプリケーションを、このガイドの手順では REMOTE_DEBUG_PORT と表記します。
• ローカル環境からリモート環境に ssh できます。
• デバッグ可能なローカル環境でセットアップされた IDE。このガイドでは、説明のために Visual Studio Code IDE とそのデフォルトのデバッグ機能を使用しています。

ローカル環境とリモート環境を接続する

デバッグ クライアント接続を開始するローカル環境で、SSH トンネルを設定します。

ssh -L LOCAL_DEBUG_PORT:localhost:REMOTE_DEBUG_PORT REMOTE_USERNAME@REMOTE_ADDRESS

次のように置き換えます。

• LOCAL_DEBUG_PORT: ローカル環境のデバッグポート。
• REMOTE_USERNAME: リモート環境のユーザー名。
• REMOTE_ADDRESS: リモート環境のアドレス。
• REMOTE_DEBUG_PORT: リモート環境のデバッグポート。

これで、ローカル環境のデバッグポートがリモート環境のデバッグポートにリンクされました。

デバッグを開始する

ローカル環境にインストールされている Visual Studio Code IDE から、次の操作を行います。

1. 新しいウィンドウで、アプリのソースコードを開きます。

2. ルート ディレクトリに .vscode/launch.json ファイルを作成し、ローカル環境のデバッグポートに接続する Debug Remote という名前の起動を構成します。

   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
       }]
   }
   

   LOCAL_DEBUG_PORT は、ローカル環境のデバッグポートに置き換えます。

3. アプリのソースコードに、HTTP リクエストの処理を一時停止するブレークポイントを追加し、以前に追加した Debug Remote 構成で実行とデバッグを開始します。

インストールした Google Workspace アドオンを操作します。Visual Studio Code IDE でアクティブにデバッグされているため、Google Workspace アドオンは応答しません。

関連トピック

エラーログをクエリする方法を学習する。