Membangun pemicu

Pratinjau Terbatas: Memperluas Google Workspace Studio dengan add-on masih dalam pratinjau terbatas. Pelajari lebih lanjut

Dokumen ini menjelaskan cara membuat starter yang memungkinkan aplikasi atau layanan Anda memberi tahu Google Workspace Studio saat peristiwa terjadi dan memulai eksekusi alur. Di API, starter disebut workflowTriggers.

Starter memulai alur, sedangkan langkah adalah satu tugas dalam urutan tugas yang mencakup alur. Dengan membuat permulaan, Anda memungkinkan pengguna menyiapkan alur otomatis yang bereaksi terhadap peristiwa real-time dari aplikasi atau layanan Anda.

Membuat pemicu melibatkan deklarasi pemicu dalam file manifes add-on dan penerapan callback siklus proses di Google Apps Script, atau memicu pemicu dengan memposting payload ke endpoint Google Workspace Studio API.

Prasyarat dan otorisasi OAuth

Untuk berkomunikasi dengan endpoint API Workspace Studio, aplikasi atau layanan Anda harus melakukan autentikasi menggunakan OAuth 2.0. Aplikasi harus meminta cakupan OAuth khusus berikut dari pengguna selama otorisasi:

https://www.googleapis.com/auth/workspace.studio.trigger

Cakupan ini mengizinkan aplikasi untuk memanggil Workspace Studio API dan memicu alur yang telah dikonfigurasi pengguna untuk template tersebut.

Token akses dan refresh offline

Karena starter memberi tahu Workspace Studio secara asinkron saat peristiwa terjadi di layanan eksternal—yang mungkin terjadi beberapa jam, hari, atau bulan setelah pengguna mengonfigurasi alur—layanan Anda harus menyediakan token akses OAuth 2.0 yang valid saat memanggil endpoint API.

Token akses yang diberikan oleh Google dalam objek peristiwa add-on (seperti selama konfigurasi starter atau permintaan callback siklus proses) berumur pendek dan hanya valid selama 1 jam. Hal ini tidak cukup untuk memicu peristiwa starter secara asinkron di masa mendatang. Untuk memanggil Workspace Studio API dari waktu ke waktu, layanan Anda memerlukan token refresh offline untuk membuat token akses baru sesuai permintaan.

Cara Anda menangani otorisasi dan mendapatkan token refresh bergantung pada runtime add-on Anda:

• Add-on HTTP (runtime alternatif): Untuk add-on HTTP, layanan backend Anda harus menerapkan alur otorisasi OAuth 2.0 terpisah yang independen dari otorisasi add-on bawaan untuk meminta akses offline (access_type=offline) dan menerima token refresh.

  Anda dapat meminta pengguna untuk mengizinkan koneksi ini dengan menampilkan kartu login atau otorisasi saat pengguna mengonfigurasi starter di Workspace Studio. Untuk mengetahui informasi selengkapnya tentang cara menampilkan kartu otorisasi dan menangani alur OAuth, lihat Menghubungkan add-on Google Workspace ke layanan pihak ketiga (memperlakukan Google Workspace sebagai layanan pihak ketiga yang Anda hubungkan).

  Layanan backend Anda harus menyimpan token refresh dengan aman (misalnya, di database layanan Anda bersama dengan triggerId) dan menggunakannya untuk mengambil token akses baru setiap kali peristiwa terjadi sebelum mengirim permintaan ke endpoint API notifyUri atau triggers.fire starter.

• Add-on Google Apps Script: Add-on berbasis Google Apps Script yang menggunakan pemicu terjadwal (berbasis waktu) untuk melakukan polling peristiwa dapat melewati penerapan alur OAuth independen. Karena pemicu terjadwal berjalan langsung dalam lingkungan runtime Google Apps Script, Google Apps Script secara otomatis mengelola dan memperbarui token OAuth menggunakan cakupan yang dideklarasikan dalam manifest.

Menentukan starter dalam file manifes

Untuk menentukan pemicu, tambahkan ke file manifes add-on Anda (appsscript.json) dalam blok addOns.studio.flows.workflowElements. Konfigurasi ini diperlukan untuk runtime Apps Script dan HTTP (runtime alternatif). Konfigurasi elemen sebagai workflowTrigger, bukan workflowAction (yang digunakan saat menentukan langkah). Untuk mengetahui informasi selengkapnya, lihat Struktur file manifes untuk add-on Google Workspace.

Di dalam blok workflowTrigger, tentukan:

• inputs: Variabel yang dikonfigurasi pengguna di kartu konfigurasi (seperti nama project, filter resource, dll.).
• outputs: Variabel yang dapat ditampilkan oleh starter ke langkah-langkah hilir dalam alur.
• onConfigFunction: Nama fungsi callback yang menampilkan antarmuka konfigurasi pengguna.
• onManageFunction: Nama fungsi callback yang dipanggil oleh Google untuk menangani pembuatan dan penghapusan langganan awal.

Contoh kode berikut menunjukkan contoh definisi manifes untuk pemicu peristiwa:

JSON

{
  "timeZone": "America/Los_Angeles",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Trigger App",
      "logoUrl": "https://fonts.gstatic.com/s/i/short-term/release/googlesymbols/start/default/24px.svg",
      "useLocaleFromApp": true
    },
    "studio": {
      "flows": {
        "workflowElements": [
          {
            "id": "triggerDemo",
            "state": "ACTIVE",
            "name": "Event Trigger",
            "description": "Fires when a event occurs in the app.",
            "workflowTrigger": {
              "inputs": [
                {
                  "id": "projectId",
                  "description": "The project identifier to watch.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                }
              ],
              "outputs": [
                {
                  "id": "eventName",
                  "description": "The name of the triggered event.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                },
                {
                  "id": "eventMessage",
                  "description": "Detailed event message description.",
                  "cardinality": "SINGLE",
                  "dataType": {
                    "basicType": "STRING"
                  }
                }
              ],
              "onConfigFunction": "onConfigTrigger",
              "onManageFunction": "onManageTrigger"
            }
          }
        ]
      }
    }
  }
}

Menangani siklus proses langganan awal

Saat pengguna mengonfigurasi dan mengaktifkan alur yang berisi starter Anda, atau jika alur dinonaktifkan atau dihapus, Google akan memanggil add-on Anda menggunakan fungsi callback onManageFunction yang dideklarasikan dalam manifes.

Objek peristiwa siklus proses

Fungsi callback menerima WorkflowEventObject yang berisi konteks tindakan. Sebagai permulaan, fitur ini mencakup:

• Pembuatan Pemicu (event.workflow.triggerCreation): Diaktifkan saat alur dipublikasikan atau diaktifkan.

  • triggerId: String UUID unik yang mengidentifikasi instance pendaftaran starter ini.

  • notifyUri: URL endpoint REST API unik yang terkait dengan pendaftaran awal ini (misalnya, https://workspacestudio.googleapis.com/v1/triggers/YOUR_TRIGGER_ID:fire).

  • inputs: Input variabel yang dikonfigurasi oleh pengguna dari kartu.

• Penghapusan Pemicu (event.workflow.triggerDeletion): Diaktifkan saat pemicu dihapus dari alur, atau saat seluruh alur dinonaktifkan atau dihapus.

  • triggerId: String UUID unik dari instance langganan yang akan dibersihkan.

Siklus proses langganan Alternate Runtimes (HTTP API)

Untuk add-on yang dibuat menggunakan runtime alternatif, notifikasi siklus proses langganan dikirim menggunakan permintaan POST HTTP ke URL endpoint HTTP yang dikonfigurasi add-on dengan nama tindakan yang ditentukan oleh fungsi callback onManageFunction. Payload cocok dengan representasi JSON WorkflowEventObject.

Untuk mengetahui informasi selengkapnya tentang runtime alternatif, lihat Membuat add-on Google Workspace menggunakan endpoint HTTP.

Menerapkan callback siklus proses di Apps Script

Contoh Apps Script berikut menunjukkan cara mengonfigurasi kartu antarmuka pengguna, menangani peristiwa siklus proses langganan menggunakan onManageTrigger, dan memicu permintaan awal kembali ke Google saat peristiwa terjadi.

Apps Script

/**
 * Generates and returns the user configuration card to collect inputs.
 */
function onConfigTrigger() {
  const projectInput = CardService.newTextInput()
    .setFieldName("projectId")
    .setTitle("Project ID")
    .setHint("Enter the project identifier to watch");

  const section = CardService.newCardSection()
    .setHeader("Configure Event Trigger")
    .addWidget(projectInput);

  const card = CardService.newCardBuilder()
    .addSection(section)
    .build();

  return card;
}

/**
 * Handles subscription lifecycle events sent from Google Workspace Studio.
 *
 * @param {Object} event The Workspace Studio event object.
 */
function onManageTrigger(event) {
  const triggerCreation = event.workflow.triggerCreation;
  const triggerDeletion = event.workflow.triggerDeletion;

  if (triggerCreation) {
    const triggerId = triggerCreation.triggerId;
    const notifyUri = triggerCreation.notifyUri;
    const inputs = triggerCreation.inputs;

    // Extract input values configured by the user.
    const projectId = inputs["projectId"].stringValues[0];

    // TODO: Save triggerId, notifyUri, and projectId in your database/service.
    // Your backend service listens for events related to 'projectId'
    // and calls notifyUri when those events occur.
    console.log("Trigger subscription created: " + triggerId +
                ", Notify URI: " + notifyUri +
                ", Match Project: " + projectId);

  } else if (triggerDeletion) {
    const triggerId = triggerDeletion.triggerId;

    // TODO: Remove references to triggerId from your database and stop
    // sending future event notifications to the associated notifyUri.
    console.log("Trigger subscription deleted: " + triggerId);
  }
}

/**
 * Mock function showing how your backend service fires the trigger.
 * This logic runs on your service when a watched event occurs.
 *
 * @param {string} notifyUri The stored notifyUri associated with the trigger.
 * @param {string} triggerId The stored triggerId.
 * @param {string} userAccessToken The OAuth 2.0 access token for the user
 *     (obtained using your stored refresh token).
 */
function simulateEventFire(notifyUri, triggerId, userAccessToken) {
  // A unique UUID version 4 is recommended as the requestId for idempotency.
  const requestId = Utilities.getUuid();

  const payload = {
    "name": "triggers/" + triggerId,
    "outputs": {
      "eventName": { "stringValues": ["EventOccurred"] },
      "eventMessage": { "stringValues": ["Hello from the service!"] }
    },
    "requestId": requestId
  };

  const options = {
    "method": "POST",
    "contentType": "application/json",
    "headers": {
      "Authorization": "Bearer " + userAccessToken
    },
    "payload": JSON.stringify(payload),
    "muteHttpExceptions": true
  };

  const response = UrlFetchApp.fetch(notifyUri, options);
  const responseCode = response.getResponseCode();

  if (responseCode === 200) {
    console.log("Trigger successfully fired!");
  } else if (responseCode === 404) {
    // 404 means the trigger registration is invalid or deleted.
    console.log("Trigger not found. Stop sending events for this trigger.");
    // TODO: Clean up the trigger from your backend database.
  } else if (responseCode === 429 || responseCode >= 500) {
    console.log("Temporary error (" + responseCode + "). Retry using exponential backoff.");
  } else {
    console.log("Failed to fire trigger. HTTP Code: " + responseCode + " - " + response.getContentText());
  }
}

Menggunakan Workspace Studio API

Anda dapat menggunakan Workspace Studio API (workspacestudio.googleapis.com) untuk memberi tahu Google secara terprogram tentang peristiwa pemula.

Endpoint berada di jalur dasar: https://workspacestudio.googleapis.com/v1.

Memberi tahu peristiwa awal

Memicu pemicu menggunakan metode triggers.fire untuk memulai eksekusi alur.

• Metode HTTP: POST
• Path: /v1/triggers/{triggerId}:fire (dengan {triggerId} adalah ID unik yang diambil selama pembuatan langganan pemicu)
• Cakupan OAuth: https://www.googleapis.com/auth/workspace.studio.trigger

Contoh kode berikut menunjukkan cara memicu starter dalam permintaan.

Permintaan

{
  "name": "triggers/TRIGGER_ID",
  "outputs": {
    "eventName": {
      "stringValues": [
        "EventOccurred"
      ]
    },
    "eventMessage": {
      "stringValues": [
        "Hello from the service!"
      ]
    }
  },
  "log": {
    "textFormatElements": [
      {
        "text": "An event occurred in the app."
      }
    ]
  },
  "requestId": "UNIQUE_REQUEST_ID"
}

• name (string, wajib): Nama resource starter, diformat sebagai triggers/{triggerId}.
• outputs (peta, opsional): Peta variabel output awal yang merepresentasikan data peristiwa. Setiap nilai adalah objek VariableData yang mendukung daftar yang diketik (seperti, stringValues, booleanValues, integerValues).
• log (objek, opsional): Representasi markup TextFormat yang ditampilkan di log aktivitas eksekusi Workspace Studio.
• requestId (string, opsional): ID unik (direkomendasikan UUID v4) yang terdiri dari hingga 36 karakter ASCII untuk memastikan keidempotenan API saat percobaan ulang.

Respons

Respons menampilkan objek JSON kosong {} jika berhasil.

Kuota Workspace Studio API

Traffic yang dikirim ke layanan workspacestudio.googleapis.com dibatasi untuk mencegah kelebihan beban sistem, mendorong penggunaan resource yang wajar, dan melindungi performa Google Workspace secara keseluruhan.

Kuota berikut diberlakukan:

Jenis kuota	Kuota
Per menit per project	1.000 permintaan awal
Per menit per pengguna	100 permintaan awal

Jenis kuotanya adalah:

• Per menit per project: Membatasi jumlah kumulatif peristiwa pemicu yang diaktifkan dari project Google Cloud satu developer hingga 1.000 permintaan per menit di semua pengguna yang menjalankan pemicunya.
• Per menit per pengguna: Membatasi kumulatif pemanggilan starter oleh satu pengguna akhir dalam project Cloud tertentu hingga 100 permintaan per menit.

Menangani error kuota berbasis waktu

Jika Anda melebihi kuota ini, API akan menampilkan kode error HTTP 429 Too Many Requests (atau 429 Resource Exhausted) yang menunjukkan bahwa kuota kapasitas telah terlampaui.

Untuk mengatasi error ini, kode Anda harus menangkap pengecualian dan menggunakan strategi backoff eksponensial yang terpotong. Backoff eksponensial mencoba ulang permintaan yang gagal menggunakan penundaan yang semakin lama di antara upaya, termasuk jitter acak (menghitung ulang penundaan acak pada setiap iterasi) untuk mencegah beberapa klien menyinkronkan dan mencoba ulang secara bersamaan:

1. Buat permintaan ke Workspace Studio API.
2. Jika permintaan gagal dengan error 429, tunggu 1 second + random_number_milliseconds dan coba lagi.
3. Jika gagal lagi, tunggu 2 seconds + random_number_milliseconds dan coba lagi.
4. Jika gagal lagi, tunggu 4 seconds + random_number_milliseconds dan coba lagi.
5. Lanjutkan loop ini, dengan menggandakan penundaan hingga mencapai nilai minimum maximum_backoff (biasanya 32 atau 64 detik).
6. Setelah Anda mencapai durasi backoff maksimum, coba lagi menggunakan penundaan konstan tersebut hingga batas percobaan ulang maksimum tercapai, lalu hentikan dan catat error.

Praktik terbaik

Saat mendesain dan menerapkan starter, pertimbangkan praktik terbaik berikut:

Memancarkan peristiwa tunggal, bukan daftar batch

Rancang starter Anda untuk memancarkan peristiwa individual untuk setiap kejadian yang berbeda (seperti satu rekaman yang diperbarui, pesan baru yang diposting, atau tugas yang ditetapkan), bukan memancarkan satu peristiwa yang berisi batch atau daftar item:

• Konsistensi dengan pemicu bawaan: Di Workspace Studio, pemicu Google Workspace bawaan (seperti menerima email di Gmail atau pengguna bergabung ke ruang di Google Chat) dipicu oleh satu peristiwa. Memancarkan peristiwa item tunggal sesuai dengan perilaku ini dan memberikan pengalaman yang konsisten dan dapat diprediksi bagi pengguna di semua starter.
• Konfigurasi alur yang lebih sederhana: Langkah-langkah hilir dalam alur biasanya memproses satu item dalam satu waktu. Memancarkan peristiwa item tunggal memungkinkan pengguna memetakan variabel secara langsung tanpa menambahkan langkah-langkah kompleks untuk melakukan iterasi pada array atau mengurai daftar.
• Menangani polling dan perubahan batch secara terpisah: Jika layanan backend Anda melakukan polling API eksternal dan mendeteksi beberapa item yang berubah selama satu interval polling, aktifkan peristiwa starter individual untuk setiap item, bukan menggabungkannya ke dalam satu peristiwa batch.
• Mengelola frekuensi dan kuota peristiwa: Karena memicu peristiwa individual untuk beberapa item yang berubah dapat menyebabkan lonjakan permintaan secara tiba-tiba, pastikan layanan Anda tetap berada dalam kuota Workspace Studio API (seperti batas 100 permintaan per menit per pengguna). Jika siklus polling menghasilkan item dalam jumlah besar (misalnya, lebih dari 100 rekaman yang diubah), atur kecepatan atau batasi pengiriman peristiwa dari waktu ke waktu untuk menghindari error 429 Too Many Requests.

Catatan: Starter batch kustom yang memancarkan daftar objek secara teknis didukung, tetapi tidak konsisten dengan starter standar dan mungkin memerlukan logika tambahan dalam langkah-langkah hilir untuk menangani array.

Perilaku inti dan kasus ekstrem

Saat mengintegrasikan starter, developer harus menangani perilaku error dan fitur runtime tertentu:

• Tidak ada dukungan untuk menjalankan pengujian: Workspace Studio tidak mendukung pengujian untuk pemula.
• Idempotensi dan pencegahan pemutaran ulang: Meskipun tidak benar-benar diperlukan, Anda harus menyertakan requestId unik (seperti UUID) dalam payload HTTP atau Apps Script Anda. Menyediakan requestId memastikan idempotensi dengan memungkinkan API mendeteksi dan mengabaikan notifikasi duplikat, sehingga mencegah alur berjalan beberapa kali untuk satu peristiwa.

• Alur yang dinonaktifkan dan diaktifkan kembali: Jika alur yang berisi pemicu Anda dinonaktifkan di Workspace Studio, Google akan mengirimkan peristiwa siklus proses triggerDeletion ke callback onManageFunction Anda. Selain itu, setiap panggilan ke metode FireTrigger terkait akan menampilkan kode error 404 Not Found (Requested entity was not found.). Layanan Anda harus bereaksi terhadap error 404 dengan menghentikan pengiriman notifikasi peristiwa mendatang untuk ID instance starter tersebut.

  Jika pengguna mengaktifkan kembali alur tersebut di lain waktu, Google akan memulai siklus proses langganan baru dengan memanggil callback onManageFunction Anda dengan peristiwa triggerCreation baru yang berisi triggerId dan notifyUri baru. triggerId sebelumnya dinonaktifkan secara permanen dan tidak diaktifkan kembali, sehingga layanan Anda tidak boleh melakukan polling atau memeriksa apakah instance pemicu lama telah diaktifkan kembali. Untuk mengetahui informasi selengkapnya, lihat Menangani siklus proses langganan awal.

• Penghapusan langganan yang bersifat idempoten: Fungsi callback onManageFunction Anda harus menangani permintaan penghapusan paket awal dari Google secara idempoten. Jika Google memanggil hook penghapusan beberapa kali untuk triggerId yang sama (misalnya, selama percobaan ulang karena kehilangan koneksi sementara), fungsi harus berhasil ditampilkan.

• Kuota alur: Selain kuota Workspace Studio API, alur pengguna tunduk pada kontrol kuota internal tambahan. Loop frekuensi tinggi atau volume peristiwa yang berlebihan dapat melampaui batas keamanan, sehingga alur dinonaktifkan secara otomatis.

Topik terkait

• Membangun langkah
• Menghubungkan add-on Google Workspace ke layanan pihak ketiga
• Variabel input
• Variabel output
• Mencatat aktivitas dan error
• Menangani error
• Objek peristiwa Workspace Studio