Webhook dapat berupa Webhook standar atau Webhook fleksibel. Dengan webhook standar, kolom permintaan dan respons ditentukan oleh Dialogflow. Dengan webhook fleksibel, Anda menentukan kolom permintaan dan respons.
Webhook standar
Dengan webhook standar, Anda menggunakan pesan respons dan permintaan yang ditentukan Dialogflow. Pesan permintaan memberikan banyak detail tentang sesi. Misalnya, halaman aktif saat ini, intent terbaru yang cocok, parameter value sesi, dan respons yang ditentukan agen akan disertakan.
Permintaan webhook standar
Saat
fulfillment
dengan webhook dipanggil,
Dialogflow akan mengirimkan permintaan webhook POST HTTPS ke layanan webhook.
Isi permintaan ini adalah objek JSON WebhookRequest
dengan informasi tentang sesi tersebut.
Beberapa
integrasi
mengisi kolom WebhookRequest.payload
dengan informasi tambahan.
Misalnya, integrasi gateway ponsel Dialogflow CX menyediakan ID pemanggil pengguna akhir.
Lihat dokumentasi referensi
WebhookRequest
(V3)
atau
WebhookRequest
(V3Beta1)
untuk mengetahui detailnya.
Respons webhook standar
Setelah layanan webhook Anda menerima permintaan webhook, layanan tersebut perlu mengirimkan respons webhook. Batasan berikut berlaku pada respons Anda:
- Respons harus terjadi dalam waktu tunggu yang Anda konfigurasi saat membuat resource webhook. Jika tidak, waktu tunggu permintaan akan habis.
- Ukuran respons harus kurang dari atau sama dengan 64 KiB.
Lihat dokumentasi referensi
WebhookResponse
(V3)
atau
WebhookResponse
(V3Beta1)
untuk mengetahui detailnya.
Setelan resource webhook standar
Berikut adalah penjelasan setelan resource webhook untuk webhook standar:
Masa Berlaku | Definisi |
---|---|
Nama tampilan | Nama yang ditampilkan di konsol untuk webhook. |
Waktu tunggu webhook habis | Saat Dialogflow mengirimkan permintaan webhook ke layanan webhook Anda, waktu tunggu mungkin habis saat menunggu respons. Setelan ini mengontrol waktu tunggu dalam detik. Jika waktu tunggu habis, Dialogflow akan memanggil peristiwa webhook.error.timeout. |
Jenis | Tetapkan ke Service directory jika Anda menggunakan direktori layanan untuk akses jaringan pribadi. Jika tidak, tetapkan ke Generic web service. |
URL webhook | Masukkan alamat URL untuk layanan webhook Anda. |
Subjenis | Tetapkan ke Standar |
Webhook khusus lingkungan | Anda dapat menyediakan webhook khusus lingkungan. |
Authentication | Lihat bagian autentikasi. |
Sertifikat CA kustom | Kunci ini digunakan untuk mengupload sertifikat CA kustom. |
Webhook fleksibel
Dengan webhook fleksibel, Anda dapat menentukan metode HTTP permintaan, parameter URL permintaan, serta kolom pesan permintaan dan respons. Permintaan hanya dapat menyediakan parameter value yang dipilih, dan respons hanya dapat memberikan parameter value pengganti. Batasan ini sebenarnya bermanfaat karena menyederhanakan antarmuka antara agen dan webhook. Kebutuhan untuk mengomunikasikan apa pun selain parameter value sesi antara agen dan webhook jarang terjadi. Metode ini juga menyederhanakan implementasi webhook Anda, karena pesan permintaan dan respons hanya berisi hal yang Anda butuhkan, dan Anda dapat menyediakan pesan webhook yang unik untuk berbagai skenario.
Permintaan webhook fleksibel
Saat membuat resource webhook untuk agen, Anda dapat menentukan hal berikut untuk permintaan webhook:
- Metode HTTP yang digunakan untuk permintaan webhook yang dikirim ke layanan webhook Anda.
- Nilai parameter sesi yang harus dikirim Dialogflow ke layanan webhook Anda menggunakan URL.
- Jika memilih
POST
,PUT
, atauPATCH
sebagai metode, Anda dapat menentukan parameter value sesi yang harus dikirim Dialogflow ke layanan webhook melalui isi JSON permintaan.
Untuk mengirim parameter value sesi menggunakan URL permintaan atau isi JSON, gunakan referensi parameter seperti biasa. Anda tidak perlu meng-escape URL dari referensi parameter, dan tidak menggabungkan referensi dalam tanda kutip. Saat runtime, Dialogflow akan meng-escape nilai parameter sesuai kebutuhan. Daftar atau nilai gabungan akan diberikan sebagai JSON.
Saat menggunakan referensi parameter dalam isi JSON, Anda harus menggabungkan referensi dengan tanda kutip, apa pun jenis parameternya. Jika parameter tersebut sebenarnya merupakan skalar numerik, daftar, atau nilai komposit, Dialogflow akan menghapus tanda kutip saat mengirim permintaan saat runtime untuk mempertahankan jenis data parameter. Jenis skalar string akan tetap dikutip. Jika nilai skalar, daftar, atau gabungan numerik direferensikan dalam nilai string (misalnya: "This is a number: $session.params.size"), parameter ini akan diperlakukan sebagai string ("This is a number: 3").
Misalnya,
Anda dapat memberikan parameter value sesi fruit
dan size
ke URL permintaan seperti ini:
https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size
Dan, untuk isi JSON permintaan seperti ini:
{
"fruitParameter": "$session.params.fruit",
"sizeParameter": "$session.params.size"
}
Respons webhook fleksibel
Saat membuat resource webhook untuk agen, Anda dapat menentukan parameter sesi yang harus ditetapkan Dialogflow ke kolom tertentu dari respons webhook saat runtime.
Batasan berikut berlaku pada respons Anda:
- Respons harus terjadi dalam waktu tunggu yang Anda konfigurasi saat membuat resource webhook. Jika tidak, waktu tunggu permintaan akan habis.
- Ukuran respons harus kurang dari atau sama dengan 64 KiB.
Gunakan format berikut untuk menentukan kolom skalar, daftar, atau komposit:
$.fully.qualified.path.to.field
Misalnya, pertimbangkan respons JSON berikut:
{
"routes" : [
{
"legs" : [
{
"distance" : {
"text" : "2,064 mi",
"value" : 3321004
}
}
]
}
]
}
Untuk menentukan kolom "value", gunakan hal berikut:
$.routes[0].legs[0].distance.value
Setelan resource webhook fleksibel
Berikut ini menjelaskan setelan resource webhook untuk webhook fleksibel:
Masa Berlaku | Definisi |
---|---|
Nama tampilan | Nama yang ditampilkan di konsol untuk webhook. |
Waktu tunggu webhook habis | Saat Dialogflow mengirimkan permintaan webhook ke layanan webhook Anda, waktu tunggu mungkin habis saat menunggu respons. Setelan ini mengontrol waktu tunggu dalam detik. Jika waktu tunggu habis, Dialogflow akan memanggil peristiwa webhook.error.timeout. |
Jenis | Tetapkan ke Service directory jika Anda menggunakan direktori layanan untuk akses jaringan pribadi. Jika tidak, tetapkan ke Generic web service. |
URL webhook | Berikan alamat URL untuk layanan webhook Anda, yang mungkin menyertakan referensi ke parameter sesi. |
Subjenis | Setel ke Fleksibel |
Metode | Tetapkan metode HTTP untuk permintaan webhook. |
Isi permintaan | Berikan isi JSON permintaan seperti yang dijelaskan di atas. |
Konfigurasi respons | Berikan parameter sesi yang harus ditetapkan ke kolom respons seperti yang dijelaskan di atas. |
Webhook khusus lingkungan | Anda dapat menyediakan webhook khusus lingkungan. |
Authentication | Lihat bagian autentikasi. |
Sertifikat CA kustom | Kunci ini digunakan untuk mengupload sertifikat CA kustom. |
Persyaratan layanan webhook
Persyaratan berikut harus dipenuhi oleh layanan webhook Anda:
- Aplikasi harus menangani permintaan HTTPS. HTTP tidak didukung. Jika Anda menghosting layanan webhook di Google Cloud Platform menggunakan solusi Komputasi atau Komputasi Serverless, lihat dokumentasi produk untuk melakukan penayangan dengan HTTPS. Untuk opsi hosting lainnya, lihat Mendapatkan sertifikat SSL untuk domain Anda.
- URL-nya untuk permintaan harus dapat diakses secara publik, kecuali jika dihosting sebagai Cloud Function atau diakses sebagai webhook Direktori layanan.
- Webhook harus menangani permintaan dan respons seperti yang dijelaskan di bagian Webhook standar atau Webhook fleksibel.
- Jika agen Anda tidak terintegrasi dengan akses jaringan pribadi Direktori Layanan, panggilan webhook dianggap di luar perimeter layanan dan akan diblokir saat mengaktifkan Kontrol Layanan VPC. Endpoint terbatas didukung oleh Direktori Layanan. Lihat Direktori Layanan untuk mengetahui detailnya.
Authentication
Mengamankan layanan webhook Anda adalah hal yang penting, sehingga hanya Anda atau agen Dialogflow Anda yang diizinkan untuk membuat permintaan. Hal ini dikonfigurasi saat membuat resource webhook. Dialogflow CX mendukung mekanisme autentikasi berikut:
Masa Berlaku | Definisi |
---|---|
Header autentikasi | Untuk setelan webhook, Anda dapat menentukan key-value pair header HTTP opsional. Jika disediakan, Dialogflow akan menambahkan header HTTP ini ke permintaan webhook. Anda dapat memberikan satu pasangan dengan kunci authorization . Nilai header mendukung referensi parameter sesi dan penguraian fungsi sistem seperti dalam pesan respons statis. |
Autentikasi dasar dengan nama pengguna dan sandi | Untuk setelan webhook, Anda dapat menentukan nilai sandi dan nama pengguna login opsional. Jika disediakan, Dialogflow akan menambahkan header HTTP otorisasi ke permintaan webhook. Header ini memiliki bentuk: "authorization: Basic <base 64 encoding of the string username:password>" . |
OAuth pihak ketiga | Anda dapat menentukan konfigurasi OAuth pihak ketiga sehingga Dialogflow akan mempertukarkan token akses dari penyedia OAuth dan menambahkannya di header HTTP otorisasi. Hanya alur kredensial klien yang didukung. |
Token akses agen layanan | Anda dapat memilih token akses di Autentikasi agen layanan agar dapat menggunakan token akses agen layanan untuk autentikasi. Akses ini dapat digunakan untuk mengakses Google Cloud API lainnya. |
Token ID agen layanan | Anda dapat memilih token ID di Autentikasi agen layanan agar dapat menggunakan token ID agen layanan untuk autentikasi. Akses ini dapat digunakan untuk mengakses layanan Cloud Function dan Cloud Run. Jika tidak ada opsi autentikasi lain yang digunakan, opsi ini diaktifkan secara default. |
Autentikasi TLS bersama | Lihat dokumentasi Autentikasi TLS bersama. |
Verifikasi sertifikat HTTPS
Dialogflow secara default menggunakan penyimpanan kepercayaan default Google untuk memverifikasi sertifikat HTTPS. Jika Anda ingin menggunakan sertifikat yang tidak dikenali oleh penyimpanan trust default Google untuk server HTTPS, seperti sertifikat yang ditandatangani sendiri atau root certificate kustom, lihat Sertifikat CA kustom.
Webhook khusus lingkungan
Jika menggunakan lingkungan untuk mengisolasi sistem produksi dari sistem pengembangan (direkomendasikan), Anda dapat mengonfigurasi webhook agar spesifik per lingkungan. Untuk setiap resource webhook yang ditentukan, Anda dapat memberikan setelan autentikasi dan URL unik untuk setiap lingkungan yang telah Anda tentukan untuk agen.
Dengan demikian, Anda dapat mengembangkan dan menguji pembaruan kode webhook dengan aman sebelum men-deploy-nya ke produksi.
Membuat atau mengedit resource webhook
Setelah layanan webhook berjalan, Anda harus membuat resource webhook di agen Anda yang memiliki informasi konektivitas dan autentikasi. Setelah pembuatan, Anda juga dapat mengedit setelan resource webhook kapan saja.
Untuk membuat atau mengedit resource webhook:
Konsol
- Buka Konsol Dialogflow CX.
- Pilih project Google Cloud Anda.
- Pilih agen Anda.
- Pilih tab Kelola.
- Klik Webhook.
- Klik Buat atau klik resource webhook di daftar untuk mengedit.
- Masukkan setelan resource webhook standar atau setelan resource webhook fleksibel.
- Klik Save.
API
Untuk membuat resource webhook, lihat metode create
untuk jenis Webhook
.
Untuk mengedit resource webhook (kecuali untuk setelan spesifik per lingkungan), lihat metode patch
atau update
untuk jenis Webhook
.
Pilih protokol dan versi untuk referensi Webhook:
Protokol | V3 | V3beta1 |
---|---|---|
REST | Resource webhook | Resource webhook |
RPC | Antarmuka webhook | Antarmuka webhook |
C++ | WebhooksClient | Tidak tersedia |
C# | WebhooksClient | Tidak tersedia |
Go | WebhooksClient | Tidak tersedia |
Java | WebhooksClient | WebhooksClient |
Node.js | WebhooksClient | WebhooksClient |
PHP | Tidak tersedia | Tidak tersedia |
Python | WebhooksClient | WebhooksClient |
Ruby | Tidak tersedia | Tidak tersedia |
Untuk mengedit setelan spesifik per lingkungan untuk webhook, lihat metode patch
atau update
untuk jenis Environment
.
Pilih protokol dan versi untuk referensi Lingkungan:
Protokol | V3 | V3beta1 |
---|---|---|
REST | Referensi lingkungan | Referensi lingkungan |
RPC | Antarmuka lingkungan | Antarmuka lingkungan |
C++ | EnvironmentsClient | Tidak tersedia |
C# | EnvironmentsClient | Tidak tersedia |
Go | EnvironmentsClient | Tidak tersedia |
Java | EnvironmentsClient | EnvironmentsClient |
Node.js | EnvironmentsClient | EnvironmentsClient |
PHP | Tidak tersedia | Tidak tersedia |
Python | EnvironmentsClient | EnvironmentsClient |
Ruby | Tidak tersedia | Tidak tersedia |
Error webhook
Jika layanan webhook Anda mengalami error saat menangani permintaan webhook, kode webhook harus menampilkan salah satu kode status HTTP berikut:
400
Bad Request401
Unauthorized403
Terlarang404
Tidak ditemukan500
Kesalahan server503
Service Unavailable
Dalam salah satu situasi error berikut, Dialogflow akan memanggil error webhook atau peristiwa bawaan waktu tunggu habis dan terus memproses seperti biasa:
- Waktu tunggu respons terlampaui.
- Kode status error diterima.
- Respons tidak valid.
- Layanan webhook tidak tersedia.
Selain itu, jika panggilan layanan webhook
dipicu oleh panggilan API intent deteksi,
kolom queryResult.webhookStatuses
dalam respons intent deteksi
berisi informasi status webhook.
Menggunakan Cloud Functions
Dialogflow terintegrasi dengan Cloud Functions, sehingga Anda dapat dengan mudah membuat webhook yang aman dan serverless. Jika Anda membuat fungsi yang berada di project yang sama dengan agen, agen Anda dapat memanggil webhook dengan aman tanpa memerlukan konfigurasi khusus.
Namun, ada dua situasi yang mengharuskan Anda menyiapkan integrasi ini secara manual:
- Akun layanan Dialogflow Service Agent dengan alamat berikut harus ada untuk project agen Anda:
Akun layanan khusus ini dan kunci terkait biasanya dibuat secara otomatis saat Anda membuat agen pertama untuk sebuah project. Jika agen dibuat sebelum 1 November 2020, Anda dapat memicu pembuatan akun layanan khusus ini:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- Buat agen baru untuk project.
- Jalankan perintah berikut:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Jika fungsi webhook Anda berada di project yang berbeda dengan agen, Anda harus memberikan peran IAM Cloud Functions Invoker ke akun layanan Dialogflow Service Agent di project fungsi Anda.
Menggunakan webhook dalam container dan framework ezcx Go
Jika Anda ingin mengimplementasikan webhook dalam container menggunakan Go, lihat framework Go ezcx. Framework ini dapat menyederhanakan banyak langkah yang diperlukan saat membuat webhook.
Menggunakan Direktori Layanan untuk akses jaringan pribadi
Dialogflow terintegrasi dengan akses jaringan pribadi Direktori Layanan, sehingga dapat terhubung ke target webhook di dalam jaringan VPC Anda. Tindakan ini menjaga traffic dalam jaringan Google Cloud dan menerapkan IAM dan Kontrol Layanan VPC.
Untuk menyiapkan webhook yang menargetkan jaringan pribadi:
Ikuti Konfigurasi jaringan pribadi Direktori Layanan untuk mengonfigurasi endpoint Direktori Layanan dan jaringan VPC Anda.
Akun layanan Dialogflow Service Agent dengan alamat berikut harus ada untuk project agen Anda:
Berikan peran IAM berikut kepada akun layanan Dialogflow Service Agent:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
servicedirectory.viewer
project Direktori Layananservicedirectory.pscAuthorizedService
project jaringan
Berikan Layanan Direktori Layanan beserta URL dan informasi autentikasi opsional saat membuat webhook.
Konsol
API
Lihat kolom
serviceDirectory
untuk jenisWebhook
.Pilih protokol dan versi untuk referensi Webhook:
Protokol V3 V3beta1 REST Resource webhook Resource webhook RPC Antarmuka webhook Antarmuka webhook C++ WebhooksClient Tidak tersedia C# WebhooksClient Tidak tersedia Go WebhooksClient Tidak tersedia Java WebhooksClient WebhooksClient Node.js WebhooksClient WebhooksClient PHP Tidak tersedia Tidak tersedia Python WebhooksClient WebhooksClient Ruby Tidak tersedia Tidak tersedia
Untuk memecahkan masalah, Anda dapat menyiapkan cek uptime pribadi untuk memeriksa apakah Direktori Layanan Anda dikonfigurasi dengan benar.
Autentikasi agen layanan
Dialogflow dapat menghasilkan token ID atau token akses menggunakan agen layanan Dialogflow.
Token ditambahkan di header HTTP otorisasi saat Dialogflow memanggil webhook.
Token ID
Token ID dapat digunakan untuk mengakses layanan Cloud Function dan Cloud Run setelah Anda memberikan peran Invoker untuk
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Audiens yang digunakan untuk membuat token ID adalah seluruh URL webhook, kecuali parameter kueri. Jika Anda menggunakan Cloud Run, pastikan URL ini didukung oleh audience Cloud Run. Misalnya, jika URL webhook adalah
https://myproject.cloudfunctions.net/my-function/method1?query=value
URL berikut harus berada dalam audiens kustom.
https://myproject.cloudfunctions.net/my-function/method1
Setiap webhook juga dapat memvalidasi token secara opsional menggunakan library klien Google atau library open source seperti github.com/googleapis/google-auth-library-nodejs.
Token akses
Token akses dapat digunakan untuk mengakses Google Cloud API lainnya setelah Anda memberikan peran yang diperlukan kepada
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Contoh dan pemecahan masalah
Lihat panduan cara kerja webhook.