Halaman ini menjelaskan cara menerima dan mengonfirmasi pesan menggunakan fitur tepat sekali Pub/Sub, yang memungkinkan Anda melacak dan mencegah pemrosesan pesan duplikat. Saat fitur diaktifkan, Pub/Sub menyediakan semantik berikut:
Pelanggan dapat menentukan apakah konfirmasi pesan berhasil.
Tidak ada pengiriman ulang setelah pesan berhasil dikonfirmasi.
Tidak ada pengiriman ulang saat pesan masih tertunda. Pesan dianggap belum selesai hingga batas waktu konfirmasi berakhir atau pesan dikonfirmasi.
Jika ada beberapa pengiriman yang valid, karena habis masa berlaku batas waktu respons atau respons negatif yang dimulai klien, hanya ID respons terbaru yang dapat digunakan untuk mengonfirmasi pesan. Semua permintaan dengan ID konfirmasi sebelumnya akan gagal.
Dengan mengaktifkan tepat satu kali, pelanggan dapat memastikan pesan diproses satu kali dengan mengikuti panduan berikut:
Konfirmasi pesan dalam batas waktu konfirmasi.
Mempertahankan informasi tentang progres pemrosesan pesan hingga pesan tersebut berhasil dikonfirmasi.
Gunakan informasi tentang progres pemrosesan pesan untuk mencegah pekerjaan duplikat saat konfirmasi gagal.
Hanya jenis langganan pull yang mendukung pengiriman tepat satu kali, termasuk pelanggan yang menggunakan StreamingPull API. Langganan push dan ekspor tidak mendukung pengiriman tepat satu kali.
Pub/Sub mendukung pengiriman tepat satu kali, dalam region cloud, berdasarkan ID pesan unik yang ditentukan Pub/Sub.
Versi library klien yang direkomendasikan
- Untuk performa terbaik, gunakan library klien versi terbaru, Python v2.13.6 atau yang lebih baru, Java v1.120.11 atau yang lebih baru, PHP v1.39.0 atau yang lebih baru, C# v3.2.0 atau yang lebih baru, C++ v2.1.0, Go v1.25.1 atau yang lebih baru, Node v3.2.0 atau yang lebih baru, dan Ruby v2.12.1 atau yang lebih baru.
Pengiriman ulang versus duplikat
Anda harus memahami perbedaan antara pengiriman ulang yang diharapkan dan tidak diharapkan.
Pengiriman ulang dapat terjadi karena konfirmasi negatif pesan yang dimulai klien atau saat klien tidak memperpanjang batas waktu konfirmasi pesan sebelum batas waktu konfirmasi berakhir. Pengiriman ulang dianggap valid dan sistem berfungsi sebagaimana mestinya.
Untuk memecahkan masalah pengiriman ulang, lihat Menangani duplikat.
Duplikat adalah saat pesan dikirim ulang setelah konfirmasi berhasil atau sebelum batas waktu konfirmasi berakhir.
Pesan yang dikirim ulang mempertahankan ID pesan yang sama di antara upaya pengiriman ulang.
Langganan dengan pengiriman tepat satu kali yang diaktifkan tidak menerima pengiriman duplikat.
Dukungan pengiriman tepat satu kali di library klien
Library klien yang didukung memiliki antarmuka untuk konfirmasi dengan respons (contoh: Go). Anda dapat menggunakan antarmuka ini untuk memeriksa apakah permintaan konfirmasi berhasil. Jika permintaan konfirmasi berhasil, klien dijamin tidak akan menerima pengiriman ulang. Jika permintaan konfirmasi gagal, klien dapat mengharapkan pengiriman ulang.
Klien juga dapat menggunakan library klien yang didukung tanpa antarmuka konfirmasi. Namun, dalam kasus tersebut, kegagalan konfirmasi dapat menyebabkan pengiriman ulang pesan secara diam-diam.
Library klien yang didukung memiliki antarmuka untuk menetapkan waktu perpanjangan sewa minimum (contoh: Go). Anda harus menetapkan nilai untuk perpanjangan sewa minimum ke angka yang tinggi untuk menghindari habis masa berlaku konfirmasi terkait jaringan. Nilai maksimum ditetapkan pada 600 detik.
Nilai dan rentang default untuk variabel yang terkait dengan pengiriman tepat sekali dan nama variabel mungkin berbeda di seluruh library klien. Misalnya, di library klien Java, variabel berikut mengontrol pengiriman tepat sekali.
Variabel | Deskripsi | Nilai |
---|---|---|
setEnableExactlyOnceDelivery |
Mengaktifkan atau menonaktifkan pengiriman tepat satu kali. | true atau false Default=false |
minDurationPerAckExtension |
Waktu minimum dalam hitungan detik yang akan digunakan untuk memperpanjang batas waktu konfirmasi perubahan. | Rentang=0 hingga 600 Default=tidak ada |
maxDurationPerAckExtension |
Waktu maksimum dalam detik yang akan digunakan untuk memperpanjang batas waktu konfirmasi perubahan. | Rentang=0 hingga 600 Default=tidak ada |
Dalam kasus pengiriman tepat sekali, permintaan modifyAckDeadline
atau acknowledgment
ke Pub/Sub akan gagal jika ID konfirmasi sudah tidak berlaku. Dalam kasus
tersebut, layanan menganggap ID konfirmasi yang sudah tidak berlaku sebagai tidak valid, karena
pengiriman yang lebih baru mungkin sudah dalam proses. Hal ini sudah didesain untuk pengiriman tepat
sekali. Kemudian, Anda akan melihat permintaan acknowledgment
dan ModifyAckDeadline
menampilkan respons INVALID_ARGUMENT
. Jika pengiriman tepat sekali dinonaktifkan, permintaan
ini akan menampilkan OK
jika ID konfirmasi sudah tidak berlaku lagi.
Untuk memastikan permintaan acknowledgment
dan ModifyAckDeadline
memiliki ID konfirmasi yang valid, sebaiknya tetapkan nilai untuk minDurationPerAckExtension
ke angka yang tinggi.
Pertimbangan regional
Jaminan pengiriman tepat satu kali hanya berlaku saat pelanggan terhubung ke layanan di wilayah yang sama. Jika aplikasi pelanggan Anda tersebar di beberapa wilayah, hal ini dapat menyebabkan pengiriman pesan duplikat, meskipun pengiriman tepat sekali diaktifkan. Penayang dapat mengirim pesan ke wilayah mana pun dan jaminan tepat sekali masih dipertahankan.
Saat Anda menjalankan aplikasi dalam Google Cloud, secara default aplikasi tersebut akan terhubung ke endpoint Pub/Sub di region yang sama. Oleh karena itu, menjalankan aplikasi di satu region dalam Google Cloud umumnya memastikan Anda berinteraksi dengan satu region.
Saat menjalankan aplikasi pelanggan di luar Google Cloud atau di beberapa region, Anda dapat memastikan bahwa Anda terhubung ke satu region dengan menggunakan endpoint lokasi saat mengonfigurasi klien Pub/Sub. Semua endpoint lokasi untuk Pub/Sub mengarah ke satu wilayah. Untuk mempelajari endpoint lokasi lebih lanjut, lihat Endpoint Pub/Sub. Untuk mengetahui daftar semua endpoint lokasi untuk Pub/Sub, lihat Daftar endpoint lokasi.
Membuat langganan dengan pengiriman tepat satu kali
Anda dapat membuat langganan dengan pengiriman tepat sekali menggunakan konsol Google Cloud, Google Cloud CLI, library klien, atau Pub/Sub API.
Langganan pull
Konsol
Untuk membuat langganan pull dengan pengiriman tepat satu kali, ikuti langkah-langkah berikut:
Di konsol Google Cloud, buka halaman Langganan.
Klik Buat langganan.
Masukkan ID Langganan.
Pilih atau buat topik dari menu drop-down.
Langganan menerima pesan dari topik.
Di bagian Pengiriman tepat satu kali, pilih Aktifkan pengiriman tepat satu kali.
Klik Create.
gcloud
Untuk membuat langganan pull dengan pengiriman tepat satu kali, gunakan perintah gcloud pubsub subscriptions create
dengan flag --enable-exactly-once-delivery
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --enable-exactly-once-delivery
Ganti kode berikut:
- SUBSCRIPTION_ID: ID langganan yang akan dibuat
- TOPIC_ID: ID topik yang akan dilampirkan ke langganan
REST
Untuk membuat langganan dengan pengiriman tepat satu kali, gunakan metode
projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Ganti kode berikut:
- PROJECT_ID: project ID untuk project tempat langganan akan dibuat
- SUBSCRIPTION_ID: ID langganan yang akan dibuat
Untuk membuat langganan pull dengan pengiriman tepat satu kali, tentukan hal ini dalam isi permintaan:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "enableExactlyOnceDelivery": true, }
Ganti kode berikut:
- PROJECT_ID: project ID untuk project dengan topik
- TOPIC_ID: ID topik yang akan dilampirkan ke langganan
C++
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub C++ API.
C#
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub C# API.
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Go API.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Java API Pub/Sub.
Python
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Python API.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Pub/Sub.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Pub/Sub.
Ruby
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Ruby API.
PHP
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API PHP Pub/Sub.
Berlangganan dengan pengiriman pesan tepat satu kali
Berikut adalah beberapa contoh kode untuk berlangganan dengan pengiriman tepat sekali menggunakan library klien.
Langganan pull
Go
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Go Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Java Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
PHP
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API PHP Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Python
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Python Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Ruby
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Ruby Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
C++
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API C++ Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
C#
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API C# Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Node.js (TypeScript)
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di panduan memulai Pub/Sub menggunakan library klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Memantau langganan pengiriman tepat satu kali
Metrik
subscription/exactly_once_warning_count
mencatat jumlah peristiwa yang
dapat menyebabkan kemungkinan pengiriman ulang (valid atau duplikat). Metrik ini menghitung
jumlah kali Pub/Sub gagal memproses permintaan yang terkait dengan
ID konfirmasi (permintaan ModifyAckDeadline
atau acknowledgment
). Alasan
kegagalan dapat bersifat server atau klien. Misalnya, jika lapisan persistensi
yang digunakan untuk mempertahankan informasi pengiriman tepat satu kali tidak tersedia, lapisan tersebut
akan menjadi peristiwa berbasis server. Jika klien mencoba mengonfirmasi pesan dengan
ID konfirmasi tidak valid, peristiwa tersebut akan menjadi peristiwa berbasis klien.
Memahami metrik
subscription/exactly_once_warning_count
merekam peristiwa yang mungkin atau mungkin tidak
menyebabkan pengiriman ulang yang sebenarnya dan dapat berisi derau berdasarkan perilaku klien. Misalnya: permintaan acknowledgment
atau ModifyAckDeadline
berulang dengan ID
konfirmasi yang tidak valid akan menambah metrik berulang kali.
Metrik berikut juga berguna untuk memahami perilaku klien:
Metrik
subscription/expired_ack_deadlines_count
menunjukkan jumlah masa berlaku ID konfirmasi yang berakhir. Masa berlaku ID konfirmasi dapat menyebabkan kegagalan untuk permintaanModifyAckDeadline
danacknowledgment
.Metrik
service.serviceruntime.googleapis.com/api/request_count
dapat digunakan untuk mencatat kegagalan permintaanModifyAckDeadline
atauacknowledgment
jika permintaan tersebut mencapai Google Cloud, tetapi tidak mencapai Pub/Sub. Ada kegagalan yang tidak akan dicatat oleh metrik ini—misalnya, saat klien terputus dari Google Cloud.
Pada sebagian besar peristiwa kegagalan yang dapat dicoba lagi, library klien yang didukung akan mencoba lagi permintaan secara otomatis.
Kuota
Langganan pengiriman tepat satu kali tunduk pada persyaratan kuota tambahan. Kuota ini diterapkan pada:
- Jumlah pesan yang digunakan dari langganan dengan pengiriman tepat sekali diaktifkan per wilayah.
- Jumlah pesan yang diakui atau yang batas waktunya diperpanjang saat menggunakan langganan dengan pengiriman tepat satu kali yang diaktifkan per region.
Untuk mengetahui informasi selengkapnya tentang kuota ini, lihat tabel dalam topik Kuota.
Pengiriman tepat satu kali dan langganan yang diurutkan
Pub/Sub mendukung pengiriman tepat satu kali dengan pengiriman urut.
Saat menggunakan pengurutan dengan pengiriman tepat satu kali, Pub/Sub mengharapkan konfirmasi untuk diurutkan. Jika konfirmasi tidak berurutan, layanan akan menggagalkan permintaan dengan error sementara. Jika batas waktu konfirmasi berakhir sebelum konfirmasi dalam urutan untuk pengiriman, klien akan menerima pengiriman ulang pesan. Oleh karena itu, saat Anda menggunakan pengurutan dengan pengiriman tepat sekali, throughput klien dibatasi hingga urutan seribu pesan per detik.
Pengiriman tepat satu kali dan langganan push
Pub/Sub hanya mendukung pengiriman tepat satu kali dengan langganan pull.
Klien yang menggunakan pesan dari langganan push mengonfirmasi pesan dengan merespons permintaan push dengan respons yang berhasil. Namun, klien tidak tahu apakah langganan Pub/Sub menerima respons dan memprosesnya. Hal ini berbeda dengan langganan pull, yaitu permintaan konfirmasi dimulai oleh klien dan langganan Pub/Sub akan merespons jika permintaan berhasil diproses. Oleh karena itu, semantik pengiriman tepat satu kali tidak selaras dengan langganan push.
Hal untuk diketahui
Jika batas waktu konfirmasi tidak ditentukan pada waktu CreateSubscription, langganan yang mengaktifkan pengiriman tepat satu kali akan memiliki batas waktu konfirmasi default 60 detik.
Batas waktu konfirmasi default yang lebih lama bermanfaat untuk menghindari pengiriman ulang yang disebabkan oleh peristiwa jaringan. Library klien yang didukung tidak menggunakan batas waktu konfirmasi langganan default.
Langganan pengiriman tepat satu kali memiliki latensi publikasi-ke-langganan yang jauh lebih tinggi dibandingkan dengan langganan reguler.
Jika Anda memerlukan throughput tinggi, klien pengiriman tepat satu kali juga harus menggunakan pull streaming.
Langganan mungkin menerima beberapa salinan pesan yang sama karena duplikat sisi publikasi, meskipun pengiriman tepat sekali diaktifkan. Duplikat sisi publikasi dapat disebabkan oleh beberapa percobaan ulang publikasi unik oleh klien publikasi atau layanan Pub/Sub. Beberapa publikasi unik oleh klien publikasi, di seluruh percobaan ulang, menyebabkan pengiriman ulang dengan ID pesan yang berbeda. Beberapa publikasi unik oleh layanan Pub/Sub, untuk merespons permintaan publikasi klien, akan menyebabkan pengiriman ulang dengan ID pesan yang sama.
Anda dapat mencoba lagi kegagalan di
subscription/exactly_once_warning_count
dan library klien yang didukung akan mencoba lagi secara otomatis. Namun, kegagalan yang terkait dengan ID konfirmasi yang tidak valid tidak dapat dicoba lagi.