Cara memanggil API eksternal dari Workspace Studio

Alur kerja Google Workspace Studio mungkin memerlukan data dari luar Gmail, Drive, atau Chat: status pesanan, angka dari basis data, atau respons dari alat internal. Untuk mengambil data ini atau mengirim informasi ke layanan lain, Anda dapat menambahkan langkah tersebut. Kirim webhookIni akan membuat permintaan HTTP ke alamat API yang telah Anda tentukan.

Anda tidak perlu mengkonfigurasi panggilan fungsi Gemini untuk membuat permintaan tersebut. Di Workspace Studio, alur kerja mengeksekusi langkah webhook dan menerima respons. Kemudian, jika Anda merasa bermanfaat, Anda dapat meneruskan respons tersebut ke langkah lain untuk meringkasnya, mengekstrak data, atau mengkomunikasikan hasilnya.

Hal-hal yang Anda butuhkan sebelum terhubung ke API

Langkah pertama adalah memverifikasi bahwa organisasi Anda dapat menggunakan webhook. Fungsi tersebut terletak di pratinjau terbatas dan dinonaktifkan secara default. Administrator harus masuk. Aplikasi > Google Workspace > Workspace Studio > Pengaturan Webhook dan mengaktifkannya untuk unit organisasi yang bersangkutan.

Pada beberapa edisi, administrator juga dapat membatasi koneksi hanya ke satu perangkat. daftar domain dan URL yang diizinkanJika langkah tersebut muncul di Studio tetapi gagal berkomunikasi dengan API Anda, verifikasi bahwa alamat tujuan telah diotorisasi. Selain itu, secara default, tindakan yang melibatkan webhook mengharuskan pengguna untuk meninjau dan mengkonfirmasi langkah tersebut sebelum dieksekusi.

Dari layanan eksternal, Anda perlu mengetahui URL-nya, metode HTTP yang didukungnya, dan format data yang diharapkannya. Selain itu, periksa juga bagaimana otentikasinya: API publik yang hanya dapat dibaca memiliki persyaratan yang berbeda dari API pribadi yang membutuhkan token atau header khusus.

Cara memanggil API dari Workspace Studio langkah demi langkah

Memasuki studio.ruang kerja.google.com dan buat alur kerja dengan pemicu yang Anda butuhkan. Misalnya, Anda dapat memulainya saat email tiba yang memenuhi kondisi tertentu. Kemudian, ikuti langkah-langkah berikut:

1. Tekan Tambahkan langkah dan pilih Kirim webhook.
2. Masuk URL lengkap dari API, termasuk awalan https://Alamat harus tetap: kolom ini tidak mendukung variabel aliran.
3. Pilih metode HTTP. MENDAPATKAN Ini digunakan untuk menanyakan data; POSuntuk mengirimkannya atau membuat catatan. Mereka juga tersedia PASANG, PATCH, dan HAPUS.
4. Jika API memerlukan isi (body), tuliskan di kolom konten atau muatanGoogle merekomendasikan penggunaan JSON ketika layanan penerima mengharapkannya.
5. Buatlah pelaksanaan pengujianPeriksa hasilnya dan aktifkan alur setelah Anda memverifikasi bahwa alur tersebut berfungsi.

Ingatlah bahwa tes tersebut melakukan tindakanJika Anda mengkonfigurasi POST untuk membuat catatan atau DELETE untuk menghapusnya, pertama-tama gunakan lingkungan pengujian atau data yang dapat Anda modifikasi tanpa masalah.

Contoh: mengirim notifikasi ke alat eksternal

Bayangkan tim Anda memiliki API yang membuat peringatan di https://api.ejemplo.com/v1/avisosAlamat ini adalah ilustrasiAnda perlu menggantinya dengan yang dari layanan Anda. Jika dokumentasinya menunjukkan bahwa layanan tersebut menerima POST dan body JSON, Anda dapat mengkonfigurasi langkah tersebut dengan konten seperti ini: {"tipo":"nuevo_correo","origen":"Workspace Studio"}.

Anda juga dapat memasukkan variabel aliran Di bagian isi, misalnya, sertakan subjek email yang memicu hal tersebut. Lakukan ini dari pemilih variabel Studio dan periksa hasilnya: jika teks yang disisipkan berisi tanda kutip atau karakter khusus lainnya, hal itu dapat menyebabkan JSON menjadi tidak valid. Variabel dapat digunakan dalam konten, tetapi tidak ada di kolom URL.

Jika Anda perlu mengambil data, pilih GET dan masukkan URL tetap yang sudah berisi parameter yang diperlukan. Workspace Studio akan mengabaikan konten apa pun yang Anda tulis di badan permintaan GET.

Apa yang harus dilakukan dengan respons API?

Langkah webhook meninggalkan respons layanan sebagai teks dalam sebuah variabel yang tersedia untuk langkah-langkah selanjutnya. Anda dapat menggunakannya untuk mengirim pemberitahuan, menulis ringkasan, atau meminta langkah AI untuk mengekstrak data tertentu.

Misalnya, jika API mengembalikan status pesanan, langkah selanjutnya dapat mengkomunikasikan status tersebut kepada tim. Pilih secara eksplisit variabel yang berisi respons: langkah-langkah selanjutnya tidak secara otomatis menerima semua yang terjadi sebelumnya dalam alur kerja. Disarankan untuk menguji konten yang dikembalikan sebelum menulis instruksi yang bergantung padanya.

Jika API memerlukan otentikasi atau logika yang lebih kompleks

Konfigurasi dasar yang didokumentasikan untuk Kirim webhook Ini mencakup URL, metode, dan isi opsional. Jika integrasi Anda perlu mendapatkan token OAuth, membuat URL dengan parameter variabel, menambahkan header khusus, atau mengubah respons sebelum melanjutkan, periksa apakah langkah ini mencakup persyaratan tersebut.

Jika itu tidak mencukupi, salah satu pilihannya adalah mengembangkan Langkah kustom untuk Workspace Studio melalui sebuah plugin. Dalam implementasi Google Apps Script, layanan tersebut UrlFetchApp Ini memungkinkan Anda untuk membuat permintaan ke API eksternal dan memproses respons JSON. Solusi ini memerlukan pengembangan dan konfigurasi izin yang tepat; hal ini tidak diperlukan untuk permintaan sederhana yang sudah dapat ditangani oleh langkah bawaan.

Hindari menempelkan kunci pribadi ke kolom yang terlihat dalam alur kerja atau menyematkannya dalam URL bersama. Sebelum mengirim data dari Gmail, Chat, atau Kalender, verifikasi informasi apa yang akan diterima oleh layanan eksternal dan apakah layanan tersebut berwenang untuk memprosesnya.

Cara menemukan kesalahan pada webhook

Jika koneksi gagal, buka tab tersebut. Aktivitas dari alur tersebut. Di sana Anda dapat melihat kesalahan lengkap dan respons yang dikirim oleh server tujuan. Informasi ini membantu membedakan antara masalah konfigurasi Studio dan permintaan yang ditolak oleh API.

• Langkah tersebut tidak muncul: Periksa dengan administrator Anda apakah webhook diaktifkan untuk unit organisasi Anda.
• URL tersebut diblokir: Periksa daftar alamat yang diizinkan, jika edisi Anda menggunakan pembatasan tersebut.
• Kesalahan 400: Periksa format isi dan kolom yang dibutuhkan oleh API.
• Kesalahan 401 atau 403: Tinjau izin dan metode otentikasi yang dibutuhkan oleh layanan tersebut.
• Kesalahan 429: Periksa apakah Anda telah melampaui batas permintaan untuk API target.
• Kesalahan 500: Periksa status dan catatan layanan yang menerima permintaan tersebut.

Perlu diingat juga batasan umum Workspace Studio: saat ini hanya mendukung hingga 25 alur per pengguna y 20 langkah per alurSelain itu, terdapat batasan eksekusi gabungan yang direset setiap 24 jam. Jika beberapa alur berhenti berjalan, tinjau aktivitasnya sebelum menyimpulkan kegagalan tersebut disebabkan oleh API.

Untuk sebagian besar koneksi HTTP sederhana, prosesnya mudah: aktifkan webhook, konfigurasikan URL tetap dan metode yang benar, uji permintaan, dan gunakan respons pada langkah selanjutnya. Jika integrasi memerlukan otentikasi tingkat lanjut atau transformasi data melalui kode, maka masuk akal untuk menyiapkan langkah khusus.