Dokumen ini memberikan ringkasan tentang langganan pull, alur kerjanya, dan properti terkait.
Dalam langganan pull, klien pelanggan meminta pesan dari server Pub/Sub.
Mode pull dapat menggunakan salah satu dari dua API layanan, Pull atau StreamingPull. Untuk menjalankan API yang dipilih, Anda dapat memilih library klien tingkat tinggi yang disediakan Google, atau library klien tingkat rendah yang dibuat secara otomatis. Anda juga dapat memilih antara pemrosesan pesan asinkron dan sinkron.
Sebelum memulai
Sebelum membaca dokumen ini, pastikan Anda memahami hal-hal berikut:
Cara kerja Pub/Sub dan berbagai istilah Pub/Sub.
Berbagai jenis langganan yang didukung Pub/Sub dan alasan Anda mungkin ingin menggunakan langganan pull.
Alur kerja langganan pull
Untuk langganan pull, klien pelanggan Anda memulai permintaan ke server Pub/Sub untuk mengambil pesan. Klien pelanggan menggunakan salah satu API berikut:
Sebagian besar klien subscriber tidak membuat permintaan ini secara langsung. Sebagai gantinya, klien mengandalkan library klien tingkat tinggi yang disediakan Trusted Cloud by S3NSyang melakukan permintaan pull streaming secara internal dan mengirimkan pesan secara asinkron. Untuk klien pelanggan yang memerlukan kontrol lebih besar terhadap cara pesan ditarik, Pub/Sub menggunakan library gRPC tingkat rendah yang dibuat secara otomatis. Library ini membuat permintaan pull atau pull streaming secara langsung. Permintaan ini dapat bersifat sinkron atau asinkron.
Dua gambar berikut menunjukkan alur kerja antara klien pelanggan dan langganan pull.


Menarik alur kerja
Alur kerja penarikan adalah sebagai berikut dan merujuk pada Gambar 1:
- Klien pelanggan secara eksplisit memanggil metode
pull
, yang meminta pesan untuk pengiriman. Permintaan ini adalahPullRequest
seperti yang ditunjukkan dalam gambar. Server Pub/Sub merespons dengan nol atau lebih banyak pesan dan ID pengakuan. Respons dengan nol pesan atau dengan error tidak selalu menunjukkan bahwa tidak ada pesan yang tersedia untuk diterima. Respons ini adalah
PullResponse
seperti yang ditunjukkan dalam gambar.Klien pelanggan secara eksplisit memanggil metode
acknowledge
. Klien menggunakan ID konfirmasi yang ditampilkan untuk mengonfirmasi bahwa pesan telah diproses dan tidak perlu dikirimkan lagi.
Untuk satu permintaan penarikan streaming, klien subscriber dapat menerima beberapa respons yang dikembalikan karena koneksi terbuka. Sebaliknya, hanya satu respons yang ditampilkan untuk setiap permintaan penarikan.
Properti langganan pull
Properti yang Anda konfigurasi untuk langganan pull menentukan cara Anda menulis pesan ke langganan. Untuk mengetahui informasi selengkapnya, lihat properti langganan.
Pub/Sub service API
Langganan pull Pub/Sub dapat menggunakan salah satu dari dua API berikut untuk mengambil pesan:
- Tarik
- StreamingPull
Gunakan RPC Acknowledge dan ModifyAckDeadline unary saat Anda menerima pesan menggunakan API ini. Kedua Pub/Sub API dijelaskan di bagian berikut.
StreamingPull API
Jika memungkinkan, library klien Pub/Sub menggunakan StreamingPull untuk throughput maksimum dan latensi terendah. Meskipun Anda mungkin tidak pernah menggunakan StreamingPull API secara langsung, penting untuk mengetahui perbedaannya dengan Pull API.
StreamingPull API mengandalkan koneksi dua arah yang persisten untuk menerima beberapa pesan saat tersedia. Berikut adalah alur kerja:
Klien mengirimkan permintaan ke server untuk membuat koneksi. Jika kuota koneksi terlampaui, server akan menampilkan error kehabisan resource. Library klien mencoba kembali error di luar kuota secara otomatis.
Jika tidak ada error atau kuota koneksi tersedia lagi, server akan terus mengirim pesan ke klien yang terhubung.
Jika atau saat kuota throughput terlampaui, server akan berhenti mengirim pesan. Namun, koneksi tidak terputus. Setiap kali kuota throughput yang tersedia cukup, streaming akan dilanjutkan.
Klien atau server akhirnya menutup koneksi.
StreamingPull API mempertahankan koneksi terbuka. Server Pub/Sub menutup koneksi secara berulang setelah jangka waktu tertentu untuk menghindari koneksi persisten yang berjalan lama. Library klien akan otomatis membuka kembali koneksi StreamingPull.
Pesan dikirim ke koneksi saat tersedia. Oleh karena itu, StreamingPull API meminimalkan latensi dan memaksimalkan throughput untuk pesan.
Baca lebih lanjut metode RPC StreamingPull: StreamingPullRequest dan StreamingPullResponse.
Pull API
API ini adalah RPC unaria tradisional yang didasarkan pada model permintaan dan respons. Satu respons penarikan sesuai dengan satu permintaan penarikan. Berikut alur kerjanya:
Klien mengirimkan permintaan ke server untuk mendapatkan pesan. Jika kuota throughput terlampaui, server akan menampilkan error kehabisan resource.
Jika tidak ada error atau kuota throughput tersedia lagi, server akan membalas dengan nol atau lebih banyak pesan dan ID pengakuan.
Saat menggunakan unary Pull API, respons dengan nol pesan atau dengan error tidak selalu menunjukkan bahwa tidak ada pesan yang tersedia untuk diterima.
Penggunaan Pull API tidak menjamin latensi rendah dan throughput tinggi pesan. Untuk mencapai throughput tinggi dan latensi rendah dengan Pull API, Anda harus memiliki beberapa permintaan luar biasa secara bersamaan. Permintaan baru dibuat saat permintaan lama menerima respons. Merancang solusi seperti itu rentan terhadap error dan sulit dikelola. Sebaiknya gunakan StreamingPull API untuk kasus penggunaan tersebut.
Gunakan Pull API, bukan StreamingPull API, hanya jika Anda memerlukan kontrol ketat atas hal berikut:
- Jumlah pesan yang dapat diproses oleh klien pelanggan
- Memori dan resource klien
Anda juga dapat menggunakan API ini saat pelanggan Anda adalah proxy antara Pub/Sub dan layanan lain yang beroperasi dengan cara yang lebih berorientasi pada penarikan.
Baca selengkapnya tentang metode REST Pull: Metode: projects.subscriptions.pull.
Baca selengkapnya metode Pull RPC: PullRequest dan PullResponse.
Jenis mode pemrosesan pesan
Pilih salah satu mode penarikan berikut untuk klien subscriber Anda.
Mode pull asinkron
Mode pull asinkron memisahkan penerimaan pesan dari pemrosesan pesan di klien pelanggan. Mode ini adalah mode default untuk sebagian besar klien pelanggan. Mode pull asinkron dapat menggunakan StreamingPull API atau Pull API unary. Penarikan asinkron juga dapat menggunakan library klien tingkat tinggi atau library klien tingkat rendah yang dibuat secara otomatis.
Anda dapat mempelajari lebih lanjut library klien nanti dalam dokumen ini.
Mode pull sinkron
Dalam mode penarikan sinkron, penerimaan dan pemrosesan pesan terjadi secara berurutan dan tidak dipisahkan satu sama lain. Oleh karena itu, mirip dengan StreamingPull versus unary Pull API, pemrosesan asinkron menawarkan latensi yang lebih rendah dan throughput yang lebih tinggi daripada pemrosesan sinkron.
Gunakan mode penarikan sinkron hanya untuk aplikasi yang latensi rendah dan throughput tinggi bukan merupakan faktor terpenting dibandingkan dengan beberapa persyaratan lainnya. Misalnya, aplikasi mungkin dibatasi untuk hanya menggunakan model pemrograman sinkron. Atau, aplikasi dengan batasan resource mungkin memerlukan kontrol yang lebih tepat atas memori, jaringan, atau CPU. Dalam kasus tersebut, gunakan mode sinkron dengan unary Pull API.
Library klien Pub/Sub
Pub/Sub menawarkan library klien tingkat tinggi dan tingkat rendah yang dibuat secara otomatis.
Library klien Pub/Sub tingkat tinggi
Library klien tingkat tinggi menyediakan opsi untuk mengontrol batas waktu konfirmasi menggunakan pengelolaan sewa. Opsi ini lebih terperinci daripada saat Anda mengonfigurasi batas waktu konfirmasi menggunakan konsol atau CLI di tingkat langganan. Library klien tingkat tinggi juga menerapkan dukungan untuk fitur seperti pengiriman berurutan, pengiriman tepat sekali, dan kontrol alur.
Sebaiknya gunakan penarikan asinkron dan StreamingPull API dengan library klien tingkat tinggi. Tidak semua bahasa yang didukung untuk Trusted Cloud by S3NS juga mendukung Pull API di library klien tingkat tinggi.
Untuk menggunakan library klien tingkat tinggi, lihat Library klien Pub/Sub.
Library klien Pub/Sub tingkat rendah yang dibuat secara otomatis
Library klien tingkat rendah tersedia untuk kasus saat Anda harus menggunakan Pull API secara langsung. Anda dapat menggunakan pemrosesan sinkron atau asinkron dengan library klien tingkat rendah yang dibuat otomatis. Anda harus membuat kode fitur secara manual seperti pengiriman berurutan, pengiriman tepat satu kali, kontrol alur, dan pengelolaan sewa saat menggunakan library klien tingkat rendah yang dibuat otomatis.
Anda dapat menggunakan model pemrosesan sinkron saat menggunakan library klien yang dibuat otomatis tingkat rendah untuk semua bahasa yang didukung. Anda dapat menggunakan library klien tingkat rendah yang dibuat otomatis dan penarikan sinkron dalam kasus ketika penggunaan Pull API secara langsung lebih tepat. Misalnya, Anda mungkin memiliki logika aplikasi yang ada yang mengandalkan model ini.
Untuk menggunakan library klien tingkat rendah yang dibuat otomatis secara langsung, lihat Ringkasan API Pub/Sub.
Contoh kode library klien
StreamingPull dan contoh kode library klien tingkat tinggi
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
Contoh berikut menggunakan library klien Go Pub/Sub versi utama (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.
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.
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.
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.
Ruby
Contoh berikut menggunakan library klien Pub/Sub Ruby v3. Jika Anda masih menggunakan library v2, lihat panduan migrasi ke v3. Untuk melihat daftar contoh kode Ruby v2, lihat contoh kode yang tidak digunakan lagi.
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.
Mengambil atribut kustom menggunakan library klien tingkat tinggi
Contoh berikut menunjukkan cara menarik pesan secara asinkron dan mengambil atribut kustom dari metadata.
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
Contoh berikut menggunakan library klien Go Pub/Sub versi utama (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.
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.
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.
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.
Ruby
Contoh berikut menggunakan library klien Pub/Sub Ruby v3. Jika Anda masih menggunakan library v2, lihat panduan migrasi ke v3. Untuk melihat daftar contoh kode Ruby v2, lihat contoh kode yang tidak digunakan lagi.
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.
Menangani error menggunakan library klien tingkat tinggi
Contoh berikut menunjukkan cara menangani error yang muncul saat berlangganan pesan.
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
Contoh berikut menggunakan library klien Go Pub/Sub versi utama (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.
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.
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.
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.
Ruby
Contoh berikut menggunakan library klien Go Pub/Sub versi utama (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.
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.
Contoh kode penarikan unary
Berikut beberapa contoh kode untuk menarik dan mengonfirmasi sejumlah tetap pesan.
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.
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.
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.
PHP
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
Contoh berikut menggunakan library klien Pub/Sub Ruby v3. Jika Anda masih menggunakan library v2, lihat panduan migrasi ke v3. Untuk melihat daftar contoh kode Ruby v2, lihat contoh kode yang tidak digunakan lagi.
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.
Protokol
Permintaan:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:pull
{
"returnImmediately": "false",
"maxMessages": "1"
}
Respons:
200 OK
{
"receivedMessages": [{
"ackId": "dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK...",
"message": {
"data": "SGVsbG8gQ2xvdWQgUHViL1N1YiEgSGVyZSBpcyBteSBtZXNzYWdlIQ==",
"messageId": "19917247034"
}
}]
}
Permintaan:
POST https://pubsub.googleapis.com/v1/projects/myproject/subscriptions/mysubscription:acknowledge
{
"ackIds": [
"dQNNHlAbEGEIBERNK0EPKVgUWQYyODM2LwgRHFEZDDsLRk1SK..."
]
}
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.
Pub/Sub mengirimkan daftar pesan. Jika daftar memiliki beberapa pesan, Pub/Sub akan mengurutkan pesan dengan kunci pengurutan yang sama. Berikut adalah beberapa peringatan penting:
Menetapkan nilai untuk
max_messages
dalam permintaan tidak menjamin bahwamax_messages
akan ditampilkan, meskipun ada banyak pesan dalam backlog. Pub/Sub Pull API mungkin menampilkan kurang darimax_messages
untuk mengurangi latensi pengiriman pesan yang siap dikirim.Respons pull yang disertai dengan 0 pesan tidak boleh digunakan sebagai indikator bahwa tidak ada pesan dalam backlog. Respons dapat diperoleh dengan 0 pesan dan memiliki permintaan berikutnya yang menampilkan pesan.
Untuk mencapai latensi pengiriman pesan yang rendah dengan mode pull unary, sangat penting untuk memiliki banyak permintaan pull yang belum diselesaikan secara bersamaan. Seiring dengan peningkatan throughput topik, diperlukan lebih banyak permintaan penarikan. Secara umum, mode StreamingPull lebih disukai untuk aplikasi yang sensitif terhadap latensi.
Kuota dan batas
Koneksi Pull dan StreamingPull tunduk pada kuota dan batas. Untuk mengetahui informasi selengkapnya, lihat Kuota dan batas Pub/Sub.
Langkah berikutnya
Buat langganan pull untuk topik Anda.
Memecahkan masalah langganan pull.
Buat atau ubah langganan dengan gcloud CLI.
Buat atau ubah langganan dengan REST API.
Buat atau ubah langganan dengan RPC API.