Properti langganan

Properti langganan Pub/Sub adalah karakteristik langganan. Anda dapat menetapkan properti langganan saat membuat atau memperbarui langganan.

Dokumen ini menjelaskan berbagai properti langganan yang dapat Anda tetapkan untuk langganan.

Sebelum memulai

• Pelajari langganan.

• Pahami alur kerja untuk langganan yang akan Anda buat: Pull, Push, atau BigQuery.

Properti langganan umum

Saat membuat langganan, Anda harus menentukan sejumlah opsi untuk menyiapkan langganan. Beberapa properti ini umum untuk semua jenis langganan dan akan dibahas di bagian berikutnya.

Durasi retensi pesan

Opsi Durasi retensi pesan menentukan berapa lama Pub/Sub menyimpan pesan setelah publikasi. Setelah durasi retensi pesan berlalu, Pub/Sub dapat menghapus pesan terlepas dari status konfirmasi pesan. Untuk mempertahankan pesan yang dikonfirmasi selama durasi retensi pesan, lihat Memutar ulang dan menghapus pesan.

Berikut adalah nilai untuk opsi Durasi retensi pesan:

• Nilai default = 7 hari
• Nilai minimum = 10 menit
• Nilai maksimum = 31 hari

Catatan: Jika Anda menyimpan pesan yang tidak terkonfirmasi dalam langganan selama lebih dari 24 jam, Anda akan dikenai biaya tambahan. Untuk mengetahui informasi selengkapnya, lihat Biaya penyimpanan.

Pesan yang tidak dikonfirmasi dapat disebabkan oleh langganan yang tidak ada aktivitas, kebutuhan pencadangan, atau pemrosesan yang lambat. Jika Anda dapat memproses pesan dalam waktu 24 jam, biaya tambahan tidak akan dikenakan. Anda dapat menghindari tagihan baru dengan mengelola skenario ini sebagai berikut:

• Langganan tidak ada aktivitas. Hapus langganan yang tidak ada aktivitasnya untuk menghindari tagihan retensi pesan langganan.

• Penyimpanan cadangan. Jika menggunakan retensi langganan sebagai penyimpanan cadangan, Anda dapat beralih ke opsi penyimpanan lain seperti retensi pesan topik atau mempertahankan pesan yang dibalas. Retensi pesan topik menyimpan pesan hanya sekali di tingkat topik dan pesan tersebut tetap tersedia untuk semua langganan yang akan menggunakannya jika diperlukan.

• Keterlambatan pemrosesan. Tambahkan lebih banyak pelanggan (jika memungkinkan) untuk memproses pesan dalam sehari.

Pertahankan pesan yang dikonfirmasi

Jika menentukan Durasi retensi pesan, Anda juga dapat menentukan apakah ingin mempertahankan pesan yang dikonfirmasi.

Opsi Pertahankan pesan yang dikonfirmasi memungkinkan Anda mempertahankan pesan yang dikonfirmasi selama durasi retensi pesan yang ditentukan. Opsi ini akan meningkatkan biaya penyimpanan pesan. Untuk informasi selengkapnya, lihat biaya penyimpanan.

Periode habis masa berlaku

Opsi Periode habis masa berlaku memungkinkan Anda memperpanjang periode habis masa berlaku langganan.

Masa berlaku langganan tanpa aktivitas pelanggan atau perubahan yang dilakukan pada properti langganan akan berakhir. Jika Pub/Sub mendeteksi aktivitas pelanggan atau jika Anda memperbarui salah satu properti langganan, jam penghapusan langganan akan dimulai ulang. Contoh aktivitas pelanggan meliputi koneksi terbuka, pull yang aktif, atau push yang berhasil dilakukan.

Jika Anda menentukan periode habis masa berlaku, nilainya harus lebih lama daripada durasi retensi pesan yang ditentukan dalam opsi Durasi retensi pesan.

Berikut adalah nilai untuk opsi Periode habis masa berlaku:

• Nilai default = 31 hari
• Nilai minimum = 1 hari

Untuk mencegah masa berlaku langganan berakhir, tetapkan periode habis masa berlaku ke never expire.

Batas waktu konfirmasi

Opsi Batas waktu konfirmasi menentukan batas waktu awal, setelah itu pesan yang tidak dikonfirmasi akan dikirim lagi. Anda dapat memperpanjang batas waktu konfirmasi per pesan dengan mengirimkan permintaan ModifyAckDeadline berikutnya.

Berikut adalah nilai untuk opsi Batas waktu konfirmasi:

• Nilai default = 10 detik
• Nilai minimum = 10 detik
• Nilai maksimum = 600 detik

Dalam beberapa kasus, library klien Pub/Sub dapat mengontrol kecepatan pengiriman dan mengubah batas waktu konfirmasi secara dinamis. Dengan demikian, pesan mungkin dikirim ulang sebelum batas waktu pengakuan yang Anda tetapkan. Untuk mengganti perilaku ini, gunakan minDurationPerAckExtension dan maxDurationPerAckExtension. Untuk informasi selengkapnya tentang penggunaan nilai ini, lihat Dukungan pengiriman tepat satu kali di library klien.

Filter langganan

Gunakan opsi Filter langganan untuk menentukan string dengan ekspresi pemfilteran. Jika langganan memiliki filter, langganan hanya akan mengirimkan pesan yang cocok dengan filter. Layanan Pub/Sub secara otomatis mengonfirmasi pesan yang tidak cocok dengan filter.

• Anda dapat memfilter pesan berdasarkan atributnya, tetapi tidak berdasarkan data dalam pesan.

• Jika tidak ditentukan, langganan tidak akan memfilter pesan dan pelanggan akan menerima semua pesan.

• Filter tidak dapat diubah atau dihapus setelah Anda menerapkannya.

Saat menerima pesan dari langganan dengan filter, Anda tidak dikenai biaya keluar untuk pesan yang otomatis dikonfirmasi oleh Pub/Sub. Anda akan dikenai biaya pengiriman pesan dan biaya penyimpanan terkait penelusuran untuk pesan ini.

Untuk mengetahui informasi selengkapnya, lihat Memfilter pesan dari langganan.

Pengurutan pesan

Jika langganan mengaktifkan Pengurutan pesan, klien pelanggan akan menerima pesan yang dipublikasikan di wilayah yang sama dengan kunci pengurutan yang sama sesuai dengan urutan pesan diterima oleh layanan.

Saat menggunakan pengiriman urut, konfirmasi untuk pesan berikutnya tidak diproses hingga konfirmasi untuk pesan sebelumnya diproses.

Penayang harus mengirim pesan dengan kunci pengurutan agar Pub/Sub dapat mengirimkan pesan secara berurutan.

Jika tidak ditetapkan, Pub/Sub mungkin tidak mengirim pesan secara berurutan, meskipun memiliki kunci pengurutan.

Topik yang dihentikan pengirimannya

Jika pesan tidak dapat dikirim setelah jumlah upaya pengiriman yang ditetapkan atau pelanggan tidak dapat mengonfirmasi pesan, Anda dapat mengonfigurasi topik pesan yang tidak terkirim tempat pesan ini dapat dipublikasikan ulang.

Jika menetapkan topik pesan tidak terkirim, Anda juga dapat menentukan jumlah maksimum upaya pengiriman. Berikut adalah nilai untuk jumlah maksimum upaya pengiriman untuk topik yang pengirimannya dihentikan:

• Nilai default = 5 upaya pengiriman
• Nilai minimum = 5 upaya pengiriman
• Nilai maksimum = 100 upaya pengiriman

Jika topik dead-letter berada di project yang berbeda dengan langganan, Anda juga harus menentukan project ID dengan topik dead-letter.

Untuk mengetahui informasi selengkapnya, lihat Penerusan ke topik surat mati.

Kebijakan coba lagi

Jika batas waktu konfirmasi berakhir atau pelanggan merespons dengan konfirmasi negatif, Pub/Sub dapat mengirim pesan lagi. Upaya pengiriman ulang ini dikenal sebagai Kebijakan percobaan ulang langganan.

Secara default, kebijakan percobaan ulang untuk langganan disetel untuk menggunakan Coba ulang segera. Dengan opsi ini, Pub/Sub akan mengirim ulang pesan saat batas waktu konfirmasi berakhir atau pelanggan merespons dengan konfirmasi negatif.

Anda juga dapat menetapkan nilai ke Coba lagi setelah penundaan backoff eksponensial. Dalam hal ini, Anda harus menentukan nilai backoff maksimum dan minimum.

Berikut beberapa panduan untuk menetapkan nilai untuk nilai backoff maksimum dan minimum:

• Jika Anda menetapkan nilai maksimum untuk durasi backoff, nilai default untuk durasi backoff minimum adalah 10 detik.

• Jika Anda menetapkan nilai minimum untuk durasi backoff, nilai default untuk durasi backoff maksimum adalah 600 detik.

• Durasi backoff terpanjang yang dapat Anda tentukan adalah 600 detik.

Kebijakan percobaan ulang dan pesan dalam batch

Jika pesan dalam batch, Pub/Sub akan memulai backoff eksponensial saat salah satu hal berikut terjadi:

• Pelanggan mengirim konfirmasi negatif untuk setiap pesan dalam batch.

• Batas waktu konfirmasi berakhir.

Kebijakan percobaan ulang dan langganan push

Jika Anda menerima pesan dari langganan push, Pub/Sub mungkin mengirim ulang pesan setelah jeda push, bukan durasi jeda eksponensial. Jika backoff push lebih lama dari durasi backoff eksponensial, Pub/Sub akan mengirim ulang pesan yang tidak dikonfirmasi setelah backoff push.

Catatan: Saat Anda mengubah durasi retensi pesan atau kebijakan habis masa berlaku langganan, periode habis masa berlaku harus ditetapkan ke nilai yang lebih besar dari durasi retensi pesan. Durasi retensi pesan default adalah 7 hari dan periode habis masa berlaku default adalah 31 hari.

Menarik properti langganan

Saat mengonfigurasi langganan pull, Anda dapat menentukan properti berikut.

Pengiriman tepat satu kali

Pengiriman tepat satu kali. Jika ditetapkan, Pub/Sub akan memenuhi jaminan pengiriman tepat satu kali. Jika tidak ditentukan, langganan mendukung pengiriman minimal satu kali untuk setiap pesan.

Properti langganan push

Saat mengonfigurasi langganan push, Anda dapat menentukan properti berikut.

Endpoint

URL endpoint (wajib). Alamat HTTPS yang dapat diakses secara publik. Server untuk endpoint push harus memiliki sertifikat SSL yang valid dan ditandatangani oleh certificate authority. Layanan Pub/Sub mengirimkan pesan ke endpoint push dari region Google Cloud yang sama dengan tempat layanan Pub/Sub menyimpan pesan. Layanan Pub/Sub mengirimkan pesan dari region Google Cloud yang sama berdasarkan upaya terbaik.

Pub/Sub tidak lagi memerlukan bukti kepemilikan untuk domain URL langganan push. Jika domain Anda menerima permintaan POST yang tidak terduga dari Pub/Sub, Anda dapat melaporkan dugaan penyalahgunaan.

Autentikasi

Aktifkan autentikasi. Jika diaktifkan, pesan yang dikirim oleh Pub/Sub ke endpoint push akan menyertakan header otorisasi untuk memungkinkan endpoint mengautentikasi permintaan. Mekanisme autentikasi dan otorisasi otomatis tersedia untuk endpoint fungsi App Engine Standard dan Cloud Run yang dihosting di project yang sama dengan langganan.

Konfigurasi autentikasi untuk langganan push yang diautentikasi terdiri dari akun layanan yang dikelola pengguna, dan parameter audiens yang ditentukan dalam panggilan create, patch, atau ModifyPushConfig. Anda juga harus memberikan peran tertentu kepada agen layanan, seperti yang dibahas di bagian berikutnya.

• Akun layanan yang dikelola pengguna (wajib). Akun layanan yang terkait dengan langganan push. Akun ini digunakan sebagai klaim email dari Token Web JSON (JWT) yang dihasilkan. Berikut adalah daftar persyaratan untuk akun layanan:

  • Akun layanan ini harus berada dalam project yang sama dengan langganan push.

  • Akun utama yang membuat atau mengubah langganan push harus memiliki izin iam.serviceAccounts.actAs di akun layanan. Anda dapat memberikan peran dengan izin ini di project, folder, atau organisasi untuk mengizinkan pemanggil meniru identitas beberapa akun layanan atau memberikan peran dengan izin ini di akun layanan untuk mengizinkan pemanggil hanya meniru identitas akun layanan ini.

• Audiens. Satu string yang tidak peka huruf besar/kecil yang digunakan webhook untuk memvalidasi audiens yang dimaksud dari token tertentu ini.

• Agen layanan (wajib).

  • Pub/Sub otomatis membuat akun layanan untuk Anda dengan format service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com.

  • Agen layanan ini harus diberi izin iam.serviceAccounts.getOpenIdToken (disertakan dalam peran roles/iam.serviceAccountTokenCreator) untuk mengizinkan Pub/Sub membuat token JWT untuk permintaan push yang diautentikasi.

Pembukaan payload

Opsi Enable payload unwrapping menghapus semua metadata pesan dari pesan Pub/Sub, kecuali data pesan. Dengan penguraian payload, data pesan dikirim langsung sebagai isi HTTP.

• Menulis metadata. Menambahkan metadata pesan yang sebelumnya dihapus kembali ke header permintaan.

Properti BigQuery

Saat memilih jenis pengiriman langganan sebagai Tulis ke BigQuery, Anda dapat menentukan properti tambahan berikut.

Menggunakan skema topik

Opsi ini memungkinkan Pub/Sub menggunakan skema topik Pub/Sub tempat langganan dilampirkan. Selain itu, Pub/Sub menulis kolom dalam pesan ke kolom yang sesuai di tabel BigQuery.

Perhatian: Penghapusan skema atau revisi skema bersifat permanen. Setiap pesan yang divalidasi terhadap revisi skema yang dihapus pada saat publikasi tidak dapat ditulis ke BigQuery menggunakan langganan BigQuery dengan Gunakan skema topik diaktifkan. Daripada menghapus skema atau revisi, pertimbangkan untuk melakukan roll back skema.

Saat menggunakan opsi ini, jangan lupa untuk memeriksa persyaratan tambahan berikut:

• Kolom dalam skema topik dan skema BigQuery harus memiliki nama yang sama dan jenisnya harus kompatibel satu sama lain.

• Setiap kolom opsional dalam skema topik juga harus opsional dalam skema BigQuery.

• Kolom wajib dalam skema topik tidak perlu diwajibkan dalam skema BigQuery.

• Jika ada kolom BigQuery yang tidak ada dalam skema topik, kolom BigQuery ini harus dalam mode NULLABLE.

• Jika skema topik memiliki kolom tambahan yang tidak ada dalam skema BigQuery dan kolom ini dapat dihapus, pilih opsi Hapus kolom yang tidak diketahui.

• Anda hanya dapat memilih salah satu properti langganan, Gunakan skema topik atau Gunakan skema tabel.

Jika Anda tidak memilih opsi Gunakan skema topik atau Gunakan skema tabel, pastikan tabel BigQuery memiliki kolom bernama data dari jenis BYTES, STRING, atau JSON. Pub/Sub menulis pesan ke kolom BigQuery ini.

Anda mungkin tidak melihat perubahan pada skema topik Pub/Sub atau skema tabel BigQuery langsung diterapkan dengan pesan yang ditulis ke tabel BigQuery. Misalnya, jika opsi Drop unknown fields diaktifkan dan kolom ada dalam skema Pub/Sub, tetapi tidak ada dalam skema BigQuery, pesan yang ditulis ke tabel BigQuery mungkin masih tidak berisi kolom setelah menambahkannya ke skema BigQuery. Pada akhirnya, skema akan disinkronkan dan pesan berikutnya akan menyertakan kolom tersebut.

Saat menggunakan opsi Gunakan skema topik untuk langganan BigQuery, Anda juga dapat memanfaatkan pengambilan data perubahan BigQuery (CDC). CDC memperbarui tabel BigQuery dengan memproses dan menerapkan perubahan pada baris yang ada.

Untuk mempelajari fitur ini lebih lanjut, lihat Update tabel streaming dengan pengambilan data perubahan.

Untuk mempelajari cara menggunakan fitur ini dengan langganan BigQuery, lihat Pengambilan data perubahan BigQuery.

Menggunakan skema tabel

Opsi ini memungkinkan Pub/Sub menggunakan skema tabel BigQuery untuk menulis kolom pesan JSON ke kolom yang sesuai. Saat Anda menggunakan opsi ini, jangan lupa untuk memeriksa persyaratan tambahan berikut:

• Pesan yang dipublikasikan harus dalam format JSON.

• Konversi JSON berikut didukung:

  Jenis JSON	Jenis Data BigQuery
  string	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME, atau TIMESTAMP
  number	NUMERIC, BIGNUMERIC, DATE, TIME, DATETIME, atau TIMESTAMP

  • Saat menggunakan konversi number ke DATE, DATETIME, TIME, atau TIMESTAMP, angka tersebut harus mematuhi representasi yang didukung.
  • Saat menggunakan konversi number ke NUMERIC atau BIGNUMERIC, presisi dan rentang nilai dibatasi pada nilai yang diterima oleh standar IEEE 754 untuk aritmetika floating point. Jika Anda memerlukan presisi tinggi atau rentang nilai yang lebih luas, gunakan konversi string ke NUMERIC atau BIGNUMERIC.
  • Saat menggunakan konversi string ke NUMERIC atau BIGNUMERIC, Pub/Sub mengasumsikan string tersebut adalah angka yang dapat dibaca manusia (misalnya, "123.124"). Jika pemrosesan string sebagai angka yang dapat dibaca manusia gagal, Pub/Sub akan memperlakukan string tersebut sebagai byte yang dienkode dengan BigDecimalByteStringEncoder.

• Jika topik langganan memiliki skema yang terkait dengannya, maka properti encoding pesan harus ditetapkan ke JSON.

• Jika ada kolom BigQuery yang tidak ada dalam pesan, kolom BigQuery ini harus dalam mode NULLABLE.

• Jika pesan memiliki kolom tambahan yang tidak ada dalam skema BigQuery dan kolom ini dapat dihapus, pilih opsi Hapus kolom yang tidak diketahui.

• Anda hanya dapat memilih salah satu properti langganan, Gunakan skema topik atau Gunakan skema tabel.

Jika Anda tidak memilih opsi Gunakan skema topik atau Gunakan skema tabel, pastikan tabel BigQuery memiliki kolom bernama data dari jenis BYTES, STRING, atau JSON. Pub/Sub menulis pesan ke kolom BigQuery ini.

Anda mungkin tidak melihat perubahan pada skema tabel BigQuery langsung berlaku dengan pesan yang ditulis ke tabel BigQuery. Misalnya, jika opsi Drop unknown fields diaktifkan dan kolom ada dalam pesan, tetapi tidak ada dalam skema BigQuery, pesan yang ditulis ke tabel BigQuery mungkin masih tidak berisi kolom tersebut setelah ditambahkan ke skema BigQuery. Pada akhirnya, skema akan disinkronkan dan pesan berikutnya akan menyertakan kolom tersebut.

Saat menggunakan opsi Gunakan skema tabel untuk langganan BigQuery, Anda juga dapat memanfaatkan pengambilan data perubahan BigQuery (CDC). CDC memperbarui tabel BigQuery dengan memproses dan menerapkan perubahan pada baris yang ada.

Untuk mempelajari fitur ini lebih lanjut, lihat Update tabel streaming dengan pengambilan data perubahan.

Untuk mempelajari cara menggunakan fitur ini dengan langganan BigQuery, lihat Pengambilan data perubahan BigQuery.

Menghapus kolom yang tidak diketahui

Opsi ini digunakan dengan opsi Gunakan skema topik atau Gunakan skema tabel. Opsi ini memungkinkan Pub/Sub menghapus kolom apa pun yang ada dalam skema atau pesan topik, tetapi tidak ada dalam skema BigQuery. Tanpa menetapkan Hapus kolom yang tidak diketahui, pesan dengan kolom tambahan tidak akan ditulis ke BigQuery dan tetap berada dalam backlog langganan. Langganan akan berakhir dalam status error.

Menulis metadata

Opsi ini memungkinkan Pub/Sub menulis metadata setiap pesan ke kolom tambahan di tabel BigQuery. Jika tidak, metadata tidak akan ditulis ke tabel BigQuery.

Jika Anda memilih opsi Write metadata, pastikan tabel BigQuery memiliki kolom yang dijelaskan dalam tabel berikut.

Jika Anda tidak memilih opsi Tulis metadata, tabel BigQuery tujuan hanya memerlukan kolom data kecuali jika use_topic_schema bernilai benar. Jika Anda memilih opsi Tulis metadata dan Gunakan skema topik, skema topik tidak boleh berisi kolom apa pun dengan nama yang cocok dengan parameter metadata. Batasan ini mencakup versi camelcase dari parameter snake case ini.

Parameter
subscription_name	STRING Nama langganan.
message_id	STRING ID pesan
publish_time	TIMESTAMP Waktu publikasi pesan.
data	BYTES, STRING, atau JSON Isi pesan. Kolom data diperlukan untuk semua tabel BigQuery tujuan yang tidak memilih Gunakan skema topik atau Gunakan skema tabel. Jika kolom tersebut berjenis JSON, isi pesan harus berupa JSON yang valid.
attributes	STRING atau JSON Objek JSON yang berisi semua atribut pesan. File ini juga berisi kolom tambahan yang merupakan bagian dari pesan Pub/Sub, termasuk kunci pengurutan, jika ada.

Properti Cloud Storage

Saat memilih jenis pengiriman langganan sebagai Tulis ke Cloud Storage, Anda dapat menentukan properti tambahan berikut.

Nama bucket

Bucket Cloud Storage harus sudah ada sebelum Anda membuat langganan Cloud Storage.

Pesan dikirim sebagai batch dan disimpan di bucket Cloud Storage. Satu batch atau file disimpan sebagai objek di bucket.

Bucket Cloud Storage harus menonaktifkan Pemohon Membayar.

Untuk membuat bucket Cloud Storage, lihat artikel Membuat bucket.

Awalan, akhiran, dan tanggal waktu nama file

File Cloud Storage output yang dihasilkan oleh langganan Cloud Storage disimpan sebagai objek di bucket Cloud Storage. Nama objek yang disimpan di bucket Cloud Storage memiliki format berikut: <file-prefix><UTC-date-time>_<uuid><file-suffix>.

Daftar berikut menyertakan detail format file dan kolom yang dapat Anda sesuaikan:

• <file-prefix> adalah awalan nama file kustom. Kolom ini bersifat opsional.

• <UTC-date-time> adalah string yang dibuat otomatis dan dapat disesuaikan berdasarkan waktu pembuatan objek.

• <uuid> adalah string acak yang dibuat otomatis untuk objek.

• <file-suffix> adalah akhiran nama file kustom. Kolom ini bersifat opsional. Akhiran nama file tidak boleh diakhiri dengan "/".

• Anda dapat mengubah awalan dan akhiran nama file:

  • Misalnya, jika nilai awalan nama file adalah prod_ dan nilai akhiran nama file adalah _archive, contoh nama objek adalah prod_2023-09-25T04:10:00+00:00_uN1QuE_archive.

  • Jika Anda tidak menentukan awalan dan akhiran nama file, nama objek yang disimpan di bucket Cloud Storage akan memiliki format: <UTC-date-time>_<uuid>.

  • Persyaratan penamaan objek Cloud Storage juga berlaku untuk awalan dan akhiran nama file. Untuk mengetahui informasi selengkapnya, lihat Tentang objek Cloud Storage.

• Anda dapat mengubah cara tanggal dan waktu ditampilkan dalam nama file:

  • Pencocok tanggal/waktu wajib yang hanya dapat Anda gunakan sekali: tahun (YYYY atau YY), bulan (MM), hari (DD), jam (hh), menit (mm), detik (ss). Misalnya, YY-YYYY atau MMM tidak valid.

  • Pencocok opsional yang hanya dapat Anda gunakan sekali: pemisah tanggal dan waktu (T) dan offset zona waktu (Z atau +00:00).

  • Elemen opsional yang dapat Anda gunakan beberapa kali: tanda hubung (-), garis bawah (_), titik dua (:), dan garis miring (/).

  • Misalnya, jika nilai format tanggal waktu nama file adalah YYYY-MM-DD/hh_mm_ssZ, nama objek contohnya adalah prod_2023-09-25/04_10_00Z_uNiQuE_archive.

  • Jika format tanggal waktu nama file diakhiri dengan karakter yang bukan pencocok, karakter tersebut akan menggantikan pemisah antara <UTC-date-time> dan <uuid>. Misalnya, jika nilai format tanggal waktu nama file adalah YYYY-MM-DDThh_mm_ss-, nama objek contohnya adalah prod_2023-09-25T04_10_00-uNiQuE_archive.

Pengelompokan file

Langganan Cloud Storage memungkinkan Anda memutuskan kapan ingin membuat file output baru yang disimpan sebagai objek di bucket Cloud Storage. Pub/Sub menulis file output saat salah satu kondisi pengelompokan yang ditentukan terpenuhi. Berikut adalah kondisi pengelompokan Cloud Storage:

• Durasi maksimum batch penyimpanan. Setelan ini wajib diisi. Langganan Cloud Storage akan menulis file output baru jika nilai durasi maksimum yang ditentukan terlampaui. Jika Anda tidak menentukan nilai, nilai default 5 menit akan diterapkan. Berikut adalah nilai yang berlaku untuk durasi maksimum:

  • Nilai minimum = 1 menit
  • Nilai default = 5 menit
  • Nilai maksimum = 10 menit

• Byte maksimum batch penyimpanan. Ini adalah setelan opsional. Langganan Cloud Storage akan menulis file output baru jika nilai byte maksimum yang ditentukan terlampaui. Berikut adalah nilai yang berlaku untuk byte maksimum:

  • Nilai minimum = 1 KB
  • Nilai maksimum = 10 GiB

• Pesan maksimum batch penyimpanan. Ini adalah setelan opsional. Langganan Cloud Storage akan menulis file output baru jika jumlah pesan maksimum yang ditentukan terlampaui. Berikut adalah nilai yang berlaku untuk pesan maksimum:

  • Nilai minimum = 1.000

Misalnya, Anda dapat mengonfigurasi durasi maksimum sebagai 6 menit dan byte maksimum sebagai 2 GB. Jika pada menit ke-4, file output mencapai ukuran file 2 GB, Pub/Sub akan menyelesaikan file sebelumnya dan mulai menulis ke file baru.

Langganan Cloud Storage mungkin menulis ke beberapa file di bucket Cloud Storage secara bersamaan. Jika telah mengonfigurasi langganan untuk membuat file baru setiap menit ke-6, Anda mungkin mengamati beberapa file Cloud Storage yang dibuat setiap 6 menit.

Dalam beberapa situasi, Pub/Sub mungkin mulai menulis ke file baru lebih awal dari waktu yang dikonfigurasi oleh kondisi pengelompokan file. File juga dapat melebihi nilai Max bytes jika langganan menerima pesan yang lebih besar dari nilai Max bytes.

Format file

Saat membuat langganan Cloud Storage, Anda dapat menentukan format file output yang akan disimpan di bucket Cloud Storage sebagai Text atau Avro.

• Teks: Pesan disimpan sebagai teks biasa. Karakter baris baru memisahkan pesan dari pesan sebelumnya dalam file. Hanya payload pesan yang disimpan, bukan atribut atau metadata lainnya.

• Avro: Pesan disimpan dalam format biner Apache Avro. Saat memilih Avro, Anda dapat mengaktifkan properti tambahan berikut:

  • Tulis metadata: Opsi ini memungkinkan Anda menyimpan metadata pesan bersama dengan pesan. Metadata seperti kolom subscription_name, message_id, publish_time, dan attributes ditulis ke kolom tingkat atas dalam objek Avro output, sedangkan semua properti pesan lainnya selain data (misalnya, ordering_key, jika ada) ditambahkan sebagai entri dalam peta attributes.

    Jika metadata tulis dinonaktifkan, hanya payload pesan yang akan ditulis ke objek Avro output. Berikut adalah skema Avro untuk pesan output dengan metadata tulis dinonaktifkan:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    Berikut adalah skema Avro untuk pesan output dengan metadata tulis diaktifkan:

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • Gunakan skema topik: Opsi ini memungkinkan Pub/Sub menggunakan skema topik Pub/Sub yang dipasangkan ke langganan saat menulis file Avro.

    Saat menggunakan opsi ini, jangan lupa untuk memeriksa persyaratan tambahan berikut:

    • Skema topik harus dalam format Apache Avro.

    • Jika gunakan skema topik dan tulis metadata diaktifkan, skema topik harus memiliki objek Record di root-nya. Pub/Sub akan memperluas daftar kolom Data untuk menyertakan kolom metadata. Akibatnya, Data tidak boleh berisi kolom apa pun dengan nama yang sama dengan kolom metadata (subscription_name, message_id, publish_time, atau attributes).

Langkah selanjutnya

• Buat langganan pull.
• Buat langganan push.
• Buat langganan BigQuery.
• Buat langganan Cloud Storage.