Mendaftarkan versi skema baru

Setelah membuat subjek, Anda dapat menambahkan versi baru ke subjek tersebut. Proses ini dikenal sebagai mendaftarkan versi skema baru. Setiap versi baru merepresentasikan evolusi skema yang terkait dengan subjek tersebut.

Subjek dapat memiliki beberapa versi. Versi dalam subjek mengikuti aturan kompatibilitas yang dapat dikonfigurasi untuk memastikan evolusi skema yang aman. Misalnya, subjek dapat mewajibkan semua perubahan kompatibel dengan versi sebelumnya. Contoh perubahan yang kompatibel dengan versi lama adalah menambahkan kolom opsional. Penambahan kolom wajib diisi akan dianggap sebagai perubahan yang tidak kompatibel dengan versi lama; jika subjek Anda dikonfigurasi untuk kompatibilitas dengan versi lama, perubahan ini tidak diizinkan. Namun, jika subjek Anda dikonfigurasi untuk kompatibilitas ke depan, menambahkan kolom wajib diisi akan dapat diterima.

Pemeriksaan kompatibilitas tidak berlaku surut. Jika aturan kompatibilitas diubah untuk registri subjek atau skema, versi yang sudah ada dalam subjek tidak akan divalidasi ulang berdasarkan aturan baru. Untuk mengetahui informasi selengkapnya tentang kompatibilitas, lihat Tentang jenis kompatibilitas.

Peran dan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mendaftarkan versi skema untuk subjek, minta administrator untuk memberi Anda peran IAM Managed Kafka Schema Registry Editor (roles/managedkafka.schemaRegistryEditor) di project atau subjek dan registry skema tertentu. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk mendaftarkan versi skema untuk subjek. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk mendaftarkan versi skema untuk subjek:

  • Berikan izin ini pada konteks induk atau konteks default: managedkafka.versions.create

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Peran Admin Managed Kafka Schema Registry (roles/managedkafka.schemaRegistryAdmin) tingkat yang lebih tinggi juga mencakup izin ini.

Untuk mengetahui informasi selengkapnya tentang peran standar yang tersedia untuk Managed Service for Apache Kafka, lihat dokumentasi Kontrol akses.

Mendaftarkan versi skema baru

Untuk mendaftarkan versi skema baru, lakukan langkah-langkah berikut.

Konsol

  1. Di konsol Google Cloud , buka halaman Schema registries.

    Buka Schema registry

  2. Klik nama registry skema tempat Anda ingin mendaftarkan versi skema baru.

  3. Di bagian Subjek dalam registry skema ini, klik nama subjek.

  4. Di halaman Subject details, klik Create version.

  5. Kolom Definisi skema menampilkan definisi versi terbaru. Perbarui definisi di kolom ini untuk versi baru. Jangan sertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan dalam nama kolom skema Anda.

  6. Jika skema Anda menggunakan atau bergantung pada struktur data yang ditentukan dalam skema lainnya di registri skema, lakukan langkah-langkah berikut:

    1. Klik Tambahkan referensi Skema.
    2. Di kolom Reference name, masukkan nama referensi skema yang dirujuk.
    3. Dalam daftar Subjek, pilih subjek yang berisi skema yang dirujuk.
    4. Dalam daftar Version, pilih nomor versi skema yang dirujuk.
    5. Klik Oke.

    Ulangi langkah-langkah ini untuk setiap skema yang dirujuk.

  7. Opsional: Untuk memeriksa apakah skema baru kompatibel dengan versi sebelumnya, klik Periksa kompatibilitas.

    Jika skema kompatibel, tanda centang akan ditampilkan. Jika tidak, pesan error akan muncul. Jika demikian, perbaiki error, lalu klik Periksa kompatibilitas lagi.

    Pemeriksaan kompatibilitas yang dilakukan bergantung pada jenis kompatibilitas subjek.

  8. Klik Create. Jika definisi skema valid dan lulus pemeriksaan kompatibilitas subjek, versi baru akan muncul di bagian Semua versi.

REST

Permintaan harus diautentikasi dengan token akses di header Authorization. Untuk mendapatkan token akses untuk Kredensial Default Aplikasi saat ini: gcloud auth application-default print-access-token.

Untuk mendaftarkan versi skema baru untuk subjek dalam konteks default, buat permintaan POST ke URI tertentu menggunakan metode projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Atau, jika menggunakan konteks tertentu, sertakan konteks dalam URI koleksi versi dan gunakan metode projects.locations.schemaRegistries.contexts.subjects.versions.create.

POST https://managedkafka.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/schemaRegistries/REGISTRY_ID/contexts/CONTEXT_ID/subjects/SUBJECT_ID/versions
Authorization: Bearer $(gcloud auth application-default print-access-token)
Content-Type: application/json

Ganti kode berikut:

  • PROJECT_ID (wajib): project ID Google Cloud Anda.
  • LOCATION (wajib): Google Cloud region tempat schema registry berada.
  • REGISTRY_ID (wajib): ID target pendaftaran skema.
  • CONTEXT_ID (opsional): ID konteks yang berisi subjek. Gunakan . (satu titik) untuk konteks default jika Anda ingin menggunakan konteks secara eksplisit, atau hilangkan /contexts/CONTEXT_ID untuk menggunakan konteks default secara implisit.
  • SUBJECT_ID (wajib): ID subjek yang akan digunakan untuk membuat versi baru.

Isi Permintaan:

Sertakan objek JSON di isi permintaan yang menentukan detail skema:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF" | "JSON", // Optional, defaults to AVRO
  "references": [ // Optional
    {
      "name": "REFERENCE_NAME",
      "subject": "REFERENCED_SUBJECT_ID",
      "version": REFERENCED_VERSION_NUMBER
    }
    // ... more references
  ]
  // "version": VERSION_NUMBER, // Optional: Usually omitted, let service assign next
  // "id": SCHEMA_ID, // Optional: Usually omitted, let service assign or reuse
}

Ganti kode berikut:

  • YOUR_SCHEMA_DEFINITION_STRING (wajib): string yang berisi payload definisi skema sebenarnya.

  • schemaType (opsional, dalam objek schema): jenis skema. Dapat berupa AVRO atau PROTOBUF. Nilai defaultnya adalah AVRO jika dihilangkan.

  • references (opsional, dalam objek schema): array objek yang menentukan skema apa pun yang dirujuk oleh skema ini.

    • REFERENCE_NAME: nama yang digunakan untuk mereferensikan skema lain dalam definisi skema ini.

    • REFERENCED_SUBJECT_ID: nama subjek yang sepenuhnya memenuhi syarat dari skema yang dirujuk. Contoh: projects/test-project/locations/us-central1/schemaRegistries/test-registry/subjects/test-referenced-subject.

    • REFERENCED_VERSION_NUMBER: nomor versi (bilangan bulat) tertentu dari skema subjek yang dirujuk.

  • versionId, schemaId: kolom opsional yang biasanya ditangani oleh layanan. Saat mendaftarkan versi skema, layanan akan menetapkan nomor versi berikutnya yang tersedia.

Jika permintaan berhasil, API akan menampilkan kode status 200 OK dan isi respons yang berisi ID skema.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi REST API.

Langkah berikutnya

Apache Kafka® adalah merek dagang terdaftar milik The Apache Software Foundation atau afiliasinya di Amerika Serikat dan/atau negara lain.