Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Membuat subjek

Dokumen ini menjelaskan cara membuat subjek di registry skema. Subjek adalah penampung logis untuk berbagai versi skema. Saat 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 praktis, tetapi dapat menyebabkan potensi ketidakcocokan 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 untuk mengetahui detailnya.

Sebelum memulai

Pelajari tentang ringkasan skema.
Buat registry skema jika Anda belum memilikinya.
Pahami referensi skema.

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.

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

Di Google Cloud konsol, buka halaman Schema registries.

Buka Schema registries
Klik nama registry skema tempat Anda ingin membuat subjek.
Klik Create subject.
Untuk Subject name, masukkan nama unik untuk subjek Anda.

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.

Untuk mengetahui informasi selengkapnya tentang cara memilih nama subjek, lihat Strategi penamaan subjek.
Untuk Context, pilih konteks atau buat konteks baru. Konteks berfungsi seperti namespace untuk mengatur subjek dan skema Anda, sehingga memberikan isolasi antara grup yang berbeda.
- Untuk menggunakan konteks yang ada, pilih konteks dari daftar Context. Konteks default ditampilkan sebagai (default context).
- Untuk membuat konteks baru, lakukan langkah-langkah berikut:
  1. Pilih Create context dari daftar Context.
  2. Di kolom Context name, masukkan nama untuk konteks.
    
    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.
  3. Klik Save.
Untuk Schema type, pilih Avro atau Protocol Buffer.
Di kolom Schema definition, masukkan definisi skema. Format skema harus cocok dengan jenis skema. Jangan menyertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan di nama kolom skema Anda.
Jika skema Anda menggunakan atau bergantung pada struktur data yang ditentukan dalam skema lain di registry skema, lakukan langkah-langkah berikut:
1. Klik Add Schema reference.
2. Di kolom Reference name, masukkan nama referensi skema yang direferensikan.
3. Di daftar Subject, pilih subjek yang berisi skema yang direferensikan.
4. Di daftar Version, pilih nomor versi skema yang direferensikan.
5. Klik OK.
Ulangi langkah-langkah ini untuk setiap skema yang direferensikan.
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 koleksi subjek menggunakan projects.locations.schemaRegistries.contexts.subjects.versions.create metode:

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 Anda. Google Cloud
LOCATION (wajib): region tempat registry skema berada. Google Cloud
REGISTRY_ID (wajib): ID registry skema target.
CONTEXT_ID (opsional): ID konteks yang berisi subjek. Gunakan . untuk konteks default jika Anda ingin menjadi eksplisit, jika tidak, hapus /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 menyertakan informasi sensitif seperti informasi identitas pribadi (PII) atau data keamanan di nama kolom skema Anda.
schemaType (opsional): jenis skema. Dapat berupa AVRO atau PROTOBUF. Default-nya adalah AVRO jika dihilangkan.
references (opsional): array objek yang menentukan skema apa pun yang direferensikan oleh skema ini.
- REFERENCE_NAME: nama yang digunakan untuk mereferensikan skema lain dalam definisi skema ini.
- REFERENCED_SUBJECT_ID: ID subjek skema yang direferensikan.
- REFERENCED_VERSION_NUMBER: nomor versi tertentu dari skema subjek yang direferensikan.
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 mendapatkan informasi lebih lanjut, lihat dokumentasi REST API.

Langkah berikutnya

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