Membuat dan mengelola skema protobuf

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

Di Bigtable, Anda dapat menggunakan skema protocol buffer (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 protocol buffer, Anda menentukan struktur data sekali dalam file proto, lalu menggunakan kode sumber yang dihasilkan untuk menulis dan membaca data Anda.
  • Meningkatkan konsistensi data: Dengan menggunakan file proto sebagai satu sumber tepercaya, Anda dapat memastikan bahwa semua aplikasi dan layanan menggunakan model data yang sama.
  • Menghilangkan duplikasi data: Anda dapat menggunakan protocol buffer 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 protoc, untuk membuat kumpulan deskripsi file protobuf, yang merupakan skema file proto yang dapat dibaca mesin. Kemudian, Anda menggunakan kumpulan deskripsi ini untuk membuat paket skema.

Untuk contoh file proto dan kumpulan deskripsi 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

Ikuti 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) di tabel.

Peran bawaan ini berisi izin yang diperlukan Bigtable untuk menggunakan paket skema. Untuk melihat izin yang benar-benar diperlukan, perluas 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 kumpulan deskripsi file protobuf

Sebelum dapat membuat paket skema, Anda harus membuat kumpulan deskripsi 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 menelusuri file proto.
    • DESCRIPTOR_OUTPUT_LOCATION: direktori tempat compiler protoc menyimpan kumpulan deskripsi yang dihasilkan.
    • PATH_TO_PROTO: jalur ke file proto Anda.

Misalnya, untuk membuat kumpulan deskripsi 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 gcloud bigtable schema-bundles create perintah:

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 tempat paket skema akan dibuat.
  • TABLE_ID: ID tabel tempat paket skema akan dibuat.
  • PROTO_DESCRIPTORS_FILE: jalur ke kumpulan deskripsi yang dibuat 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)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  CreateSchemaBundleRequest request =
      CreateSchemaBundleRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .setSchemaBundleId(schemaBundleId)
          .setSchemaBundle(schemaBundleObj)
          .build();
  SchemaBundle schemaBundle = adminClient.createSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s created successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to create a schema bundle: " + e.getMessage());
}

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 gcloud bigtable schema-bundles describe perintah:

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 kumpulan deskripsi 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(
          "projects/"
              + projectId
              + "/instances/"
              + instanceId
              + "/tables/"
              + tableId
              + "/schemaBundles/"
              + schemaBundleId);
  // Deserialize and print the FileDescriptorSet
  DescriptorProtos.FileDescriptorSet fileDescriptorSet =
      DescriptorProtos.FileDescriptorSet.parseFrom(
          schemaBundle.getProtoSchema().getProtoDescriptors());

  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 gcloud bigtable schema-bundles list perintah:

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 {
  ListSchemaBundlesRequest request =
      ListSchemaBundlesRequest.newBuilder()
          .setParent(
              "projects/" + projectId + "/instances/" + instanceId + "/tables/" + tableId)
          .build();
  for (SchemaBundle bundle : adminClient.listSchemaBundles(request).iterateAll()) {
    String id = SchemaBundleName.parse(bundle.getName()).getSchemaBundle();
    System.out.println(id);
    schemaBundleIds.add(id);
  }
} 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 kumpulan deskripsi baru kompatibel dengan versi lama. Jika tidak kompatibel, update akan gagal dengan error FailedPrecondition. Sebaiknya cadangkan 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 memaksa update, Anda dapat menggunakan flag --ignore-warnings dengan gcloud CLI.

gcloud

Untuk memperbarui paket skema agar menggunakan kumpulan deskripsi 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 kumpulan deskripsi baru.

Opsional: Untuk memaksa update meskipun ada perubahan yang tidak kompatibel, tambahkan perintah dengan flag --ignore-warnings. Jika tampilan terwujud berkelanjutan atau tampilan logis menggunakan paket skema, Anda tidak boleh memaksa perubahan yang tidak kompatibel.

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)) {
  if (in == null) {
    throw new FileNotFoundException("Resource not found: " + PROTO_FILE_PATH);
  }
  SchemaBundle schemaBundleObj =
      SchemaBundle.newBuilder()
          .setName(
              "projects/"
                  + projectId
                  + "/instances/"
                  + instanceId
                  + "/tables/"
                  + tableId
                  + "/schemaBundles/"
                  + schemaBundleId)
          .setProtoSchema(
              ProtoSchema.newBuilder().setProtoDescriptors(ByteString.readFrom(in)).build())
          .build();
  UpdateSchemaBundleRequest request =
      UpdateSchemaBundleRequest.newBuilder()
          .setSchemaBundle(schemaBundleObj)
          .setUpdateMask(FieldMask.newBuilder().addPaths("proto_schema").build())
          .build();
  SchemaBundle schemaBundle = adminClient.updateSchemaBundleAsync(request).get();
  System.out.printf("Schema bundle: %s updated successfully%n", schemaBundle.getName());
} catch (Exception e) {
  System.err.println("Failed to modify schema bundle: " + e.getMessage());
}

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.

Jika tampilan terwujud berkelanjutan atau tampilan logis menggunakan paket skema, jangan hapus paket tersebut.

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(
      "projects/"
          + projectId
          + "/instances/"
          + instanceId
          + "/tables/"
          + tableId
          + "/schemaBundles/"
          + 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 protocol buffer 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.
  • Jika tampilan terwujud berkelanjutan atau tampilan logismenggunakan paket skema, Anda tidak boleh memaksa perubahan yang tidak kompatibel atau menghapus paket tersebut.

Langkah berikutnya