Halaman ini menjelaskan cara menerima dan mengonfirmasi pesan menggunakan fitur tepat satu kali Pub/Sub, yang memungkinkan Anda melacak dan mencegah pemrosesan pesan duplikat. Jika fitur diaktifkan, Pub/Sub menyediakan semantik berikut:
Subscriber dapat menentukan apakah konfirmasi pesan berhasil.
Tidak ada pengiriman ulang setelah pesan berhasil dikonfirmasi.
Pengiriman ulang tidak terjadi saat pesan belum terkirim. Pesan dianggap belum selesai hingga batas waktu konfirmasi berakhir atau pesan dikonfirmasi.
Jika ada beberapa pengiriman yang valid, karena masa berlaku batas waktu konfirmasi berakhir atau konfirmasi negatif yang dimulai klien, hanya ID konfirmasi terbaru yang dapat digunakan untuk mengonfirmasi pesan. Semua permintaan dengan ID konfirmasi sebelumnya akan gagal.
Dengan mengaktifkan pemrosesan tepat satu kali, pelanggan dapat memastikan pesan diproses satu kali dengan mengikuti pedoman berikut:
Mengonfirmasi 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 jika pengiriman 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.139.0 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
Penting untuk memahami perbedaan antara pengiriman ulang yang diharapkan dan tidak diharapkan.
Pengiriman ulang dapat terjadi karena penolakan negatif yang dimulai klien terhadap pesan 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 terjadi 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 seperti itu, kegagalan konfirmasi dapat menyebabkan pengiriman ulang pesan secara diam-diam.
Library klien yang didukung memiliki antarmuka untuk menyetel waktu perpanjangan sewa minimum (contoh: Go). Anda harus menetapkan nilai untuk perpanjangan masa sewa minimum ke angka yang tinggi untuk menghindari masa berlaku pengakuan terkait jaringan berakhir. Nilai maksimum ditetapkan pada 600 detik.
Jika Anda menggunakan library klien Java dan menginisialisasi pelanggan dengan Channel gRPC kustom menggunakan metode
setChannelProvider()
, sebaiknya Anda juga menetapkanmaxInboundMetadataSize
ke setidaknya 1 MB saat membuatTransportChannelProvider
. Untuk konfigurasi ini, Anda dapat menggunakan metodeInstantiatingGrpcChannelProvider.Builder.setMaxInboundMetadataSize()
atauManagedChannelBuilder.maxInboundMetadataSize()
.
Nilai dan rentang default untuk variabel yang terkait dengan pengiriman tepat satu kali 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. | benar atau salah 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 satu kali, permintaan modifyAckDeadline
atau acknowledgment
ke Pub/Sub gagal saat ID pengakuan sudah berakhir. Dalam kasus seperti itu, layanan menganggap ID konfirmasi yang sudah tidak berlaku sebagai tidak valid, karena pengiriman yang lebih baru mungkin sudah dalam proses. Hal ini sesuai dengan desain untuk pengiriman tepat satu kali. Kemudian, Anda akan melihat permintaan acknowledgment
dan ModifyAckDeadline
menampilkan respons INVALID_ARGUMENT
. Jika pengiriman tepat satu kali dinonaktifkan, permintaan ini akan menampilkan OK
jika ID konfirmasi telah habis masa berlakunya.
Untuk memastikan bahwa permintaan acknowledgment
dan ModifyAckDeadline
memiliki ID konfirmasi yang valid, pertimbangkan untuk menetapkan nilai minDurationPerAckExtension
ke angka yang tinggi.
Pertimbangan regional
Jaminan pengiriman tepat satu kali hanya berlaku saat pelanggan terhubung ke layanan di region yang sama. Jika aplikasi pelanggan Anda tersebar di beberapa wilayah, hal ini dapat menyebabkan pengiriman pesan duplikat, meskipun pengiriman tepat satu kali diaktifkan. Penerbit dapat mengirim pesan ke wilayah mana pun dan jaminan pengiriman tepat satu kali tetap dipertahankan.
Saat Anda menjalankan aplikasi dalam Google Cloud, secara default aplikasi tersebut terhubung ke endpoint Pub/Sub di region yang sama. Oleh karena itu, menjalankan aplikasi Anda di satu region dalam Google Cloud biasanya memastikan Anda berinteraksi dengan satu region.
Saat menjalankan aplikasi pelanggan di luar Google Cloud atau di beberapa region, Anda dapat menjamin bahwa Anda terhubung ke satu region dengan menggunakan endpoint lokasi saat mengonfigurasi klien Pub/Sub. Semua endpoint lokasi untuk Pub/Sub mengarah ke satu region. Untuk mempelajari lebih lanjut endpoint lokasi, lihat Endpoint Pub/Sub. Untuk mengetahui daftar semua endpoint berbasis lokasi untuk Pub/Sub, lihat Daftar endpoint berbasis lokasi.
Membuat langganan dengan pengiriman tepat satu kali
Anda dapat membuat langganan dengan pengiriman persis sekali menggunakan Google Cloud konsol, 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 Subscriptions.
Klik Buat langganan.
Masukkan ID Langganan.
Pilih atau buat topik dari menu drop-down.
Langganan menerima pesan dari topik.
Di bagian Exactly once delivery, pilih Enable exactly once delivery.
Klik Buat.
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 ini di 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 API C# Pub/Sub.
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 Pub/Sub Java API.
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 API Ruby Pub/Sub.
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 beberapa contoh kode untuk berlangganan dengan pengiriman tepat satu kali 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 pengiriman ulang (valid atau duplikat). Metrik ini menghitung
waktu Pub/Sub gagal memproses permintaan yang terkait dengan
ID pengakuan (permintaan ModifyAckDeadline
atau acknowledgment
). Alasan
kegagalan dapat berupa berbasis server atau klien. Misalnya, jika lapisan persistensi yang digunakan untuk mempertahankan informasi pengiriman tepat satu kali tidak tersedia, maka peristiwa tersebut akan menjadi peristiwa berbasis server. Jika klien mencoba mengonfirmasi pesan dengan
ID konfirmasi yang tidak valid, hal ini akan menjadi peristiwa berbasis klien.
Memahami metrik
subscription/exactly_once_warning_count
mencatat peristiwa yang mungkin atau mungkin tidak
menyebabkan pengiriman ulang yang sebenarnya dan dapat menjadi tidak relevan berdasarkan perilaku klien. Misalnya: permintaan acknowledgment
atau ModifyAckDeadline
yang berulang dengan ID konfirmasi yang tidak valid akan meningkatkan metrik berulang kali.
Metrik berikut juga berguna untuk memahami perilaku klien:
Metrik
subscription/expired_ack_deadlines_count
menampilkan jumlah masa berlaku ID konfirmasi yang berakhir. Masa berlaku ID pengakuan dapat menyebabkan kegagalan untuk permintaanModifyAckDeadline
danacknowledgment
.service.serviceruntime.googleapis.com/api/request_count
dapat digunakan untuk mencatat kegagalan permintaanModifyAckDeadline
atauacknowledgment
jika permintaan 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 kasus 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 satu kali diaktifkan per wilayah.
- Jumlah pesan yang dikonfirmasi atau yang batas waktunya diperpanjang saat menggunakan langganan dengan pengiriman tepat satu kali yang diaktifkan per wilayah.
Untuk mengetahui informasi selengkapnya terkait kuota ini, lihat tabel dalam topik Kuota.
Pengiriman tepat satu kali dan langganan yang diurutkan
Pub/Sub mendukung pengiriman tepat satu kali dengan pengiriman berurutan.
Saat menggunakan pengurutan dengan pengiriman tepat satu kali, Pub/Sub mengharapkan pengakuan dalam urutan. Jika konfirmasi tidak berurutan, layanan akan gagal memenuhi permintaan dengan error sementara. Jika batas waktu konfirmasi berakhir sebelum konfirmasi sesuai urutan untuk pengiriman, klien akan menerima pengiriman ulang pesan. Oleh karena itu, saat Anda menggunakan pengurutan dengan pengiriman tepat satu kali, throughput klien dibatasi hingga urutan ribuan pesan per detik.
Pengiriman tepat satu kali dan langganan push
Pub/Sub mendukung pengiriman tepat satu kali hanya 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, di mana permintaan konfirmasi dimulai oleh klien dan langganan Pub/Sub merespons jika permintaan berhasil diproses. Karena itu, semantik pengiriman tepat satu kali tidak selaras dengan baik 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 publish-to-subscribe yang jauh lebih tinggi dibandingkan dengan langganan reguler.
Jika Anda memerlukan throughput tinggi, klien pengiriman tepat satu kali juga harus menggunakan tarikan streaming.
Langganan dapat menerima beberapa salinan pesan yang sama karena duplikat sisi publikasi, meskipun pengiriman tepat satu kali diaktifkan. Duplikat sisi publikasi dapat disebabkan oleh beberapa percobaan ulang publikasi unik oleh klien publikasi atau layanan Pub/Sub. Beberapa publikasi unik oleh klien penerbitan, di seluruh percobaan ulang, menyebabkan pengiriman ulang dengan ID pesan yang berbeda. Beberapa publikasi unik oleh layanan Pub/Sub, untuk merespons permintaan publikasi klien, 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 kegagalan ini secara otomatis. Namun, kegagalan yang terkait dengan ID konfirmasi yang tidak valid tidak dapat dicoba lagi.