Membuat dan mengelola skema protobuf

Dokumen ini menjelaskan cara membuat dan melakukan operasi pada paket skema.

Di Bigtable, Anda dapat menggunakan skema buffer protokol (protobuf) untuk membuat kueri kolom individual dalam pesan protobuf yang disimpan sebagai byte di kolom Anda. Anda melakukannya dengan mengupload skema dalam paket skema, resource tingkat tabel yang berisi satu atau beberapa skema protobuf Anda.

Penggunaan paket skema menawarkan manfaat berikut:

  • Menghemat waktu dan tenaga: Dengan buffer protokol, Anda menentukan struktur data satu kali dalam file proto, lalu menggunakan kode sumber yang dihasilkan untuk menulis dan membaca data.
  • Meningkatkan konsistensi data: Dengan menggunakan file proto sebagai sumber kebenaran tunggal, Anda dapat memastikan bahwa semua aplikasi dan layanan menggunakan model data yang sama.
  • Menghilangkan duplikasi data: Anda dapat menggunakan buffer protokol di seluruh project dengan menentukan jenis pesan dalam file proto yang berada di luar codebase project tertentu.

Proses penggunaan skema di Bigtable dimulai dengan file proto Anda. File proto adalah file teks tempat Anda menentukan struktur data. Anda menggunakan alat compiler protobuf, yang juga disebut sebagai protoc, untuk membuat set deskriptor file protobuf, yang merupakan skema yang dapat dibaca mesin dari file proto Anda. Kemudian, Anda menggunakan set deskriptor ini untuk membuat paket skema.

Untuk melihat contoh file proto dan set deskriptor yang sesuai, lihat Contoh data.

Diagram berikut menunjukkan proses penggunaan skema di Bigtable:

Proses penggunaan skema protobuf di Bigtable.
Gambar 1. Proses penggunaan skema protobuf di Bigtable (klik untuk memperbesar).

Anda dapat membuat paket skema menggunakan Google Cloud CLI. Setelah mengupload paket skema ke Bigtable, Anda dapat membuat kueri data menggunakan pembuat kueri Bigtable Studio, GoogleSQL untuk Bigtable, atau tabel eksternal Bigtable di BigQuery.

Sebelum memulai

Lakukan langkah-langkah berikut jika Anda berencana menggunakan gcloud CLI:

  1. Instal Google Cloud CLI.

  2. Lakukan inisialisasi gcloud CLI:

    gcloud init

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna membuat dan mengelola paket skema, minta administrator untuk memberi Anda peran Identity and Access Management (IAM) Bigtable Admin (roles/bigtable.admin) pada tabel.

Peran bawaan ini berisi izin yang diperlukan Bigtable untuk bekerja dengan paket skema. Untuk melihat izin yang benar-benar diperlukan, luaskan bagian Izin yang diperlukan:

Izin yang diperlukan

  • bigtable.schemaBundles.create
  • bigtable.schemaBundles.update
  • bigtable.schemaBundles.delete
  • bigtable.schemaBundles.get
  • bigtable.schemaBundles.list

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Untuk mengetahui informasi selengkapnya tentang peran dan izin Bigtable, lihat Kontrol akses dengan IAM.

Membuat set deskriptor file protobuf

Sebelum dapat membuat paket skema, Anda harus membuat set deskriptor dari file proto dengan alat compiler protobuf.

  1. Untuk menginstal compiler, download paketnya dan ikuti petunjuk dalam file README.

  2. Jalankan compiler:

    protoc --proto_path=IMPORT_PATH --include_imports \
   --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO

    Ganti kode berikut:

    • IMPORT_PATH: direktori tempat compiler protoc mencari file proto.
    • DESCRIPTOR_OUTPUT_LOCATION: direktori tempat compiler protoc menyimpan set deskriptor yang dihasilkan.
    • PATH_TO_PROTO: jalur ke file proto Anda.

Misalnya, untuk membuat set deskriptor bernama library.pb untuk file library.proto di direktori saat ini, Anda dapat menggunakan perintah berikut:

protoc --include_imports --descriptor_set_out=library.pb
library.proto

Membuat paket skema

gcloud

Untuk membuat paket skema, gunakan perintah gcloud bigtable schema-bundles create:

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

Ganti kode berikut:

  • SCHEMA_BUNDLE_ID: ID unik untuk paket skema baru yang tidak boleh berisi karakter titik ('.').
  • INSTANCE_ID: ID instance untuk membuat paket skema.
  • TABLE_ID: ID tabel tempat membuat paket skema.
  • PROTO_DESCRIPTORS_FILE: jalur ke set deskriptor yang dihasilkan pada langkah sebelumnya.

Java

Untuk membuat paket skema, gunakan metode createSchemaBundle:

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Bigtable, lihat Library klien Bigtable.

Untuk melakukan autentikasi ke Bigtable, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

try {
  InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH);
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.of(tableId, schemaBundleId)
          .setProtoSchema(ByteString.readFrom(in));
  SchemaBundle schemaBundle = adminClient.createSchemaBundle(request);
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getId());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to create a schema bundle from a non-existent table: " + e.getMessage());
} catch (IOException e) {
  throw new RuntimeException(e);
}

Melihat informasi tentang paket skema

Sebelum dapat melihat informasi tentang paket skema, Anda harus memiliki tabel Bigtable dengan setidaknya satu paket skema. Anda bisa mendapatkan informasi tentang paket skema dalam tabel dengan mengambil definisi satu paket skema atau dengan mencantumkan semua paket skema dalam tabel.

Mendapatkan definisi paket skema

gcloud

Untuk mendapatkan detail tentang paket skema, gunakan perintah gcloud bigtable schema-bundles describe:

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Ganti kode berikut:

  • SCHEMA_BUNDLE_ID: ID paket skema.
  • INSTANCE_ID: ID instance.
  • TABLE_ID: ID tabel.

Java

Untuk mendapatkan definisi paket skema, gunakan metode getSchemaBundle. Metode ini menampilkan objek SchemaBundle yang berisi definisi skema.

Contoh berikut menunjukkan cara mendapatkan paket skema dan mendeserialisasi set deskriptor untuk mencetak konten skema:

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Bigtable, lihat Library klien Bigtable.

Untuk melakukan autentikasi ke Bigtable, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

SchemaBundle schemaBundle = null;
try {
  schemaBundle = adminClient.getSchemaBundle(tableId, schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(schemaBundle.getProtoSchema());

  System.out.println("--------- Deserialized FileDescriptorSet ---------");
  for (DescriptorProtos.FileDescriptorProto fileDescriptorProto :
      fileDescriptorSet.getFileList()) {
    System.out.println("File: " + fileDescriptorProto.getName());
    System.out.println("  Package: " + fileDescriptorProto.getPackage());
    for (DescriptorProtos.DescriptorProto messageType :
        fileDescriptorProto.getMessageTypeList()) {
      System.out.println("  Message: " + messageType.getName());
    }
  }
  System.out.println("--------------------------------------------------");
} catch (InvalidProtocolBufferException e) {
  System.err.println("Failed to parse FileDescriptorSet: " + e.getMessage());
} catch (NotFoundException e) {
  System.err.println(
      "Failed to retrieve metadata from a non-existent schema bundle: " + e.getMessage());
}

Outputnya mirip dengan hal berikut ini:

--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------

Mencantumkan paket skema dalam tabel

gcloud

Untuk melihat daftar paket skema untuk tabel, gunakan perintah gcloud bigtable schema-bundles list:

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Ganti kode berikut:

  • INSTANCE_ID: ID instance.
  • TABLE_ID: ID tabel.

Java

Untuk melihat daftar semua paket skema dalam tabel, gunakan metode listSchemaBundles. Metode ini menampilkan daftar ID paket skema.

Contoh berikut menunjukkan cara mencantumkan paket skema dalam tabel:

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Bigtable, lihat Library klien Bigtable.

Untuk melakukan autentikasi ke Bigtable, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

List<String> schemaBundleIds = new ArrayList<>();
try {
  schemaBundleIds = adminClient.listSchemaBundles(tableId);
  for (String schemaBundleId : schemaBundleIds) {
    System.out.println(schemaBundleId);
  }
} catch (NotFoundException e) {
  System.err.println(
      "Failed to list schema bundles from a non-existent table: " + e.getMessage());
}

Outputnya mirip dengan hal berikut ini:

my-schema-bundle-1
my-schema-bundle-2

Memperbarui paket skema

Saat Anda memperbarui paket skema, Bigtable akan memeriksa apakah set deskriptor baru kompatibel dengan versi lama yang ada. Jika tidak kompatibel, update akan gagal dengan error FailedPrecondition. Sebaiknya Anda mencadangkan nomor kolom yang dihapus untuk mencegah penggunaan ulang. Untuk mengetahui informasi selengkapnya, lihat Praktik Terbaik Proto dalam dokumentasi protobuf.

Jika Anda yakin bahwa perubahan yang tidak kompatibel aman dan ingin memaksakan update, Anda dapat menggunakan flag --ignore-warnings dengan gcloud CLI.

gcloud

Untuk memperbarui paket skema agar menggunakan set deskriptor yang berbeda, gunakan perintah gcloud bigtable schema-bundles update:

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --proto-descriptors-file=PROTO_DESCRIPTORS_FILE

Ganti kode berikut:

  • SCHEMA_BUNDLE_ID: ID paket skema yang akan diperbarui.
  • INSTANCE_ID: ID instance yang berisi paket skema.
  • TABLE_ID: ID tabel yang berisi paket skema.
  • PROTO_DESCRIPTORS_FILE: jalur ke file set deskriptor baru.

Opsional: Untuk memaksa update meskipun ada perubahan yang tidak kompatibel, tambahkan perintah dengan flag --ignore-warnings.

Java

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Bigtable, lihat Library klien Bigtable.

Untuk melakukan autentikasi ke Bigtable, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

try {
  InputStream in = getClass().getClassLoader().getResourceAsStream(PROTO_FILE_PATH);
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.of(tableId, schemaBundleId)
          .setProtoSchema(ByteString.readFrom(in));
  SchemaBundle schemaBundle = adminClient.updateSchemaBundle(request);
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getId());
} catch (NotFoundException e) {
  System.err.println("Failed to modify a non-existent schema bundle: " + e.getMessage());
} catch (IOException e) {
  throw new RuntimeException(e);
}

Menghapus paket skema

gcloud

Untuk menghapus paket skema, gunakan perintah gcloud bigtable schema-bundles delete:

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Ganti kode berikut:

  • SCHEMA_BUNDLE_ID: ID paket skema yang akan dihapus.
  • INSTANCE_ID: ID instance yang berisi paket skema.
  • TABLE_ID: ID tabel yang berisi paket skema.

Java

Untuk mempelajari cara menginstal dan menggunakan library klien untuk Bigtable, lihat Library klien Bigtable.

Untuk melakukan autentikasi ke Bigtable, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal. 

try {
  adminClient.deleteSchemaBundle(tableId, schemaBundleId);
  System.out.printf("SchemaBundle: %s deleted successfully%n", schemaBundleId);
} catch (NotFoundException e) {
  System.err.println("Failed to delete a non-existent schema bundle: " + e.getMessage());
}

Batasan

Paket skema memiliki batasan berikut:

  • Anda dapat membuat maksimal 10 paket skema per tabel.
  • Ukuran total deskriptor buffer protokol yang diserialkan dalam paket skema tidak boleh melebihi 4 MB. Tidak ada batasan langsung pada jumlah skema individual yang dapat Anda sertakan dalam paket, selama ukuran total paket tidak melebihi batas ini.

Langkah berikutnya