Dokumen ini memberikan informasi tentang cara memublikasikan pesan.
Aplikasi penerbit membuat dan mengirim pesan ke topik. Pub/Sub menawarkan pengiriman pesan setidaknya satu kali dan upaya pengurutan terbaik kepada pelanggan yang ada.
Alur umum untuk aplikasi penerbit adalah:
- Buat pesan yang berisi data Anda.
- Mengirim 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:
Peran yang diperlukan
Untuk mendapatkan izin yang diperlukan untuk memublikasikan pesan ke suatu topik,
minta administrator untuk memberi Anda peran IAM
Pub/Sub Publisher (roles/pubsub.publisher
) sesuai topik.
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses.
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 yang berisi metadata dan data 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 suatu 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.
Pada 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 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.
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.
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.
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 tersebut kepada penayang.
Menggunakan atribut untuk memublikasikan pesan
Anda dapat menyematkan atribut khusus sebagai metadata di 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 lebih dari 1.024 byte.
Skema pesan dapat direpresentasikan sebagai berikut:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Untuk duplikat sisi publikasi, nilai publishTime
yang berbeda dapat dilihat 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 khusus untuk stempel waktu peristiwa.
Contoh berikut menunjukkan cara memublikasikan pesan dengan atribut ke suatu topik.
Konsol
Untuk memublikasikan pesan dengan atribut, ikuti langkah-langkah berikut:
Di konsol Google Cloud, buka halaman Topics.
Klik topik yang pesannya ingin Anda publikasikan.
Di halaman detail topik, klik Pesan.
Klik Publikasikan pesan.
Pada kolom Isi pesan, masukkan data pesan.
Pada 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 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.
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.
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 kunci pengurutan, lihat Memesan pesan.
Berikut adalah daftar pertimbangan utama untuk pesan yang diurutkan bagi klien penayang:
Pemesanan di satu klien penayang: Saat satu klien penayang memublikasikan pesan dengan kunci pengurutan yang sama di region yang sama, klien pelanggan akan menerima pesan tersebut sesuai dengan urutan 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.
Pemesanan di beberapa klien penayang: Urutan pesan yang diterima oleh klien pelanggan konsisten dengan urutan pesan yang dipublikasikan di wilayah yang sama, meskipun beberapa klien penayang menggunakan kunci pengurutan yang sama. Namun, klien penayang sendiri tidak memiliki pengetahuan tentang 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 Y, semua klien pelanggan akan menerima pesan X sebelum Y. Jika diperlukan urutan pesan yang ketat di berbagai klien penayang, klien tersebut harus menerapkan mekanisme koordinasi tambahan untuk memastikan bahwa klien ini tidak memublikasikan pesan dengan kunci pengurutan yang sama secara bersamaan. Misalnya, layanan penguncian dapat digunakan untuk mempertahankan kepemilikan kunci pengurutan saat memublikasikan.
Pengurutan lintas region: Pengurutan pesan diharapkan hanya untuk pesan yang dipublikasikan di region yang sama. Oleh karena itu, pastikan klien penayang Anda menggunakan endpoint layanan lokasi untuk memublikasikan pesan ke region yang sama untuk kunci pengurutan yang sama. Klien pelanggan kemudian dapat menerima pesan ini secara berurutan.
Kegagalan publikasi: Jika publikasi dengan kunci pengurutan gagal, pesan yang diantrekan dengan kunci pengurutan yang sama di penayang akan gagal, termasuk permintaan publikasi di masa mendatang dari kunci pengurutan ini. Anda harus melanjutkan publikasi dengan kunci pengurutan jika kegagalan tersebut terjadi. Untuk contoh melanjutkan operasi publikasi, lihat Mencoba ulang permintaan dengan kunci pengurutan.
Anda dapat memublikasikan pesan dengan kunci pemesanan 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 pesannya ingin Anda publikasikan.
Di halaman detail topik, klik Pesan.
Klik Publikasikan pesan.
Pada 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 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.
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.
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 baik.
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 referensi berikut: