Halaman ini menjelaskan cara menerima dan mengonfirmasi pesan menggunakan semantik tepat satu kali. 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.
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 tinggi, C# v3.2.0 atau yang lebih tinggi, C++ v2.1.0, Go v1}atau versi lebih tinggi {1.3.1}v1, dan lebih tinggi {10.1.0}v1.v1.
Pengiriman tepat satu kali
Pub/Sub mendukung pengiriman tepat satu kali, dalam region cloud, berdasarkan ID pesan unik yang ditentukan Pub/Sub.
Saat fitur ini diaktifkan, Pub/Sub akan memberikan hal berikut:
Tidak ada pengiriman ulang yang terjadi setelah pesan berhasil dikonfirmasi.
Pengiriman ulang tidak akan terjadi saat pesan belum diproses. Pesan dianggap belum terselesaikan hingga batas waktu konfirmasi berakhir atau pesan dikonfirmasi.
Jika ada beberapa pengiriman yang valid, karena batas waktu konfirmasi berakhir masa berlaku atau konfirmasi negatif yang dimulai klien, hanya ID konfirmasi terbaru yang dapat digunakan untuk mengonfirmasi pesan. Setiap permintaan dengan ID konfirmasi sebelumnya akan gagal.
Penayangan ulang versus duplikat
Penting untuk memahami perbedaan antara pengiriman ulang yang diharapkan dan yang tidak terduga.
Pengiriman ulang dapat terjadi karena penerimaan pesan negatif yang dimulai oleh 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 dan memaksa percobaan ulang.
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 yang mengaktifkan pengiriman tepat satu kali tidak akan 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 senyap.
Library klien yang didukung memiliki antarmuka untuk menetapkan waktu ekstensi lease minimum (contoh: Go). Anda harus menetapkan nilai untuk ekstensi sewa minimum ke angka yang tinggi untuk menghindari habisnya masa berlaku konfirmasi terkait jaringan. Nilai maksimum ditetapkan pada 600 detik.
Nilai dan rentang default untuk variabel yang terkait dengan pengiriman tepat satu kali dan nama variabel mungkin berbeda di berbagai library klien. Misalnya, dalam library klien Java, variabel berikut mengontrol pengiriman tepat satu kali.
Variabel | Deskripsi | Nilai |
---|---|---|
setEnableExactlyOnceDelivery |
Mengaktifkan atau menonaktifkan pengiriman tepat satu kali. | true (benar) atau false (salah) Default=false |
minDurationPerAckExtension |
Waktu minimum dalam detik yang digunakan untuk memperpanjang batas waktu konfirmasi modifikasi. | Rentang=0 hingga 600 Default=tidak ada |
maxDurationPerAckExtension |
Waktu maksimum dalam detik yang digunakan untuk memperpanjang batas waktu konfirmasi modifikasi. | Rentang=0 hingga 600 Default=tidak ada |
Dalam kasus pengiriman tepat satu kali, permintaan modifyAckDeadline
atau acknowledgment
ke Pub/Sub akan gagal saat ID konfirmasi sudah tidak berlaku lagi. Dalam kasus tersebut, layanan akan menganggap ID konfirmasi yang telah habis masa berlakunya sebagai tidak valid, karena pengiriman yang lebih baru mungkin sedang berlangsung. Hal ini merupakan desain untuk
pengiriman tepat satu kali. Anda kemudian melihat permintaan acknowledgment
dan ModifyAckDeadline
menampilkan
respons INVALID_ARGUMENT
. Jika pengiriman tepat satu kali dinonaktifkan, permintaan ini akan menampilkan OK
jika ID konfirmasi yang sudah tidak berlaku lagi.
Untuk memastikan bahwa permintaan acknowledgment
dan ModifyAckDeadline
memiliki ID konfirmasi
yang valid, sebaiknya tetapkan nilai untuk
minDurationPerAckExtension
ke angka yang tinggi.
Membuat langganan dengan pengiriman tepat satu kali
Anda dapat membuat langganan dengan pengiriman tepat satu kali 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 Persis sekali pengiriman, pilih Aktifkan pengiriman tepat sekali.
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 untuk 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 untuk dilampirkan ke langganan
C++
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di Panduan Memulai: Menggunakan Library Klien. Untuk 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 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 informasi selengkapnya, lihat dokumentasi referensi API Pub/Sub Java.
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 informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Node.js API.
Node.js
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan Memulai: Menggunakan Library Klien. Untuk informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Node.js API.
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 Pub/Sub PHP API.
Berlangganan dengan pengiriman pesan tepat satu kali
Berikut adalah beberapa contoh kode untuk berlangganan 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 informasi selengkapnya, lihat dokumentasi referensi API Go Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Java
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di panduan memulai Pub/Sub menggunakan library klien. Untuk informasi selengkapnya, lihat dokumentasi referensi API Java Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca 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 informasi selengkapnya, lihat dokumentasi referensi API Node.js Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
PHP
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan PHP di panduan memulai Pub/Sub menggunakan library klien. Untuk informasi selengkapnya, lihat dokumentasi referensi API PHP Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Python
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di panduan memulai Pub/Sub menggunakan library klien. Untuk informasi selengkapnya, lihat dokumentasi referensi API Python Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
Ruby
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Ruby di panduan memulai Pub/Sub menggunakan library klien. Untuk informasi selengkapnya, lihat dokumentasi referensi API Ruby Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
C++
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di panduan memulai Pub/Sub menggunakan library klien. Untuk informasi selengkapnya, lihat dokumentasi referensi API C++ Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca Menyiapkan autentikasi untuk lingkungan pengembangan lokal.
C#
Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di panduan memulai Pub/Sub menggunakan library klien. Untuk informasi selengkapnya, lihat dokumentasi referensi API C# Pub/Sub.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca 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 informasi selengkapnya, lihat dokumentasi referensi Pub/Sub Node.js API.
Untuk melakukan autentikasi ke Pub/Sub, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, baca 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 berapa kali Pub/Sub gagal memproses permintaan yang terkait dengan ID konfirmasi (permintaan ModifyAckDeadline
atau acknowledgment
). Penyebab kegagalan dapat disebabkan oleh server atau klien. Misalnya, jika lapisan persistensi yang digunakan untuk mempertahankan informasi pengiriman yang tepat satu kali tidak tersedia, lapisan tersebut akan menjadi peristiwa berbasis server. Jika klien mencoba mengonfirmasi pesan dengan ID konfirmasi yang tidak valid, pesan tersebut akan menjadi peristiwa berbasis klien.
Memahami metrik
subscription/exactly_once_warning_count
menangkap 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 dalam memahami perilaku klien:
Metrik
subscription/expired_ack_deadlines_count
menunjukkan jumlah masa berlaku ID konfirmasi. Akhir masa berlaku ID konfirmasi dapat menyebabkan kegagalan untuk permintaanModifyAckDeadline
danacknowledgment
.Metrik
service.serviceruntime.googleapis.com/api/request_count
dapat digunakan untuk merekam 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.
Dalam sebagian besar kasus kegagalan yang dapat dicoba lagi, library klien yang didukung akan mencoba lagi permintaan tersebut secara otomatis.
Kuota
Langganan pengiriman tepat satu kali tunduk pada persyaratan kuota tambahan. Kuota ini diberlakukan pada:
- Jumlah pesan yang digunakan dari langganan dengan pengiriman tepat satu kali yang diaktifkan per region.
- Jumlah pesan yang dikonfirmasi atau yang batas waktunya diperpanjang saat menggunakan langganan dengan pengiriman tepat satu kali yang diaktifkan per region.
Untuk mengetahui informasi lebih lanjut terkait kuota ini, lihat tabel dalam topik Kuota.
Pengiriman tepat satu kali dan langganan yang dipesan
Pub/Sub mendukung pengiriman tepat satu kali dengan pengiriman yang dipesan.
Saat menggunakan pengurutan dengan pengiriman tepat satu kali, Pub/Sub mengharapkan konfirmasi yang berurutan. Jika konfirmasi tidak sesuai urutan, layanan akan menggagalkan permintaan dengan error sementara. Jika batas waktu konfirmasi berakhir sebelum konfirmasi sesuai urutan untuk pengiriman, klien akan menerima pengiriman ulang pesan. Oleh karena itu, ketika Anda menggunakan pengurutan dengan pengiriman tepat satu kali, throughput klien dibatasi hingga urutan seribu 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 tersebut 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, yang mana permintaan konfirmasi dimulai oleh klien dan langganan Pub/Sub merespons jika permintaan berhasil diproses. Karena itu, semantik pengiriman yang tepat satu kali tidak selaras dengan langganan push.
Hal untuk diketahui
Jika batas waktu konfirmasi tidak ditentukan pada waktu CreateSubscription, tepatnya setelah pengiriman yang diaktifkan akan memiliki batas waktu konfirmasi default 60 detik.
Batas waktu konfirmasi default yang lebih lama akan 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 untuk berlangganan yang jauh lebih tinggi dibandingkan dengan langganan reguler.
Jika Anda memerlukan throughput yang tinggi, klien pengiriman yang tepat satu kali juga harus menggunakan streaming pull.
Langganan mungkin menerima beberapa salinan pesan yang sama karena adanya duplikat sisi publikasi, meskipun pengiriman tepat satu kali diaktifkan. Duplikat sisi publikasi dapat terjadi karena beberapa percobaan ulang publikasi unik oleh klien publikasi atau layanan Pub/Sub. Beberapa publikasi unik oleh klien penayang, di semua percobaan ulang, akan 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 ulang 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.