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

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

Resource di Managed Service for Apache Kafka mencakup hal berikut:

  • Cluster

  • Topik

  • Grup konsumen

  • ACL

  • Registry skema

  • Konteks (dalam registry skema)

  • Subjek (dalam registry atau konteks skema)

  • Versi (versi skema dalam subjek)

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

Untuk mengetahui informasi selengkapnya tentang penamaan resource Google Cloud umum, lihat Nama resource. API registry skema untuk Managed Service for 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}

  • Schema registry: 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 rincian setiap komponen di bagian berikutnya.

ID Project

Nilainya 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 berupa salah satu lokasi Managed Service for Apache Kafka yang didukung. Untuk mengetahui daftar lokasi yang tersedia, lihat lokasi Managed Service for 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 diawali dengan string goog

  • Diawali dengan huruf

  • Batasan panjang:

    • ID cluster: berisi antara 3 dan 255 karakter.

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

    • ID registri 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 diawali 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 pendaftaran 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 +.

ID ACL

acl_id menentukan pola resource yang berlaku untuk entri ACL. Semua entri ACL dalam ACL berlaku untuk pola resource yang dienkode dalam ID ACL.

acl_id harus disusun seperti salah satu dari berikut:

  • Untuk ACL di cluster:

    • cluster

  • Untuk ACL pada satu resource dalam cluster:

    • topic/{RESOURCE_NAME}
    • consumerGroup/{RESOURCE_NAME}
    • transactionalId/{RESOURCE_NAME}

  • Untuk ACL pada semua resource yang cocok dengan awalan:

    • topicPrefixed/{RESOURCE_NAME}
    • consumerGroupPrefixed/{RESOURCE_NAME}
    • transactionalIdPrefixed/{RESOURCE_NAME}

  • Untuk ACL pada semua resource dari jenis tertentu (wildcard):

    • allTopics (mewakili topic/*)
    • allConsumerGroups (mewakili consumerGroup/*)
    • allTransactionalIds (mewakili transactionalId/*)

{RESOURCE_NAME}: Nama resource tertentu.

Contoh:

  • Untuk memberikan izin pada topik tertentu my-topic: topic/my-topic
  • Untuk memberikan izin pada semua topik yang dimulai dengan test-: topicPrefixed/test-
  • Untuk memberikan izin pada cluster itu sendiri: cluster
  • Untuk memberikan izin pada grup mana pun: allConsumerGroups
  • Untuk memberikan izin pada ID transaksi tertentu tx-id: transactionalId/tx-id

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 dalam URL.

Misalnya, mi-tópico adalah ID yang tidak valid jika ó bukan karakter yang diizinkan untuk jenis ID resource tertentu tersebut. 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 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. Berbagai strategi menawarkan tingkat fleksibilitas dan kontrol yang berbeda 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 berasal 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 diterapkan, sehingga cocok untuk banyak kasus penggunaan.

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

Berikut adalah daftar kerugian menggunakan TopicNameStrategy:

  • Setiap topik hanya dapat menangani satu jenis pesan secara efektif 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 rekaman 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 dengan topik, Anda dapat mengirim berbagai jenis data ke topik Kafka yang sama. Hal ini dapat dilakukan selama setiap jenis data memiliki nama lengkap yang unik dan skema yang sesuai yang 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 rekaman tertentu. Hal ini dapat membatasi jika Anda memerlukan versi jenis catatan yang sama yang berbeda dalam 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 rekaman, 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 kumpulan 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 bisa menjadi cukup panjang karena kombinasi nama topik dan nama rekaman yang sepenuhnya memenuhi syarat.
Apache Kafka® adalah merek dagang terdaftar milik The Apache Software Foundation atau afiliasinya di Amerika Serikat dan/atau negara lain.