Dokumen ini memberikan informasi tentang memublikasikan pesan.
Aplikasi penayang membuat dan mengirim pesan ke topik. Pub/Sub menawarkan pengiriman pesan minimal satu kali dan pengurutan upaya terbaik kepada pelanggan yang ada.
Alur umum untuk aplikasi penayang adalah:
- Buat pesan yang berisi data Anda.
- Kirim permintaan ke server Pub/Sub untuk memublikasikan pesan ke topik yang ditentukan.
Sebelum memulai
Sebelum mengonfigurasi alur kerja publikasi, pastikan Anda telah menyelesaikan tugas berikut:
- Pelajari alur kerja publikasi.
- Buat topik.
- Pilih dan buat langganan.
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan guna memublikasikan pesan ke topik, minta administrator Anda untuk memberi Anda peran IAM Pub/Sub Publisher (roles/pubsub.publisher
) di topik.
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.
Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.
Anda memerlukan izin tambahan untuk membuat atau memperbarui topik dan langganan.
Format pesan
Pesan terdiri dari kolom dengan data dan metadata pesan. Tentukan setidaknya salah satu dari berikut ini dalam pesan:
- Data pesan
- Kunci pengurutan
- Atribut dengan metadata tambahan
Layanan Pub/Sub menambahkan kolom berikut ke pesan:
- ID pesan yang unik untuk topik
- Stempel waktu saat layanan Pub/Sub menerima pesan
Untuk mempelajari pesan lebih lanjut, lihat Format pesan.
Memublikasikan pesan
Anda dapat memublikasikan pesan dengan Google Cloud konsol, Google Cloud CLI, Pub/Sub API, dan library klien. Library klien dapat memublikasikan pesan secara asinkron.
Contoh berikut menunjukkan cara memublikasikan pesan ke topik.
Konsol
Untuk memublikasikan pesan, ikuti langkah-langkah berikut:
Di konsol Google Cloud , buka halaman Pub/Sub topics.
Klik ID topik.
Di halaman Topic details di bagian Messages, klik Publish message.
Di kolom Isi pesan, masukkan data pesan.
Klik Publikasikan.
gcloud
Untuk memublikasikan pesan, gunakan perintah gcloud pubsub topics publish:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Ganti kode berikut:
- TOPIC_ID: ID topik
- MESSAGE_DATA: string dengan data pesan
- KEY: kunci atribut pesan
- VALUE: nilai untuk kunci atribut pesan
REST
Untuk memublikasikan pesan, kirim permintaan POST seperti berikut:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Ganti kode berikut:
- PROJECT_ID: project ID project dengan topik
- TOPIC_ID: ID topik
Tentukan kolom berikut dalam isi permintaan:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Ganti kode berikut:
- KEY: kunci atribut pesan
- VALUE: nilai untuk kunci atribut pesan
- MESSAGE_DATA: string berenkode base64 dengan data pesan
Pesan harus berisi kolom data yang tidak kosong atau minimal satu atribut.
Jika permintaan berhasil, responsnya adalah objek JSON dengan ID pesan. Contoh berikut adalah respons dengan ID pesan:
{ "messageIds": [ "19916711285", ] }
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.
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.
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.
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
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.
Setelah Anda memublikasikan pesan, layanan Pub/Sub akan menampilkan ID pesan ke penayang.
Menggunakan atribut untuk memublikasikan pesan
Anda dapat menyematkan atribut kustom sebagai metadata dalam pesan Pub/Sub. Atribut digunakan untuk memberikan informasi tambahan tentang pesan, seperti prioritas, asal, atau tujuannya. Atribut juga dapat digunakan untuk memfilter pesan pada langganan.
Ikuti panduan berikut untuk menggunakan atribut dalam pesan Anda:
Atribut dapat berupa string teks atau string byte.
Anda dapat memiliki maksimal 100 atribut per pesan.
Kunci atribut tidak boleh diawali dengan
goog
dan tidak boleh melebihi 256 byte.Nilai atribut tidak boleh melebihi 1024 byte.
Skema pesan dapat ditampilkan sebagai berikut:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Untuk duplikat sisi publikasi, Anda dapat melihat nilai publishTime
yang berbeda untuk pesan asli sisi klien yang sama, meskipun dengan messageId
yang sama.
Skema JSON PubsubMessage
dipublikasikan sebagai bagian dari dokumentasi
REST dan
RPC. Anda dapat menggunakan atribut kustom untuk stempel waktu peristiwa.
Contoh berikut menunjukkan cara memublikasikan pesan dengan atribut ke topik.
Konsol
Untuk memublikasikan pesan dengan atribut, ikuti langkah-langkah berikut:
Di konsol Google Cloud , buka halaman Topics.
Klik topik yang ingin Anda publikasikan pesannya.
Di halaman detail topik, klik Messages.
Klik Publikasikan pesan.
Di kolom Isi pesan, masukkan data pesan.
Di bagian Atribut pesan, klik Tambahkan atribut.
Masukkan pasangan nilai kunci.
Tambahkan atribut lainnya, jika diperlukan.
Klik Publikasikan.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
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.
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
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.
Menggunakan kunci pengurutan untuk memublikasikan pesan
Untuk menerima pesan secara berurutan di klien pelanggan, Anda harus mengonfigurasi klien penerbit untuk memublikasikan pesan dengan kunci pengurutan.
Untuk memahami konsep pengurutan kunci, lihat Pesan pesanan.
Berikut adalah daftar pertimbangan utama untuk pengiriman pesan yang diurutkan bagi klien penayang:
Pengurutan di satu klien penerbit: Saat satu klien penerbit memublikasikan pesan dengan kunci pengurutan yang sama di wilayah yang sama, klien pelanggan menerima pesan tersebut dalam urutan persis seperti saat pesan tersebut dipublikasikan. Misalnya, jika klien penayang memublikasikan pesan 1, 2, dan 3 dengan kunci pengurutan A, klien pelanggan akan menerimanya dalam urutan 1, 2, 3.
Pengurutan di beberapa klien penayang: Urutan pesan yang diterima oleh klien pelanggan konsisten dengan urutan saat pesan tersebut dipublikasikan di wilayah yang sama, meskipun beberapa klien penayang menggunakan kunci pengurutan yang sama. Namun, klien penayang itu sendiri tidak mengetahui pesanan ini.
Misalnya, jika klien penayang X dan Y masing-masing memublikasikan pesan dengan kunci pengurutan A, dan pesan X diterima oleh Pub/Sub sebelum pesan Y, maka semua klien pelanggan menerima pesan X sebelum pesan Y. Jika diperlukan urutan pesan yang ketat di berbagai klien penerbit, klien tersebut harus menerapkan mekanisme koordinasi tambahan untuk memastikan mereka tidak memublikasikan pesan dengan kunci pengurutan yang sama secara bersamaan. Misalnya, layanan penguncian dapat digunakan untuk mempertahankan kepemilikan kunci pemesanan saat memublikasikan.
Pengurutan di seluruh region: Jaminan pengiriman yang diurutkan hanya berlaku jika publikasi untuk kunci pengurutan berada di region yang sama. Jika aplikasi penayang Anda memublikasikan pesan dengan kunci pengurutan yang sama ke berbagai wilayah, urutan tidak dapat diterapkan di seluruh publikasi tersebut. Pelanggan dapat terhubung ke region mana pun dan jaminan pemesanan 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 umumnya memastikan Anda berinteraksi dengan satu region.
Saat menjalankan aplikasi penayang 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 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.
Kegagalan publikasi: Jika publikasi dengan kunci pengurutan gagal, pesan yang diantrekan dengan kunci pengurutan yang sama di penayang akan gagal, termasuk permintaan publikasi mendatang dengan kunci pengurutan ini. Anda harus melanjutkan publikasi dengan kunci pengurutan jika terjadi kegagalan tersebut. Untuk contoh melanjutkan operasi publikasi, lihat Coba lagi permintaan dengan kunci pengurutan.
Anda dapat memublikasikan pesan dengan kunci pengurutan menggunakan konsol Google Cloud , Google Cloud CLI, Pub/Sub API, atau library klien.
Konsol
Untuk memublikasikan pesan dengan atribut, ikuti langkah-langkah berikut:
Di konsol Google Cloud , buka halaman Topics.
Klik topik yang ingin Anda publikasikan pesannya.
Di halaman detail topik, klik Messages.
Klik Publikasikan pesan.
Di kolom Isi pesan, masukkan data pesan.
Di kolom Pengurutan pesan, masukkan kunci pengurutan.
Klik Publikasikan.
gcloud
Untuk memublikasikan pesan dengan kunci pengurutan, gunakan perintah
gcloud pubsub topics publish
dan flag --ordering-key
:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Ganti kode berikut:
- TOPIC_ID: ID topik
- MESSAGE_DATA: string dengan data pesan
- ORDERING_KEY: string dengan kunci pengurutan
REST
Untuk memublikasikan pesan dengan kunci pengurutan, kirim permintaan POST seperti berikut:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Ganti kode berikut:
- PROJECT_ID: project ID project dengan topik
- TOPIC_ID: ID topik
Tentukan kolom berikut dalam isi permintaan:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Ganti kode berikut:
- KEY: kunci atribut pesan
- VALUE: nilai untuk kunci atribut pesan
- MESSAGE_DATA: string berenkode base64 dengan data pesan
- ORDERING_KEY: string dengan kunci pengurutan
Pesan harus berisi kolom data yang tidak kosong atau minimal satu atribut.
Jika permintaan berhasil, responsnya adalah objek JSON dengan ID pesan. Contoh berikut adalah respons dengan ID pesan:
{ "messageIds": [ "19916711285", ] }
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.
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
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.
Memantau penayang
Cloud Monitoring menyediakan sejumlah metrik untuk memantau topik.
Untuk memantau topik dan mempertahankan penayang yang sehat, lihat Mempertahankan penayang yang sehat.
Langkah berikutnya
Untuk membatasi lokasi tempat Pub/Sub menyimpan data pesan, lihat Membatasi lokasi resource Pub/Sub.
Untuk memublikasikan pesan dengan skema, lihat Ringkasan skema.
Untuk mempelajari cara mengonfigurasi opsi pengiriman lanjutan, lihat hal berikut: