Menjeda dan melanjutkan alur kerja menggunakan callback dan Google Spreadsheet

Google Spreadsheet adalah solusi spreadsheet berbasis cloud yang mendukung kolaborasi real-time dan menyediakan alat untuk memvisualisasikan, memproses, dan mengomunikasikan data.

Tutorial ini menunjukkan cara membuat dan men-deploy alur kerja yang membuat endpoint panggilan balik (atau webhook), menyimpan URL panggilan balik ke Google Spreadsheet, menjeda eksekusi, lalu menunggu persetujuan manusia melalui spreadsheet Spreadsheet untuk memulai ulang alur kerja. Pelajari lebih lanjut cara menggunakan panggilan balik.

Membuat folder baru di Google Drive

Buat folder baru di Google Drive. Folder ini digunakan untuk menyimpan spreadsheet Anda. Dengan menyiapkan izin untuk folder bersama, alur kerja Anda diizinkan untuk menulis ke spreadsheet.

1. Buka drive.google.com.
2. Klik Baru > Folder baru.
3. Masukkan nama folder.
4. Klik Buat.
5. Klik kanan folder baru Anda, lalu pilih Bagikan.

6. Tambahkan alamat email untuk akun layanan default Compute Engine.

   Tindakan ini akan memberi akun layanan akses ke folder. Saat Anda mengaitkan akun layanan dengan alur kerja, alur kerja akan memiliki akses edit ke file apa pun di folder. Pelajari lebih lanjut cara berbagi file, folder, dan drive.

7. Pilih peran Editor.

8. Hapus centang pada kotak Beri tahu orang.

9. Klik Bagikan.

Membuat spreadsheet menggunakan Google Spreadsheet

Saat Anda membuat spreadsheet melalui Google Spreadsheet, spreadsheet tersebut akan disimpan di Google Drive. Secara default, spreadsheet disimpan ke folder root Anda di Drive. Tidak ada opsi untuk membuat spreadsheet secara langsung dalam folder tertentu menggunakan Google Spreadsheet API. Namun, ada alternatif lain, termasuk memindahkan spreadsheet ke folder tertentu setelah Anda membuatnya, seperti yang dilakukan dalam contoh ini. Untuk mengetahui informasi selengkapnya, lihat Bekerja dengan folder Google Drive.

1. Buka sheets.google.com.

2. Klik Baru .

   Tindakan ini akan membuat dan membuka spreadsheet baru Anda. Setiap spreadsheet memiliki nilai spreadsheetId unik, yang berisi huruf, angka, tanda hubung, atau garis bawah. Anda dapat menemukan ID spreadsheet di URL Google Spreadsheet:

   https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0

3. Catat ID ini karena akan diperlukan saat Anda membuat alur kerja.

4. Tambahkan judul kolom agar sesuai dengan contoh berikut:

   

   Perhatikan bahwa nilai di kolom G, Disetujui?, digunakan untuk memulai callback dalam alur kerja.

5. Pindahkan spreadsheet ke folder Google Drive yang Anda buat sebelumnya:

   1. Di spreadsheet, pilih File > Pindahkan.
   2. Buka folder yang Anda buat.
   3. Klik Pindahkan.

Anda juga dapat menggunakan konektor Google Sheets API untuk membuat spreadsheet. Perhatikan bahwa saat menggunakan konektor, spreadsheetId dapat diambil dari hasil resp. Contoh:

- create_spreadsheet:
    call: googleapis.sheets.v4.spreadsheets.create
    args:
      body:
      connector_params:
        scopes: ${driveScope}
    result: resp
- assign_sheet_id:
    assign:
      - sheetId: ${resp.spreadsheetId}

Memperluas Google Spreadsheet menggunakan Apps Script

Apps Script memungkinkan Anda membuat, membaca, dan mengedit Google Spreadsheet secara terprogram. Sebagian besar skrip yang dirancang untuk Spreadsheet memanipulasi array untuk berinteraksi dengan sel, baris, dan kolom dalam spreadsheet. Untuk pengantar penggunaan Apps Script dengan Google Spreadsheet, lihat Panduan memulai fungsi kustom.

Catatan: Jika Anda login ke beberapa Akun Google secara bersamaan, Anda mungkin mengalami masalah saat mengakses Apps Script. Multi-login, atau login ke beberapa Akun Google sekaligus, tidak didukung untuk Apps Script. Untuk mengetahui informasi selengkapnya, lihat Memperbaiki masalah terkait beberapa Akun Google.

1. Membuat project Apps Script dari Google Spreadsheet:

   1. Buka spreadsheet Spreadsheet Anda.
   2. Pilih Ekstensi > Apps Script.
   3. Di editor skrip, klik Project tanpa judul.
   4. Beri nama project Anda, lalu klik Ganti nama.

   Skrip Anda kini terikat ke spreadsheet Anda, yang memberi skrip kemampuan khusus untuk mengubah antarmuka pengguna atau merespons saat spreadsheet dibuka.

   Project skrip merepresentasikan kumpulan file dan resource Apps Script. File kode dalam project skrip memiliki ekstensi .gs.

2. Anda dapat menggunakan Apps Script untuk menulis fungsi kustom yang dapat Anda gunakan di Google Spreadsheet seperti fungsi bawaan. Fungsi kustom dibuat menggunakan JavaScript standar. Buat fungsi:

   1. Buka project Apps Script Anda.
   2. Klik Editor .
   3. File skrip akan muncul sebagai file project bernama Code.gs. Untuk mengedit file, pilih file tersebut.

   4. Ganti kode apa pun di editor skrip dengan kode berikut yang membaca data di spreadsheet Anda dan meneruskannya sebagai input ke eksekusi alur kerja:

      function handleEdit(e) {
        var range = e.range.getA1Notation();
        var sheet = e.source;
      
        if (range.length > 1 && range[0] === 'G') {
          if (e.value == "TRUE") {
            Logger.log("Approved: TRUE");
      
            var row = range.slice(1);
            var url = sheet.getRange('E' + row).getCell(1, 1).getValue();
            var approver = sheet.getRange('F' + row).getCell(1, 1).getValue();
      
            callback(url, approver);
          }
          else {
            Logger.log("Approved: FALSE");
          }
        }
      }
      
      function callback(url, approver) {
        const headers = {
          "Authorization": "Bearer " + ScriptApp.getOAuthToken()
        };
      
        var payload = {
          'approver': approver
        };
      
        const params = {
          "method": 'POST',
          "contentType": 'application/json',
          "headers": headers,
          "payload": JSON.stringify(payload)
        };
      
      
        Logger.log("Workflow callback request to " + url);
        var response = UrlFetchApp.fetch(url, params);
        Logger.log(response);
      }

   5. Klik Simpan .

3. Pemicu yang dapat diinstal Apps Script memungkinkan project skrip menjalankan fungsi tertentu saat kondisi tertentu terpenuhi, seperti saat spreadsheet dibuka atau diedit. Buat pemicu:

   1. Buka project Apps Script Anda.
   2. Klik Pemicu .
   3. Klik Add Trigger.
   4. Dalam dialog Add Trigger for YOUR_PROJECT_NAME, konfigurasi pemicu:
      1. Di daftar Choose which function to run, pilih handleEdit.
      2. Dalam daftar Choose which deployment should run, pilih Head.
      3. Dalam daftar Select event source, pilih From spreadsheet.
      4. Di daftar Pilih jenis peristiwa, pilih Saat pengeditan.
      5. Dalam daftar Setelan notifikasi kegagalan, pilih Beri tahu saya setiap hari.
   5. Klik Simpan.

   6. Jika Anda menerima perintah untuk memilih Akun Google, pilih akun yang sesuai, lalu klik Izinkan.

      Hal ini memungkinkan project Apps Script Anda melihat, mengedit, membuat, dan menghapus spreadsheet Google Spreadsheet Anda; serta terhubung ke layanan eksternal.

4. File manifes project Apps Script adalah file JSON yang menentukan informasi project dasar yang dibutuhkan Apps Script untuk menjalankan skrip dengan berhasil. Perhatikan bahwa editor Apps Script menyembunyikan file manifes secara default untuk melindungi setelan project Apps Script Anda. Edit file manifes:

   1. Buka project Apps Script Anda.
   2. Klik Setelan Project .
   3. Pilih kotak centang Tampilkan file manifes "appsscript.json" dalam editor.
   4. Klik Editor .
   5. File manifes muncul sebagai file project bernama appsscript.json. Untuk mengedit file, pilih file tersebut.

   6. Kolom oauthScopes menentukan array string. Untuk menetapkan cakupan otorisasi yang digunakan project Anda, tambahkan array dengan cakupan yang ingin Anda dukung. Contoh:

      {
        "timeZone": "America/Toronto",
        "dependencies": {
        },
        "exceptionLogging": "STACKDRIVER",
        "runtimeVersion": "V8",
        "oauthScopes": [
          "https://www.googleapis.com/auth/script.external_request",
          "https://www.googleapis.com/auth/cloud-platform",
          "https://www.googleapis.com/auth/spreadsheets"
        ]
      }

      Hal ini menetapkan cakupan eksplisit ke:

      • Menghubungkan ke layanan eksternal
      • Melihat, mengedit, mengonfigurasi, dan menghapus data Google Cloud Anda serta melihat alamat email untuk Akun Google Anda
      • Melihat, mengedit, membuat, dan menghapus semua spreadsheet Google Spreadsheet Anda

   7. Klik Simpan .

   Catatan: Untuk melindungi setelan project Anda, sembunyikan manifes setelah Anda selesai mengedit dengan menghapus centang pada kotak Tampilkan file manifes "appsscript.json" di editor.

Men-deploy alur kerja yang menulis ke spreadsheet dan menggunakan callback

Deploy alur kerja yang dijalankan, dijeda, lalu dilanjutkan saat callback disetujui melalui spreadsheet. Alur kerja menulis ke spreadsheet Sheets menggunakan konektor Google Sheets API.

Konsol

1. Di konsol Google Cloud , buka halaman Workflows:

   Buka Workflows

2. Klik Buat.

3. Masukkan nama untuk alur kerja baru: workflows-awaits-callback-sheets.

4. Di daftar Region, pilih us-central1 (Iowa).

5. Untuk Service account, pilih akun layanan default Compute Engine ([e-mail]).

6. Klik Berikutnya.

7. Di editor alur kerja, masukkan definisi berikut untuk alur kerja Anda:

   main:
     steps:
       - init:
           assign:
           # Replace with your sheetId and make sure the service account
           # for the workflow has write permissions to the sheet
           - sheetId: "10hieAH6b-oMeIVT_AerSLNxQck14IGhgi8ign-x2x8g"
       - before_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here before waiting for callback from sheets"}
       - wait_for_sheets_callback:
           call: await_callback_sheets
           args:
             sheetId: ${sheetId}
           result: await_callback_result
       - after_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here after receiving callback from sheets"}
       - returnResult:
           return: ${await_callback_result}
   
   await_callback_sheets:
       params: [sheetId]
       steps:
           - init:
               assign:
                 - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
                 - location: ${sys.get_env("GOOGLE_CLOUD_LOCATION")}
                 - workflow_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_ID")}
                 - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
           - create_callback:
               call: events.create_callback_endpoint
               args:
                 http_callback_method: POST
               result: callback_details
           - save_callback_to_sheets:
               call: googleapis.sheets.v4.spreadsheets.values.append
               args:
                   range: ${"Sheet1!A1:G1"}
                   spreadsheetId: ${sheetId}
                   valueInputOption: RAW
                   body:
                       majorDimension: "ROWS"
                       values:
                         - ["${project_id}", "${location}", "${workflow_id}", "${execution_id}", "${callback_details.url}", "", "FALSE"]
           - log_and_await_callback:
               try:
                 steps:
                   - log_await_start:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Started waiting for callback from sheet " + sheetId}
                   - await_callback:
                       call: events.await_callback
                       args:
                         callback: ${callback_details}
                         timeout: 3600
                       result: callback_request
                   - log_await_stop:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Stopped waiting for callback from sheet " + sheetId}
               except:
                   as: e
                   steps:
                       - log_error:
                           call: sys.log
                           args:
                               severity: "ERROR"
                               text: ${"Received error " + e.message}
           - check_null_await_result:
               switch:
                 - condition: ${callback_request == null}
                   return: null
           - log_await_result:
               call: sys.log
               args:
                 severity: INFO
                 data: ${"Approved by " + callback_request.http_request.body.approver}
           - return_await_result:
               return: ${callback_request.http_request.body}

8. Pastikan Anda mengganti nilai placeholder sheetId dengan spreadsheetId Anda.

9. Klik Deploy.

gcloud

1. Buat file kode sumber untuk alur kerja Anda:

   touch workflows-awaits-callback-sheets.yaml

2. Di editor teks, salin alur kerja berikut ke file kode sumber Anda:

   main:
     steps:
       - init:
           assign:
           # Replace with your sheetId and make sure the service account
           # for the workflow has write permissions to the sheet
           - sheetId: "10hieAH6b-oMeIVT_AerSLNxQck14IGhgi8ign-x2x8g"
       - before_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here before waiting for callback from sheets"}
       - wait_for_sheets_callback:
           call: await_callback_sheets
           args:
             sheetId: ${sheetId}
           result: await_callback_result
       - after_sheets_callback:
           call: sys.log
           args:
             severity: INFO
             data: ${"Execute steps here after receiving callback from sheets"}
       - returnResult:
           return: ${await_callback_result}
   
   await_callback_sheets:
       params: [sheetId]
       steps:
           - init:
               assign:
                 - project_id: ${sys.get_env("GOOGLE_CLOUD_PROJECT_ID")}
                 - location: ${sys.get_env("GOOGLE_CLOUD_LOCATION")}
                 - workflow_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_ID")}
                 - execution_id: ${sys.get_env("GOOGLE_CLOUD_WORKFLOW_EXECUTION_ID")}
           - create_callback:
               call: events.create_callback_endpoint
               args:
                 http_callback_method: POST
               result: callback_details
           - save_callback_to_sheets:
               call: googleapis.sheets.v4.spreadsheets.values.append
               args:
                   range: ${"Sheet1!A1:G1"}
                   spreadsheetId: ${sheetId}
                   valueInputOption: RAW
                   body:
                       majorDimension: "ROWS"
                       values:
                         - ["${project_id}", "${location}", "${workflow_id}", "${execution_id}", "${callback_details.url}", "", "FALSE"]
           - log_and_await_callback:
               try:
                 steps:
                   - log_await_start:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Started waiting for callback from sheet " + sheetId}
                   - await_callback:
                       call: events.await_callback
                       args:
                         callback: ${callback_details}
                         timeout: 3600
                       result: callback_request
                   - log_await_stop:
                       call: sys.log
                       args:
                         severity: INFO
                         data: ${"Stopped waiting for callback from sheet " + sheetId}
               except:
                   as: e
                   steps:
                       - log_error:
                           call: sys.log
                           args:
                               severity: "ERROR"
                               text: ${"Received error " + e.message}
           - check_null_await_result:
               switch:
                 - condition: ${callback_request == null}
                   return: null
           - log_await_result:
               call: sys.log
               args:
                 severity: INFO
                 data: ${"Approved by " + callback_request.http_request.body.approver}
           - return_await_result:
               return: ${callback_request.http_request.body}

3. Pastikan Anda mengganti nilai placeholder sheetId dengan spreadsheetId Anda.

4. Deploy alur kerja dengan memasukkan perintah berikut:

   gcloud workflows deploy workflows-awaits-callback-sheets \
       --source=workflows-awaits-callback-sheets.yaml \
       --location=us-central1 \
       --service-account=[e-mail]

   Ganti PROJECT_NUMBER dengan Google Cloud nomor project Anda. Anda dapat mengambil nomor project Anda:

   gcloud projects describe PROJECT_ID

Menguji alur menyeluruh

Jalankan alur kerja untuk menguji alur menyeluruh. Mengeksekusi alur kerja menjalankan definisi alur kerja saat ini yang terkait dengan alur kerja.

Konsol

1. Di konsol Google Cloud , buka halaman Workflows:

   Buka Workflows

2. Di halaman Workflows, pilih alur kerja workflows-awaits-callback-sheets untuk membuka halaman detailnya.

3. Di halaman Workflow details, klik Execute.

4. Klik Execute lagi.

   Alur kerja dimulai dan status eksekusinya harus Running. Log juga menunjukkan bahwa alur kerja dijeda dan menunggu:

   Execute steps here before waiting for callback from sheets
   ...
   Started waiting for callback from sheet 1JlNFFnqs760M_KDqeeeDc_qtrABZDxoalyCmRE39dpM

5. Pastikan alur kerja telah menulis detail panggilan balik ke baris di spreadsheet Anda.

   Misalnya, Anda akan melihat ID eksekusi alur kerja di kolom Execution ID, endpoint callback di kolom Callback URL, dan FALSE di kolom Approved?.

6. Di spreadsheet, ubah FALSE menjadi TRUE.

   Setelah satu atau dua menit, eksekusi akan dilanjutkan dan kemudian selesai dengan status eksekusi Succeeded.

gcloud

1. Buka terminal.

2. Menjalankan alur kerja:

     gcloud workflows run workflows-awaits-callback-sheets

   Alur kerja dimulai dan output akan menunjukkan bahwa alur kerja dijeda dan menunggu:

     Waiting for execution [a8361789-90e0-467f-8bd7-ea1c81977820] to complete...working.

3. Pastikan alur kerja telah menulis detail panggilan balik ke baris di spreadsheet Anda.

   Misalnya, Anda akan melihat ID eksekusi alur kerja di kolom Execution ID, endpoint callback di kolom Callback URL, dan FALSE di kolom Approved?.

4. Di spreadsheet, ubah FALSE menjadi TRUE.

   Setelah satu atau dua menit, eksekusi akan dilanjutkan dan kemudian selesai dengan status eksekusi SUCCEEDED.