Membuat subjek

Dokumen ini menjelaskan cara membuat subjek di registry skema. Subjek adalah penampung logis untuk berbagai versi skema. Saat Anda membuat subjek untuk pertama kalinya, Anda juga membuat versi pertama skema untuk subjek tersebut.

Anda dapat membuat subjek dengan salah satu cara berikut:

  • Implisit (default): perilaku default untuk banyak klien produsen dan konsumen adalah membuat skema yang tidak ada secara otomatis saat klien terhubung. Subjek dan versi yang mereferensikan skema juga dibuat secara otomatis. Hal ini memang praktis, tetapi dapat menyebabkan potensi inkonsistensi dalam data jika beberapa klien membuat versi secara bersamaan.

  • Eksplisit (direkomendasikan): dalam metode ini, setiap skema harus dibuat di registry sebelum klien produsen atau konsumen dapat menggunakannya. Anda dapat menggunakan Google Cloud konsol atau Managed Kafka API untuk melakukannya.

Perilaku ini harus dikonfigurasi di setelan klien Anda. Lihat dokumentasi library klien serializer atau deserializer Anda untuk mengetahui detailnya.

Sebelum memulai

Peran dan izin yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat subjek, minta administrator untuk memberi Anda peran IAM Managed Kafka Schema Registry Editor (roles/managedkafka.schemaRegistryEditor) di project atau registry skema 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 membuat subjek. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk membuat 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 untuk membuat dan mengelola versi subjek.

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

Membuat subjek atau versi pertama skema

Saat membuat subjek, Anda juga membuat versi pertamanya. Versi pertama ini membuat skema baru atau merupakan referensi ke skema yang ada.

Konsol

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

    Buka Schema registry

  2. Klik nama registry skema tempat Anda ingin membuat subjek.

  3. Klik Buat subjek.

  4. Untuk Nama subjek, masukkan nama unik untuk subjek Anda.

    Nama harus diawali dengan huruf dan hanya berisi huruf, angka, dan karakter khusus berikut: tanda hubung (-), titik (.), garis bawah (_), tilde (~), persen (%), atau tanda tambah (+). Nama subjek tidak dapat diubah.

    Untuk mengetahui informasi selengkapnya tentang cara memilih nama subjek, lihat Strategi penamaan subjek.

  5. Untuk Konteks, pilih konteks atau buat konteks baru. Konteks berfungsi seperti namespace untuk mengatur subjek dan skema Anda, sehingga memberikan isolasi di antara grup yang berbeda.

    • Untuk menggunakan konteks yang ada, pilih konteks dari daftar Konteks. Konteks default ditampilkan sebagai (default context).

    • Untuk membuat konteks baru, lakukan langkah-langkah berikut:

      1. Pilih Buat konteks dari daftar Konteks.

      2. Di kolom Nama konteks, masukkan nama untuk konteks.

        Nama harus diawali dengan huruf dan hanya berisi huruf, angka, dan karakter khusus berikut: tanda hubung (-), titik (.), garis bawah (_), tilde (~), persen (%), atau tanda tambah (+). Nama konteks tidak dapat diubah.

      3. Klik Simpan.

  6. Untuk Schema type, pilih Avro atau Protocol Buffer.

  7. Di kolom Schema definition, masukkan definisi skema. Format skema harus cocok dengan jenis skema. Jangan sertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan dalam nama kolom skema Anda.

  8. 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.

  9. Klik Create.

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.

Contoh REST API berikut membuat versi pertama subjek.

Untuk membuat subjek dalam konteks default, buat permintaan POST ke URI yang ditentukan menggunakan metode projects.locations.schemaRegistries.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/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 kumpulan subjek menggunakan metode projects.locations.schemaRegistries.contexts.subjects.versions.create:

POST https://managedkafka.googleapis.com/v1main/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 . untuk konteks default jika Anda ingin eksplisit, atau hilangkan /contexts/CONTEXT_ID untuk menggunakan konteks default secara implisit.

    Nama harus dimulai dengan huruf, dan hanya berisi huruf, angka, dan karakter khusus berikut: tanda pisah -, titik ., garis bawah _, tilde ~, persen %, atau tanda tambah +. Nama konteks tidak dapat diubah.

  • SUBJECT_ID (wajib): ID untuk subjek baru yang akan digunakan untuk membuat versi pertama.

    Nama harus dimulai dengan huruf, dan hanya berisi huruf, angka, dan karakter khusus berikut: tanda pisah -, titik ., garis bawah _, tilde ~, persen %, atau tanda tambah +. Nama subjek tidak dapat diubah.

Isi Permintaan:

Sertakan objek JSON di isi permintaan yang menentukan detail skema:

{
  "schema": "YOUR_SCHEMA_DEFINITION_STRING",
  "schema_type": "AVRO" | "PROTOBUF", // 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.

    Jangan sertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan dalam nama kolom skema Anda.

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

  • references (opsional): 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: ID subjek skema yang dirujuk.
    • REFERENCED_VERSION_NUMBER: nomor versi spesifik dari skema subjek yang dirujuk.

  • versionId, schemaId: kolom opsional yang biasanya ditangani oleh layanan. Untuk versi pertama subjek, versionId akan menjadi "1".

Jika permintaan berhasil dan skema valid serta lulus pemeriksaan kompatibilitas jika dikonfigurasi, API akan menampilkan kode status 200 OK. Isi respons berisi ID skema yang digunakan oleh versi yang dibuat, yang berbeda dengan ID versi.

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.