Ringkasan registry skema

Schema registry menyediakan repositori skema yang digunakan oleh beberapa aplikasi. Sebelumnya, tanpa registry skema, tim mungkin bergantung pada perjanjian informal—seperti pemahaman verbal, dokumen bersama yang tidak diterapkan secara terprogram, atau halaman wiki—untuk menentukan format pesan dan cara melakukan serialisasi dan deserialisasi pesan. Registry skema memastikan encoding dan decoding pesan yang konsisten.

Dokumen ini memberikan ringkasan fitur registry skema untuk Managed Service for Apache Kafka, komponennya, dan alur kerja dasarnya.

Memahami skema

Bayangkan Anda sedang membuat aplikasi yang melacak pesanan pelanggan. Anda dapat menggunakan topik Kafka bernama customer_orders untuk mengirimkan pesan yang berisi informasi tentang setiap pesanan. Pesan pesanan standar dapat menyertakan kolom informasi berikut:

ID Pesanan
Nama pelanggan
Nama produk
Kuantitas
Harga

Untuk memastikan pesan ini disusun secara konsisten, Anda dapat menentukan skema. Berikut adalah contoh dalam format Apache Avro:

{
  "type": "record",
  "name": "Order",
  "namespace": "com.example",
  "fields": [
    {"name": "orderId", "type": "string"},
    {"name": "customerName", "type": "string"},
    {"name": "productName", "type": "string"},
    {"name": "quantity", "type": "int"},
    {"name": "price", "type": "double"}
  ]
}

Berikut adalah contoh yang sama dalam format Protocol Buffer.

syntax = "proto3";

package com.example;

option java_multiple_files = true; // Optional: Recommended for Java users
option java_package = "com.example"; // Optional: Explicit Java package

message Order {
  string orderId = 1;
  string customerName = 2;
  string productName = 3;
  int32 quantity = 4; // Avro int maps to Protobuf int32
  double price = 5;
}

Skema ini adalah blueprint untuk pesan. Hal ini memberi tahu Anda bahwa pesan order memiliki lima kolom: ID pesanan, nama pelanggan, nama produk, jumlah, dan harga. Selain itu, file ini juga menentukan jenis data setiap kolom.

Jika klien konsumen menerima pesan biner yang dienkode dengan skema ini, klien tersebut harus tahu persis cara menafsirkannya. Untuk mewujudkannya, produsen menyimpan skema order di registry skema dan meneruskan ID skema bersama dengan pesan. Selama konsumen pesan mengetahui registry mana yang digunakan, konsumen dapat mengambil skema yang sama dan mendekode pesan.

Asumsikan bahwa Anda ingin menambahkan kolom, orderDate, ke pesan order Anda. Anda akan membuat versi baru skema order dan mendaftarkannya dengan subjek yang sama. Dengan begitu, Anda dapat melacak perkembangan skema dari waktu ke waktu. Penambahan kolom adalah perubahan yang kompatibel dengan versi mendatang. Artinya, konsumen yang menggunakan versi skema lama (tanpa orderDate) masih dapat membaca dan memproses pesan yang dibuat dengan skema baru. Kolom baru akan diabaikan.

Kompatibilitas mundur untuk registry skema berarti aplikasi konsumen yang dikonfigurasi dengan versi skema baru dapat membaca data yang dihasilkan dengan skema sebelumnya.

Dalam contoh ini, skema order awal adalah versi 1. Saat menambahkan kolom orderDate, Anda membuat skema order versi 2. Kedua versi disimpan dalam subjek yang sama, sehingga Anda dapat mengelola update skema tanpa merusak aplikasi yang ada yang mungkin masih mengandalkan versi 1.

Berikut adalah tampilan atas ke bawah dari contoh registry skema yang disebut schema_registry_test yang disusun berdasarkan konteks, subjek, dan versi skema:

customer_support context
- order subjek
- V1 versi (mencakup orderId, customerName, productName, quantity, price)
- V2 (menambahkan orderDate ke V1)

Apa itu skema

Pesan Apache Kafka terdiri dari string byte. Tanpa struktur yang ditentukan, aplikasi konsumen harus berkoordinasi langsung dengan aplikasi produsen untuk memahami cara menafsirkan byte ini.

Skema memberikan deskripsi formal data dalam pesan. Skema menentukan kolom dan jenis datanya seperti string, bilangan bulat, atau boolean, dan struktur bertingkat.

Managed Service untuk Apache Kafka mendukung skema dalam format berikut:

Apache Avro
Protocol Buffers (Protobuf)

Schema Registry API tidak mendukung JSON.

Fitur schema registry yang terintegrasi dalam Managed Service for Apache Kafka memungkinkan Anda membuat, mengelola, dan menggunakan skema ini dengan klien Kafka. Registry skema menerapkan Confluent Schema Registry REST API, yang kompatibel dengan aplikasi Apache Kafka yang ada dan library klien umum.

Organisasi registry skema

Registry skema menggunakan struktur hierarki untuk mengatur skema.

Gambar: Struktur hierarkis skema.

Skema: struktur dan jenis data pesan. Setiap skema diidentifikasi dengan ID skema. ID ini digunakan oleh aplikasi untuk mengambil skema.
Subject: penampung logis untuk berbagai versi skema. Subjek mengelola cara skema berkembang dari waktu ke waktu menggunakan aturan kompatibilitas. Setiap subjek biasanya sesuai dengan topik atau objek rekaman Kafka.
Versi: saat logika bisnis memerlukan perubahan pada struktur pesan, buat dan daftarkan versi skema baru di bagian subjek yang relevan.

Setiap versi mereferensikan skema tertentu. Versi subjek yang berbeda dapat mereferensikan skema yang sama jika skema pokoknya sama.
Konteks: pengelompokan atau namespace tingkat tinggi untuk subjek. Konteks memungkinkan tim atau aplikasi yang berbeda menggunakan nama subjek yang sama tanpa konflik dalam registry skema yang sama.

Registry skema dapat memiliki beberapa konteks. Selalu berisi konteks default yang diidentifikasi sebagai ., yaitu tempat skema dan subjek berada jika tidak ada ID konteks lain yang ditentukan.

Konteks dapat berisi beberapa subjek.
Registry: penampung tingkat teratas untuk seluruh ekosistem skema. Menyimpan dan mengelola semua skema, subjek, versi, dan konteks.

Alur kerja pendaftaran skema

Untuk mengikuti alur kerja yang dijelaskan di bagian ini, Anda dapat mencoba panduan memulai di Membuat pesan Avro dengan registry skema.

Serializer dan deserializer di klien Kafka Anda berinteraksi dengan registry skema untuk memastikan pesan sesuai dengan skema yang ditentukan. Berikut alur kerja umum untuk registry skema di Managed Service for Apache Kafka:

Lakukan inisialisasi aplikasi produser Anda dengan skema tertentu yang ditentukan sebagai class yang dibuat Avro dan konfigurasikan untuk menggunakan library serializer dan registry skema tertentu.
Konfigurasi klien konsumen untuk menggunakan library deserializer yang sesuai dan registry skema yang sama.
Saat runtime, klien meneruskan objek pesan ke metode producer.send dan library klien Kafka menggunakan serializer yang dikonfigurasi untuk mengonversi rekaman ini menjadi byte yang dienkode Avro.
Serializer menentukan nama subjek untuk skema berdasarkan strategi nama subjek yang dikonfigurasi dalam library klien. Kemudian, nama subjek ini digunakan dalam permintaan ke registry skema untuk mengambil ID skema. Untuk mengetahui informasi selengkapnya, lihat Strategi penamaan subjek.
Jika skema tidak ada di registry dengan nama subjek tersebut, klien dapat dikonfigurasi untuk mendaftarkan skema, yang dalam hal ini akan menerima ID yang baru ditetapkan.

Hindari konfigurasi ini di lingkungan produksi.
Produser mengirim pesan yang diserialisasi dengan ID skema ke topik broker Kafka yang sesuai.
Broker Kafka menyimpan representasi array byte pesan Anda dalam topik.
Aplikasi konsumen menerima pesan.
Deserializer mengambil skema dengan ID ini dari registry skema.
Deserializer mengurai pesan untuk aplikasi konsumen.

Batasan

Fitur berikut tidak didukung oleh registry skema:

Format skema:
- Format skema JSON.
Mode skema:
- Mode skema READONLY_OVERRIDE.
Nilai konfigurasi skema:
- Nilai konfigurasi Normalize dan Alias.
Metode API:
- Metode ModifySchemaTags (/subjects/{subject}/versions/{version}/tags).
- Metode GetLatestWithMetadata (/subjects/{subject}/metadata).
- Metode ListSchemas (/schemas).
- Metode DeleteSchemaMode.
- Untuk metode GetVersion: parameter format, deleted, dan findTags.
- Untuk metode CreateVersion: parameter metadata, ruleSet, schemaTagsToAdd, dan schemaTagsToRemove.
- Untuk metode UpdateSchemaMode: parameter force.
- Untuk metode GetSchemaMode: parameter defaultToGlobal.
- Untuk metode GetSchema: parameter WorkspaceMaxId dan findTags.
- Untuk metode ListVersions: parameter deletedOnly.
- Untuk metode ListSubjects: parameter deletedOnly.

Langkah berikutnya

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