Men-debug Add-on Google Workspace

Sebagai developer Add-on Google Workspace, Anda mungkin perlu men-debug kode untuk menguji perubahan atau memecahkan masalah yang kompleks. Proses debug Add-on Google Workspace dapat dilakukan dengan berbagai cara, bergantung pada arsitektur aplikasi, fungsi aplikasi, cara aplikasi di-deploy, dan preferensi Anda.

Halaman ini menjelaskan cara men-debug Add-on Google Workspace menggunakan ngrok, yang merupakan platform ingress terpadu yang dapat Anda gunakan untuk menguji lingkungan pengembangan lokal. Dalam panduan ini, Anda menguji perubahan kode di lingkungan lokal dan memecahkan masalah di lingkungan jarak jauh.

Catatan: Jika Add-on Google Workspace Anda dibuat dengan Google Apps Script, gunakan kode berikut:

• Menguji deployment
• Menggunakan debugger dan titik henti sementara

Men-debug dari lingkungan pengembangan lokal

Di bagian ini, Anda akan berinteraksi dengan Add-on Google Workspace yang dijalankan di lingkungan lokal Anda.

Gambar 1. Men-debug di lingkungan pengembangan lokal.

Prasyarat

Node.js

• Versi terbaru node dan npm terinstal di lingkungan lokal Anda.

• Versi terbaru nodemon yang diinstal di lingkungan lokal Anda, yang digunakan untuk tujuan pemuatan ulang otomatis:

  npm install -g nodemon
  

• Project Google Cloud. Anda dapat mengikuti bagian Prasyarat, dan Menyiapkan lingkungan di Panduan memulai.

• Kode Add-on Google Workspace untuk melakukan debug di lingkungan lokal Anda. Kami menggunakan fitur link pratinjau dari contoh kode 3p-resources dari repositori GitHub googleworkspace/add-ons-samples dalam panduan ini untuk tujuan ilustrasi.

• IDE yang disiapkan di lingkungan lokal Anda yang dapat melakukan debug. Kami menggunakan Visual Studio Code IDE dan fitur proses debug defaultnya dalam panduan ini untuk tujuan ilustrasi.

• Akun ngrok.

• Versi terbaru gcloud diinstal dan diinisialisasi di lingkungan lokal Anda.

Python

• Versi terbaru python3 yang diinstal di lingkungan lokal Anda.
• pip dan virtualenv versi terbaru yang diinstal di lingkungan lokal Anda, masing-masing digunakan untuk mengelola paket Python dan lingkungan virtual.
• Project Google Cloud. Anda dapat mengikuti bagian Prasyarat, dan Menyiapkan lingkungan di Panduan memulai.
• Kode Add-on Google Workspace untuk melakukan debug di lingkungan lokal Anda. Kami menggunakan fitur link pratinjau dari contoh kode 3p-resources dari repositori GitHub googleworkspace/add-ons-samples dalam panduan ini untuk tujuan ilustrasi.
• IDE yang disiapkan di lingkungan lokal Anda yang dapat melakukan debug. Kami menggunakan Visual Studio Code IDE dan fitur proses debug defaultnya dalam panduan ini untuk tujuan ilustrasi.
• Akun ngrok.
• Versi terbaru gcloud diinstal dan diinisialisasi di lingkungan lokal Anda.

Java

• Versi stabil terbaru Java SE 11's JDK yang diinstal di lingkungan lokal Anda.
• Versi terbaru Apache Maven yang diinstal di lingkungan lokal Anda, digunakan untuk mengelola project Java.
• Project Google Cloud. Anda dapat mengikuti bagian Prasyarat, dan Menyiapkan lingkungan di Panduan memulai.
• Kode Add-on Google Workspace untuk melakukan debug di lingkungan lokal Anda. Kami menggunakan fitur link pratinjau dari contoh kode 3p-resources dari repositori GitHub googleworkspace/add-ons-samples dalam panduan ini untuk tujuan ilustrasi.
• IDE yang disiapkan di lingkungan lokal Anda yang dapat melakukan debug. Kami menggunakan Visual Studio Code IDE dan fitur proses debug defaultnya dalam panduan ini untuk tujuan ilustrasi.
• Akun ngrok.
• Versi terbaru gcloud diinstal dan diinisialisasi di lingkungan lokal Anda.

Membuat layanan localhost tersedia untuk publik

Anda harus menghubungkan lingkungan lokal ke internet agar Add-on Google Workspace dapat mengaksesnya. Aplikasi ngrok digunakan untuk mengalihkan permintaan HTTP yang dibuat ke URL publik ke lingkungan lokal Anda.

1. Pada browser di lingkungan lokal Anda, login ke akun ngrok Anda.
2. Instal aplikasi dan siapkan authtoken di lingkungan lokal Anda.
3. Buat domain statis di akun ngrok, dengan referensi sebagai NGROK_STATIC_DOMAIN dalam petunjuk panduan ini.

Membuat dan menginstal deployment add-on

1. Konfigurasikan Add-on Google Workspace untuk mengirim semua permintaan HTTP-nya ke domain statis Anda. File deployment Anda akan terlihat seperti berikut:

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

   Ganti NGROK_STATIC_DOMAIN dengan domain statis di akun ngrok Anda.

2. Tetapkan project Google Cloud yang akan digunakan:

   gcloud config set project PROJECT_ID
   

3. Dapatkan kredensial pengguna baru yang akan digunakan untuk Kredensial Default Aplikasi:

   gcloud auth application-default login
   

   Ganti PROJECT_ID dengan project ID untuk project Google Cloud aplikasi.

4. Buat deployment:

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

   Ganti DEPLOYMENT_FILE_PATH dengan jalur file deployment Anda.

5. Instal deployment:

   gcloud workspace-add-ons deployments install manageSupportCases
   

Gambar 2. Add-on Google Workspace mengirimkan semua permintaan HTTP-nya ke domain statis. Layanan publik ngrok berfungsi sebagai jembatan antara Add-on Google Workspace dan kode aplikasi yang dieksekusi secara lokal.

Menguji Add-on Google Workspace

Anda dapat men-deploy secara lokal, menguji, men-debug, dan memuat ulang Add-on Google Workspace secara otomatis.

Catatan: Add-on Google Workspace dijalankan dengan Framework Cloud Functions pada contoh.

Node.js

1. Dari Visual Studio Code IDE yang diinstal di lingkungan lokal Anda, lakukan hal berikut:

   1. Di jendela baru, buka folder add-ons-samples/node/3p-resources.

   2. Konfigurasikan aplikasi untuk dijalankan secara lokal dan muat ulang secara otomatis debug dengan menambahkan satu dependensi dan dua skrip dalam 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"
          }
          ...
      }
      

   3. Dari direktori root, instal aplikasi:

      npm install
      

   4. Buat dan konfigurasi peluncuran bernama Debug Watch yang memicu skrip debug-watch dengan membuat file .vscode/launch.json di direktori root:

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

   5. Tambahkan titik henti sementara yang menjeda pemrosesan permintaan HTTP dalam file index.js, dan mulai jalankan dan lakukan proses debug dengan konfigurasi Debug Watch yang ditambahkan sebelumnya. Aplikasi tersebut kini berjalan dan memproses permintaan HTTP pada port 9000.

      

      Gambar 3. Aplikasi sedang berjalan dan memproses permintaan HTTP pada port 9000.

2. Luncurkan aplikasi ngrok di lingkungan lokal Anda:

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000
   

   Ganti NGROK_STATIC_DOMAIN dengan domain statis di akun ngrok Anda. Semua permintaan kini dialihkan ke lingkungan lokal Anda dan port yang digunakan oleh aplikasi.

   

   Gambar 4. Terminal dengan server ngrok yang berjalan dan melakukan pengalihan.

3. Antarmuka web juga dimulai di localhost oleh aplikasi ngrok. Anda dapat memantau semua aktivitas dengan membukanya di browser.

   

   Gambar 5. Antarmuka web yang dihosting oleh aplikasi ngrok tidak menampilkan permintaan HTTP.

4. Uji Add-on Google Workspace Anda dengan melihat pratinjau URL kasus di Dokumen Google baru dengan akun penguji:

   • Buat Dokumen Google baru.

     Membuat Dokumen Google baru

   • Ketik link berikut, lalu tekan enter:

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

   • Klik linknya.

5. Pada Visual Studio Code di lingkungan lokal, Anda dapat melihat bahwa eksekusi dijeda pada titik henti sementara yang ditetapkan.

   

   Gambar 6. Eksekusi dijeda di titik henti sementara yang telah ditetapkan.

6. Saat Anda melanjutkan eksekusi dari debugger Visual Studio Code sebelum Add-on Google Workspace berakhir, Add-on Google Workspace akan menampilkan pratinjau link dari cache di Dokumen Google.

7. Anda dapat memeriksa log permintaan dan respons HTTP dari antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal Anda.

   

   Gambar 7. Permintaan HTTP dari antarmuka web yang dihosting oleh aplikasi ngrok.

8. Untuk mengubah perilaku aplikasi, ganti Case dengan Case: inline 51 dari index.js. Saat Anda menyimpan file ini, nodemon akan otomatis memuat ulang aplikasi dengan kode sumber yang diperbarui dan Visual Studio Code tetap berada dalam mode debug.

   

   Gambar 8. Aplikasi sedang berjalan dan memproses permintaan HTTP pada port 9000 dengan perubahan kode dimuat.

9. Kali ini, daripada mengklik link dan menunggu beberapa detik di Dokumen Google baru, Anda dapat memilih permintaan HTTP terakhir yang dicatat dalam log di antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal Anda, lalu klik Replay. Sama seperti terakhir kali, Add-on Google Workspace Anda tidak membalas karena sedang di-debug secara aktif.

10. Saat melanjutkan eksekusi dari debugger Visual Studio Code, Anda dapat melihat dari antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal bahwa aplikasi menghasilkan respons dengan versi kartu pratinjau yang telah diupdate.

Python

1. Dari Visual Studio Code IDE yang diinstal di lingkungan lokal Anda, lakukan hal berikut:

   1. Di jendela baru, buka folder add-ons-samples/python/3p-resources/create_link_preview.

   2. Buat lingkungan virtual baru untuk Python env dan aktifkan:

      virtualenv env
      source env/bin/activate
      

   3. Instal semua dependensi project menggunakan pip di lingkungan virtual:

      pip install -r requirements.txt
      

   4. Buat file .vscode/launch.json di direktori utama dan konfigurasikan peluncuran bernama Debug Watch yang memicu aplikasi dari modul functions-framework pada port 9000 dalam mode debug di lingkungan 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. Tambahkan titik henti sementara yang menjeda pemrosesan permintaan HTTP dalam file main.py, dan mulai jalankan dan lakukan proses debug dengan konfigurasi Debug Watch yang ditambahkan sebelumnya. Aplikasi tersebut kini berjalan dan memproses permintaan HTTP pada port 9000.

      

      Gambar 3. Aplikasi sedang berjalan dan memproses permintaan HTTP pada port 9000.

2. Luncurkan aplikasi ngrok di lingkungan lokal Anda:

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000
   

   Ganti NGROK_STATIC_DOMAIN dengan domain statis di akun ngrok Anda. Semua permintaan kini dialihkan ke lingkungan lokal Anda dan port yang digunakan oleh aplikasi.

   

   Gambar 4. Terminal dengan server ngrok yang berjalan dan melakukan pengalihan.

3. Antarmuka web juga dimulai di localhost oleh aplikasi ngrok. Anda dapat memantau semua aktivitas dengan membukanya di browser.

   

   Gambar 5. Antarmuka web yang dihosting oleh aplikasi ngrok tidak menampilkan permintaan HTTP.

4. Uji Add-on Google Workspace Anda dengan melihat pratinjau URL kasus di Dokumen Google baru dengan akun penguji:

   • Buat Dokumen Google baru.

     Membuat Dokumen Google baru

   • Ketik link berikut, lalu tekan enter:

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

   • Klik linknya.

5. Pada Visual Studio Code di lingkungan lokal, Anda dapat melihat bahwa eksekusi dijeda pada titik henti sementara yang ditetapkan.

   

   Gambar 6. Eksekusi dijeda di titik henti sementara yang telah ditetapkan.

6. Saat Anda melanjutkan eksekusi dari debugger Visual Studio Code sebelum Add-on Google Workspace berakhir, Add-on Google Workspace akan menampilkan pratinjau link dari cache di Dokumen Google.

7. Anda dapat memeriksa log permintaan dan respons HTTP dari antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal Anda.

   

   Gambar 7. Permintaan HTTP dari antarmuka web yang dihosting oleh aplikasi ngrok.

8. Untuk mengubah perilaku aplikasi, ganti Case dengan Case: inline 56 dari file main.py. Jika Anda menyimpan file ini, Visual Studio Code akan otomatis memuat ulang aplikasi dengan kode sumber yang diperbarui dan tetap dalam mode debug.

   

   Gambar 8. Aplikasi sedang berjalan dan memproses permintaan HTTP pada port 9000 dengan perubahan kode dimuat.

9. Kali ini, daripada mengklik link dan menunggu beberapa detik di Dokumen Google baru, Anda dapat memilih permintaan HTTP terakhir yang dicatat dalam log di antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal Anda, lalu klik Replay. Sama seperti terakhir kali, Add-on Google Workspace Anda tidak membalas karena sedang di-debug secara aktif.

10. Saat melanjutkan eksekusi dari debugger Visual Studio Code, Anda dapat melihat dari antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal bahwa aplikasi menghasilkan respons dengan versi kartu pratinjau yang telah diupdate.

Java

1. Dari Visual Studio Code IDE yang diinstal di lingkungan lokal Anda, lakukan hal berikut:

   1. Di jendela baru, buka folder add-ons-samples/java/3p-resources.

   2. Konfigurasikan project Maven untuk menjalankan aplikasi CreateLinkPreview pada port 9000 secara lokal dengan menambahkan plugin build Cloud Functions Framework function-maven-plugin dalam file 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. Sekarang, Anda dapat meluncurkannya secara lokal dalam mode debug:

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

   4. Buat file .vscode/launch.json di direktori utama dan konfigurasikan peluncuran bernama Remote Debug Watch yang dilampirkan ke aplikasi yang sebelumnya diluncurkan dengan port 8000:

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

   5. Tambahkan titik henti sementara yang menjeda pemrosesan permintaan HTTP dalam file CreateLinkPreview.java, dan mulai melampirkan dan melakukan proses debug dengan konfigurasi Remote Debug Watch yang ditambahkan sebelumnya. Aplikasi tersebut sedang berjalan dan memproses permintaan HTTP di port 9000.

      

      Gambar 3. Aplikasi sedang berjalan dan memproses permintaan HTTP pada port 9000.

2. Luncurkan aplikasi ngrok di lingkungan lokal Anda:

   ngrok http --domain=NGROK_STATIC_DOMAIN 9000
   

   Ganti NGROK_STATIC_DOMAIN dengan domain statis di akun ngrok Anda. Semua permintaan kini dialihkan ke lingkungan lokal Anda dan port yang digunakan oleh aplikasi.

   

   Gambar 4. Terminal dengan server ngrok yang berjalan dan melakukan pengalihan.

3. Antarmuka web juga dimulai di localhost oleh aplikasi ngrok. Anda dapat memantau semua aktivitas dengan membukanya di browser.

   

   Gambar 5. Antarmuka web yang dihosting oleh aplikasi ngrok tidak menampilkan permintaan HTTP.

4. Uji Add-on Google Workspace Anda dengan melihat pratinjau URL kasus di Dokumen Google baru dengan akun penguji:

   • Buat Dokumen Google baru.

     Membuat Dokumen Google baru

   • Ketik link berikut, lalu tekan enter:

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

   • Klik linknya.

5. Pada Visual Studio Code di lingkungan lokal, Anda dapat melihat bahwa eksekusi dijeda pada titik henti sementara yang ditetapkan.

   

   Gambar 6. Eksekusi dijeda di titik henti sementara yang telah ditetapkan.

6. Saat Anda melanjutkan eksekusi dari debugger Visual Studio Code sebelum Add-on Google Workspace berakhir, Add-on Google Workspace akan menampilkan pratinjau link dari cache di Dokumen Google.

7. Anda dapat memeriksa log permintaan dan respons HTTP dari antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal Anda.

   

   Gambar 7. Permintaan HTTP dari antarmuka web yang dihosting oleh aplikasi ngrok.

8. Untuk mengubah perilaku aplikasi, ganti Case dengan Case: inline 78 dari file CreateLinkPreview.java, mulai ulang proses mvnDebug, dan luncurkan kembali Remote Debug Watch untuk melampirkan kembali dan memulai ulang proses debug.

9. Kali ini, daripada mengklik link dan menunggu beberapa detik di Dokumen Google baru, Anda dapat memilih permintaan HTTP terakhir yang dicatat dalam log di antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal Anda, lalu klik Replay. Sama seperti terakhir kali, Add-on Google Workspace Anda tidak membalas karena sedang di-debug secara aktif.

10. Saat melanjutkan eksekusi dari debugger Visual Studio Code, Anda dapat melihat dari antarmuka web yang dihosting oleh aplikasi ngrok di lingkungan lokal bahwa aplikasi menghasilkan respons dengan versi kartu pratinjau yang telah diupdate.

Men-debug dari lingkungan jarak jauh

Di bagian ini, Anda akan berinteraksi dengan Add-on Google Workspace yang dijalankan di lingkungan jarak jauh.

Gambar 9. Men-debug dari lingkungan jarak jauh.

Prasyarat

• Add-on Google Workspace Anda di-deploy dan diinstal.
• Aplikasi Anda yang berjalan di lingkungan jarak jauh dengan debugger yang diaktifkan pada port tertentu disebut sebagai REMOTE_DEBUG_PORT dalam petunjuk panduan ini.
• Lingkungan lokal Anda dapat ssh ke lingkungan jarak jauh.
• IDE yang disiapkan di lingkungan lokal Anda yang dapat melakukan debug. Kami menggunakan Visual Studio Code IDE dan fitur proses debug defaultnya dalam panduan ini untuk tujuan ilustrasi.

Menghubungkan lingkungan lokal dan jarak jauh

Di lingkungan lokal tempat Anda ingin memulai koneksi klien debug, siapkan tunnel SSH:

ssh -L LOCAL_DEBUG_PORT:localhost:REMOTE_DEBUG_PORT REMOTE_USERNAME@REMOTE_ADDRESS

Ganti kode berikut:

• LOCAL_DEBUG_PORT: Port debug di lingkungan lokal Anda.
• REMOTE_USERNAME: Nama pengguna di lingkungan jarak jauh Anda.
• REMOTE_ADDRESS: Alamat lingkungan jarak jauh Anda.
• REMOTE_DEBUG_PORT: Port debug di lingkungan jarak jauh Anda.

Port debug di lingkungan lokal Anda kini ditautkan ke port debug di lingkungan jarak jauh.

Memulai proses debug

Dari Visual Studio Code IDE yang diinstal di lingkungan lokal Anda, lakukan hal berikut:

1. Di jendela baru, buka kode sumber aplikasi Anda.

2. Buat file .vscode/launch.json di direktori utama dan konfigurasikan peluncuran bernama Debug Remote yang dilampirkan ke port debug di lingkungan lokal Anda:

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

   Ganti LOCAL_DEBUG_PORT dengan port debug di lingkungan lokal Anda.

3. Tambahkan titik henti sementara dalam kode sumber aplikasi Anda yang menjeda pemrosesan permintaan HTTP, dan mulai jalankan dan proses debug dengan konfigurasi Debug Remote yang ditambahkan sebelumnya.

Lakukan interaksi dengan Add-on Google Workspace yang terinstal. Add-on Google Workspace Anda tidak dibalas karena sedang di-debug secara aktif di IDE Visual Studio Code.

Topik terkait

Pelajari cara mengkueri log error.