Pedoman untuk memberi nama resource Google Cloud Managed Service for Apache Kafka

Google Cloud Resource adalah komponen apa pun yang Anda buat atau gunakan dalam the Google Cloud. Resource ini membentuk blok penyusun aplikasi dan sistem yang berjalan di platform.

Resource di Managed Service untuk Apache Kafka mencakup hal berikut:

  • Cluster

  • Topik

  • Grup konsumen

  • ACL

  • Registry skema

  • Konteks (dalam registry skema)

  • Subjek (dalam registry skema atau konteks)

  • Versi (versi skema dalam subjek)

  • Skema (diidentifikasi berdasarkan ID, dikaitkan dengan satu atau beberapa subjek dan versi)

Untuk mengetahui informasi selengkapnya tentang penamaan resource umum Google Cloud , lihat Nama resource. API registry skema untuk Managed Service untuk Apache Kafka dirancang agar kompatibel dengan API open source yang ada, sehingga beberapa konvensi penamaan mungkin berbeda dari standar API umum.

Format penamaan resource

Berikut adalah format untuk berbagai resource:

  • Cluster: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}

  • Topik: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/topics/{TOPIC_ID}

  • Grup konsumen: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/consumerGroup/{CONSUMER_GROUP_ID}

  • ACL: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/clusters/{CLUSTER_ID}/acl/{ACL_ID}

  • Registry skema: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}

  • Konteks: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}

  • Subjek:

    • Dalam konteks default: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}
    • Dalam konteks tertentu: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}

  • Skema (diidentifikasi berdasarkan ID):

    • Dalam konteks default: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/schemas/ids/{SCHEMA_ID}
    • Dalam konteks tertentu: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/schemas/ids/{SCHEMA_ID}

  • Versi (diidentifikasi berdasarkan nomor versi dalam subjek):

    • Dalam konteks default: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}
    • Dalam konteks tertentu: projects/{PROJECT_ID}/locations/{LOCATION_NAME}/schemaRegistries/{SCHEMA_REGISTRY_ID}/contexts/{CONTEXT_ID}/subjects/{SUBJECT_ID}/versions/{VERSION_ID}

Berikut adalah rincian setiap komponen di bagian berikutnya.

project ID

Nilai harus berupa project ID atau nomor project, yang tersedia dari konsol Google Cloud . Misalnya, my-cool-project adalah project ID, sedangkan 123456789123 adalah nomor project.

Lokasi

Nilai harus salah satu lokasi Managed Service untuk Apache Kafka yang didukung. Untuk mengetahui daftar lokasi yang tersedia, lihat Lokasi Managed Service untuk Apache Kafka.

ID

ID adalah segmen terakhir dalam jalur resource. Variabel seperti {CLUSTER_ID}, {TOPIC_ID}, {CONSUMER_GROUP_ID}, {SCHEMA_REGISTRY_ID}, {CONTEXT_ID}, dan {SUBJECT_ID} harus sesuai dengan panduan berikut:

  • Tidak dimulai dengan string goog

  • Diawali dengan huruf

  • Batasan panjang:

    • ID Cluster: berisi antara 3 dan 53 karakter.

    • ID Topik, Grup Konsumen: Panjang apa pun yang diizinkan oleh Apache Kafka. Nama topik Apache Kafka dibatasi hingga 249 karakter.

    • ID registry skema: berisi hingga 255 karakter.

    • ID konteks: berisi hingga 255 karakter.

    • ID subjek: berisi hingga 255 byte UTF-8.

  • Batasan karakter:

    • ID Cluster: Harus cocok dengan regex ^[a-z]([-a-z0-9]*[a-z0-9])?. Artinya, huruf kecil, angka, dan tanda hubung. Nama ini harus dimulai dengan huruf dan tidak boleh diakhiri dengan tanda hubung.

    • ID Topik, Grup Konsumen: Validasi dilakukan oleh Kafka. Karakter yang diizinkan adalah `[a-zA-Z0-9.-], yang mencakup alfanumerik ASCII, titik (.), garis bawah (), dan tanda hubung (-).

    • ID registry skema: huruf (huruf besar atau huruf kecil), angka, dan garis bawah _.

    • ID konteks: huruf (huruf besar atau huruf kecil), angka, dan karakter khusus berikut: tanda hubung -, titik ., garis bawah _, tilde ~, persen %, atau tanda tambah +.

    • ID subjek: huruf (huruf besar atau huruf kecil), angka, dan karakter khusus berikut: tanda hubung -, titik ., garis bawah _, tilde ~, persen %, atau tanda tambah +.

Karakter khusus

Anda dapat menggunakan karakter khusus yang tercantum di bagian sebelumnya dalam ID resource tanpa encoding URL. Namun, Anda harus memastikan bahwa karakter khusus lainnya dienkode atau didekode dengan benar saat digunakan di URL.

Misalnya, mi-tópico adalah ID yang tidak valid jika ó bukan karakter yang diizinkan untuk jenis ID resource tertentu. Namun, mi-topico akan valid jika hanya huruf Latin dasar yang diizinkan. Format ini penting saat melakukan panggilan REST.

Jika Anda mereferensikan topik dari library klien Kafka, jalur resource lengkap tidak akan digunakan. Hanya nama topik itu sendiri yang digunakan. Demikian pula, saat berinteraksi dengan skema menggunakan integrasi klien Kafka seperti serializer atau deserializer, Anda biasanya menggunakan nama subjek, bukan jalur resource lengkap.

Strategi penamaan subjek

Saat menggunakan registry skema, terutama dengan integrasi klien Kafka seperti serializer dan deserializer, nama subjek sangat penting. Strategi penamaan subjek menentukan cara skema didaftarkan dan diambil dari registry skema. Strategi yang berbeda menawarkan tingkat fleksibilitas dan kontrol yang berbeda-beda atas evolusi skema.

Anda dapat mengonfigurasi strategi penamaan subjek dengan menetapkan properti key.subject.name.strategy atau value.subject.name.strategy dalam konfigurasi klien Kafka.

TopicNameStrategy

Ini adalah strategi default untuk library klien Kafka open source.

Nama subjek diturunkan langsung dari nama topik Kafka, yang ditambahkan dengan key untuk kunci pesan atau value untuk nilai pesan. Jika auto.register.schema ditetapkan ke true, klien produsen akan menggunakan topicName-value atau topicName-key untuk topik bernama topicName.

Berikut beberapa contohnya:

  • Nama topik: orders
  • Subjek untuk nilai pesan: orders-value
  • Subjek untuk kunci pesan: orders-key

Berikut adalah daftar keuntungan menggunakan TopicNameStrategy:

  • Strategi ini mudah dipahami, sehingga cocok untuk banyak kasus penggunaan.

  • Skema terikat langsung ke topik, sehingga Anda dapat mengembangkan jenis data dalam satu topik secara independen.

Berikut adalah daftar kerugian menggunakan TopicNameStrategy:

  • Setiap topik hanya dapat menangani satu jenis pesan yang didasarkan pada skema nilai. Hal ini karena nama subjek ditetapkan ke nama topik. Jika Anda perlu mengirim berbagai jenis data ke topik yang sama, strategi ini tidak akan berfungsi.

RecordNameStrategy

Strategi ini menggunakan nama class yang sepenuhnya memenuhi syarat dari data Avro atau Protobuf sebagai nama subjek.

Berikut beberapa contohnya:

  • Nama skema Avro: com.example.data.Customer
  • Nama pesan Protobuf: com.example.data.Order
  • Subjek untuk skema customer: com.example.data.Customer
  • Subjek untuk skema order: com.example.data.Order

Berikut adalah daftar keuntungan menggunakan RecordNameStrategy:

  • Karena nama subjek tidak terikat ke topik, Anda dapat mengirim berbagai jenis data ke topik Kafka yang sama. Hal ini dapat dilakukan selama setiap jenis data memiliki nama yang sepenuhnya memenuhi syarat dan skema yang sesuai terdaftar.

  • Skema untuk jenis data tertentu seperti com.example.common.Address dapat digunakan di beberapa topik, dan evolusinya dikelola secara terpusat dalam satu subjek.

Berikut adalah daftar kerugian menggunakan RecordNameStrategy:

  • Anda harus menggunakan subjek dan versi yang sama untuk semua topik yang menggunakan jenis data tertentu. Hal ini dapat membatasi jika Anda memerlukan versi jenis data yang sama di topik yang berbeda.

TopicRecordNameStrategy

Strategi ini menggabungkan aspek TopicNameStrategy dan RecordNameStrategy.

Nama subjek adalah kombinasi dari nama topik Kafka dan nama class yang sepenuhnya memenuhi syarat dari data, yang diformat sebagai TOPIC_NAME-FULLY_QUALIFIED_CLASS_NAME.

Berikut beberapa contohnya:

  • Topik: user-events

  • Nama yang sepenuhnya memenuhi syarat: com.example.events.PageView

  • Nama subjek untuk kombinasi ini: user-events-com.example.events.PageView

  • Topik lain: product-interactions

  • Nama yang sepenuhnya memenuhi syarat: com.example.events.PageView

  • Nama subjek untuk kombinasi ini: product-interactions-com.example.events.PageView

Berikut adalah daftar keuntungan menggunakan TopicRecordNameStrategy:

  • Serupa dengan RecordNameStrategy, Anda dapat mengirim berbagai jenis data ke topik yang sama.

  • Tidak seperti RecordNameStrategy, strategi ini memungkinkan Anda mengembangkan skema untuk jenis data tertentu secara independen dalam setiap topik. Artinya, my-topic-com.example.project.MyRecord dapat berkembang secara berbeda dari another-topic-com.example.project.MyRecord.

Berikut adalah daftar kerugian menggunakan TopicRecordNameStrategy:

  • Nama subjek dapat menjadi cukup panjang karena kombinasi nama topik dan nama data yang sepenuhnya memenuhi syarat.
Apache Kafka® adalah merek dagang terdaftar dari The Apache Software Foundation atau afiliasinya di Amerika Serikat dan/atau negara lain.