Dokumen ini menunjukkan cara mengaitkan skema untuk topik Pub/Sub.
Sebelum memulai
- Pahami cara kerja skema Pub/Sub.
- Buat skema.
Peran dan izin yang diperlukan
Untuk mendapatkan izin yang diperlukan guna mengaitkan dan mengelola skema, minta administrator untuk memberi Anda peran IAM Pub/Sub Editor (roles/pubsub.editor
) di project Anda.
Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.
Peran bawaan ini berisi izin yang diperlukan untuk mengaitkan dan mengelola skema. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:
Izin yang diperlukan
Izin berikut diperlukan untuk mengaitkan dan mengelola skema:
-
Buat skema:
pubsub.schemas.create
-
Lampirkan skema ke topik:
pubsub.schemas.attach
-
Meng-commit revisi skema:
pubsub.schemas.commit
-
Menghapus skema atau revisi skema:
pubsub.schemas.delete
-
Mendapatkan skema atau revisi skema:
pubsub.schemas.get
-
Mencantumkan skema:
pubsub.schemas.list
-
Mencantumkan revisi skema:
pubsub.schemas.listRevisions
-
Mengembalikan skema:
pubsub.schemas.rollback
-
Memvalidasi pesan:
pubsub.schemas.validate
-
Mendapatkan kebijakan IAM untuk skema:
pubsub.schemas.getIamPolicy
-
Konfigurasi kebijakan IAM untuk skema:
pubsub.schemas.setIamPolicy
Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.
Anda dapat memberikan peran dan izin kepada entity utama seperti pengguna, grup, domain, atau akun layanan. Anda dapat membuat skema dalam satu project dan melampirkannya ke topik yang berada di project lain. Pastikan Anda memiliki izin yang diperlukan untuk setiap project.
Panduan untuk mengaitkan skema dengan topik
Anda dapat mengaitkan skema dengan topik saat membuat atau mengedit topik. Berikut adalah panduan untuk mengaitkan skema dengan topik:
Anda dapat mengaitkan skema dengan satu atau beberapa topik.
Setelah skema dikaitkan dengan topik, setiap pesan yang diterima topik dari penayang harus mengikuti skema tersebut.
Saat mengaitkan skema dengan topik, Anda juga harus menentukan encoding pesan yang akan dipublikasikan sebagai
BINARY
atauJSON
. Jika menggunakan JSON dengan skema Avro, perhatikan baik-baik aturan encoding untuk gabungan.Jika skema yang terkait dengan topik memiliki revisi, pesan harus cocok dengan encoding dan divalidasi terhadap revisi dalam rentang yang tersedia. Jika tidak divalidasi, pesan akan gagal dipublikasikan.
Revisi dicoba dalam urutan kronologis terbalik yang didasarkan pada waktu pembuatan. Untuk membuat revisi skema, lihat Meng-commit revisi skema.
Logika validasi untuk skema pesan
Saat mengaitkan skema dengan topik dan jika skema memiliki revisi, Anda dapat menentukan rentang revisi yang akan digunakan. Jika Anda tidak menentukan rentang, seluruh rentang akan digunakan untuk validasi.
Jika Anda tidak menentukan revisi sebagai Revisi pertama yang diizinkan, revisi terlama yang ada untuk skema akan digunakan untuk validasi. Jika Anda tidak menentukan revisi sebagai Revisi terakhir yang diizinkan, maka revisi terbaru yang ada untuk skema akan digunakan.
Mari kita ambil contoh Skema S
yang dilampirkan ke topik T
.
Skema S
memiliki ID revisi A
,B
, C
, dan D
yang dibuat secara berurutan,
dengan A
adalah revisi pertama atau terlama. Tidak ada skema yang identik
satu sama lain, atau rollback skema yang ada.
Jika Anda hanya menyetel kolom Revisi pertama yang diizinkan sebagai
B
, pesan yang hanya sesuai dengan skemaA
akan ditolak, sedangkan pesan yang sesuai dengan skemaB
,C
, danD
akan diterima.Jika Anda hanya menyetel kolom Revisi terakhir yang diizinkan sebagai
C
, pesan yang sesuai dengan skemaA
,B
, danC
akan diterima, dan pesan yang hanya sesuai dengan skemaD
akan ditolak.Jika Anda menetapkan kedua kolom Revisi pertama yang diizinkan sebagai
B
dan Revisi terakhir yang diizinkan sebagaiC
, pesan yang sesuai dengan skemaB
danC
akan diterima.Anda juga dapat menyetel revisi pertama dan terakhir ke ID revisi yang sama. Dalam hal ini, hanya pesan yang sesuai dengan revisi tersebut yang diterima.
Membuat dan mengaitkan skema saat Anda membuat topik
Anda dapat membuat topik dengan skema menggunakan Google Cloud konsol, gcloud CLI, Pub/Sub API, atau Cloud Client Libraries.
Konsol
Di konsol Google Cloud , buka halaman Pub/Sub topics.
Klik Create topic.
Di kolom Topic ID, masukkan ID untuk topik Anda.
Untuk memberi nama topik, lihat pedoman.
Centang kotak Gunakan skema.
Pertahankan setelan default untuk kolom yang tersisa.
Anda dapat membuat skema atau menggunakan skema yang sudah ada.
Jika Anda membuat skema, ikuti langkah-langkah berikut: `
- Untuk Select a Pub/Sub schema, pilih Create a new schema.
Halaman Create schema ditampilkan di tab sekunder.
Ikuti langkah-langkah di Membuat skema.
Kembali ke tab Buat topik, lalu klik Muat ulang.
Telusuri skema Anda di kolom Select a Pub/Sub schema.
Pilih encoding pesan sebagai JSON atau Biner.
Skema yang baru saja Anda buat memiliki ID revisi. Anda dapat membuat revisi skema tambahan seperti yang dibahas dalam Melakukan revisi skema.
Jika Anda mengaitkan skema yang sudah dibuat, ikuti langkah-langkah berikut:
Untuk Select a Pub/Sub schema, pilih skema yang ada.
Pilih encoding pesan sebagai JSON atau Biner.
Opsional: Jika skema yang dipilih memiliki revisi, untuk Rentang Revisi, gunakan menu drop-down untuk Revisi pertama yang diizinkan dan Revisi terakhir yang diizinkan.
Anda dapat menentukan kedua kolom, hanya menentukan salah satu, atau mempertahankan setelan default berdasarkan persyaratan Anda.
Pertahankan setelan default untuk kolom yang tersisa.
Klik Buat untuk menyimpan topik dan menetapkannya ke skema yang dipilih.
gcloud
Untuk membuat topik yang ditetapkan dengan skema yang dibuat sebelumnya, jalankan perintah
gcloud pubsub topics create
berikut:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Dengan:
- TOPIC_ID adalah ID untuk topik yang Anda buat.
- ENCODING_TYPE adalah encoding pesan yang divalidasi terhadap skema. Nilai ini harus ditetapkan ke
JSON
atauBINARY
. - SCHEMA_ID adalah ID skema yang ada.
- FIRST_REVISION_ID adalah ID revisi terlama yang akan divalidasi.
- LAST_REVISION_ID adalah ID revisi terbaru yang akan divalidasi.
--first-revision-id
dan --last-revision-id
bersifat opsional.
Anda juga dapat menetapkan skema dari project Google Cloud lain:
gcloud pubsub topics create TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_ID \ --schema-project=SCHEMA_PROJECT \ --project=TOPIC_PROJECT
Dengan:
- SCHEMA_PROJECT adalah project ID Google Cloud project untuk skema.
- TOPIC_PROJECT adalah project ID project Google Cloud untuk topik.
REST
Untuk membuat topik, gunakan metode projects.topics.create
:
Permintaan:
Permintaan harus diautentikasi dengan token akses di header
Authorization
. Untuk mendapatkan token akses bagi Kredensial Default Aplikasi saat ini: gcloud auth application-default print-access-token
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Isi permintaan:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
Dengan:
- PROJECT_ID adalah project ID Anda.
- TOPIC_ID adalah topic ID Anda.
- SCHEMA_NAME adalah nama skema yang digunakan untuk memvalidasi pesan yang dipublikasikan. Formatnya adalah:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE adalah encoding pesan yang divalidasi terhadap skema. Nilai ini harus ditetapkan ke
JSON
atauBINARY
. - FIRST_REVISION_ID adalah ID revisi terlama yang akan divalidasi.
- LAST_REVISION_ID adalah ID revisi terbaru yang akan divalidasi.
firstRevisionId
dan lastRevisionId
bersifat opsional.
Respons:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
dan lastRevisionId
akan dihilangkan jika tidak diberikan dalam permintaan.
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.
Mengedit skema yang terkait dengan topik
Anda dapat mengedit topik untuk melampirkan skema, menghapus skema, atau memperbarui rentang revisi yang digunakan untuk memvalidasi pesan. Secara umum, jika Anda memiliki perubahan yang direncanakan untuk skema yang digunakan, Anda dapat melakukan revisi baru dan memperbarui rentang revisi yang digunakan untuk topik.
Anda dapat mengedit skema yang terkait dengan topik menggunakan Google Cloud konsol, gcloud CLI, Pub/Sub API, atau Library Klien Cloud.
Konsol
Di konsol Google Cloud , buka halaman Pub/Sub topics.
Klik Topic ID topik.
Di halaman detail topik, klik Edit.
Anda dapat melakukan perubahan berikut pada skema.
Mungkin perlu waktu beberapa menit agar perubahan diterapkan.
Jika Anda ingin menghapus skema dari topik, di halaman Edit topik, hapus centang pada kotak Gunakan skema.
Jika Anda ingin mengubah skema, di bagian Schema, pilih nama skema.
Perbarui kolom lainnya sesuai kebutuhan.
- Jika Anda ingin memperbarui rentang revisi, untuk Rentang Revisi, gunakan menu drop-down untuk Revisi pertama yang diizinkan dan Revisi terakhir yang diizinkan.
Anda dapat menentukan kedua kolom, hanya menentukan salah satu, atau mempertahankan setelan default berdasarkan persyaratan Anda.
Klik Perbarui untuk menyimpan perubahan.
gcloud
gcloud pubsub topics update TOPIC_ID \ --message-encoding=ENCODING_TYPE \ --schema=SCHEMA_NAME \ --first-revision-id=FIRST_REVISION_ID \ --last-revision-id=LAST_REVISION_ID \
Dengan:
- TOPIC_ID adalah ID untuk topik yang Anda buat.
- ENCODING_TYPE adalah encoding pesan yang divalidasi terhadap skema. Nilai ini harus ditetapkan ke
JSON
atauBINARY
. - SCHEMA_NAME adalah nama skema yang ada.
- FIRST_REVISION_ID adalah ID revisi terlama yang akan divalidasi.
- LAST_REVISION_ID adalah ID revisi terbaru yang akan divalidasi.
--first-revision-id
dan --last-revision-id
bersifat opsional.
REST
Untuk memperbarui topik, gunakan metode projects.topics.patch
:
Permintaan:
Permintaan harus diautentikasi dengan token akses di header
Authorization
. Untuk mendapatkan token akses bagi Kredensial Default Aplikasi saat ini: gcloud auth application-default print-access-token
.
PATCH https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID Authorization: Bearer ACCESS_TOKEN
Isi permintaan:
{ "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" "update_mask": } }
Dengan:
- PROJECT_ID adalah project ID Anda.
- TOPIC_ID adalah topic ID Anda.
- SCHEMA_NAME adalah nama skema yang digunakan untuk memvalidasi pesan yang dipublikasikan. Formatnya adalah:
projects/PROJECT_ID/schemas/SCHEMA_ID
. - ENCODING_TYPE adalah encoding pesan yang divalidasi terhadap skema. Nilai ini harus ditetapkan ke
JSON
atauBINARY
. - FIRST_REVISION_ID adalah ID revisi terlama yang akan divalidasi.
- LAST_REVISION_ID adalah ID revisi terbaru yang akan divalidasi.
firstRevisionId
dan lastRevisionId
bersifat opsional.
Respons:
{ "name": "projects/PROJECT_ID/topics/TOPIC_ID", "schemaSettings": { "schema": "SCHEMA_NAME", "encoding": "ENCODING_TYPE" "firstRevisionId": "FIRST_REVISION_ID" "lastRevisionId": "LAST_REVISION_ID" } }
firstRevisionId
dan lastRevisionId
tidak ditetapkan setelah
update.
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 Pub/Sub Java 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.
Langkah berikutnya
- Meng-commit revisi skema
- Memublikasikan pesan ke topik dengan skema
- Memvalidasi definisi skema
- Memvalidasi pesan untuk skema