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 dengan 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-tugas berikut:
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan guna memublikasikan pesan ke topik,
minta administrator untuk memberi Anda
peran IAM Pub/Sub Publisher (roles/pubsub.publisher
) pada 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 hal berikut 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 konsol Google Cloud, 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 pada 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 setidaknya 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 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.
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 Pub/Sub Ruby API.
Setelah Anda memublikasikan pesan, layanan Pub/Sub akan menampilkan ID pesan kepada 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 di 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 1.024 byte.
Skema pesan dapat direpresentasikan sebagai berikut:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Untuk duplikat sisi publikasi, Anda mungkin melihat nilai publishTime
yang berbeda
untuk pesan asli sisi klien yang sama, bahkan 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 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.
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 Pub/Sub Ruby API.
Menggunakan kunci pengurutan untuk memublikasikan pesan
Untuk menerima pesan secara berurutan di klien pelanggan, Anda harus mengonfigurasi klien penayang untuk memublikasikan pesan dengan kunci pengurutan.
Untuk memahami konsep pengurutan kunci, lihat Pesan urutan.
Berikut adalah daftar pertimbangan utama untuk pesan terurut bagi klien penayang:
Pengurutan di satu klien penayang: Saat satu klien penayang memublikasikan pesan dengan kunci pengurutan yang sama di wilayah yang sama, klien pelanggan akan menerima pesan tersebut dalam urutan yang sama persis dengan urutan publikasinya. 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 perintah 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, semua klien pelanggan akan menerima pesan X sebelum pesan Y. Jika urutan pesan yang ketat di berbagai klien penayang diperlukan, 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 pengurutan saat memublikasikan.
Pemesanan di seluruh region: Jaminan pengiriman yang dipesan hanya berlaku saat publikasi untuk kunci pengurutan berada di region yang sama. Jika aplikasi penayang Anda memublikasikan pesan dengan kunci pengurutan yang sama ke wilayah yang berbeda, urutan tidak dapat diterapkan di seluruh publikasi tersebut. Pelanggan dapat terhubung ke region mana pun dan jaminan pengurutan tetap 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 penayang di luar Google Cloud atau di beberapa region, Anda dapat memastikan bahwa Anda terhubung ke satu region menggunakan endpoint lokasi saat mengonfigurasi klien Pub/Sub. Semua endpoint lokasi untuk Pub/Sub mengarah ke satu region. Untuk mempelajari endpoint lokasi lebih lanjut, lihat Endpoint Pub/Sub. Untuk mengetahui daftar semua endpoint lokasi untuk Pub/Sub, lihat Daftar endpoint lokasi.
Kegagalan publikasi: Jika publikasi dengan kunci pengurutan gagal, pesan yang diantrekan dari kunci pengurutan yang sama di penayang akan gagal, termasuk permintaan publikasi mendatang dari kunci pengurutan ini. Anda harus melanjutkan publikasi dengan kunci pengurutan saat kegagalan tersebut terjadi. Untuk mengetahui contoh melanjutkan operasi publikasi, lihat Mencoba ulang 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 setidaknya 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 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.
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 Pub/Sub Ruby API.
Memantau penayang
Cloud Monitoring menyediakan sejumlah metrik untuk memantau topik.
Untuk memantau topik dan mempertahankan penayang yang sehat, lihat Mempertahankan penayang yang sehat.
Langkah selanjutnya
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: