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 setiap kolom 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.

Menggunakan paket skema memberikan manfaat berikut:

• Menghemat waktu dan tenaga: dengan buffer protokol, Anda cukup 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 kebenaran, 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 file proto yang dapat dibaca mesin. Kemudian, Anda menggunakan set deskriptor ini untuk membuat paket skema.

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

Diagram berikut menunjukkan proses penggunaan skema di Bigtable:

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

Anda dapat membuat paket skema menggunakan konsol Google Cloud atau 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

Konsol

1. Di konsol Google Cloud , buka daftar instance Bigtable.

   Buka daftar instance

2. Pilih instance dari daftar.

3. Di panel navigasi, klik Bigtable Studio.

4. Di panel Explorer, di samping tabel tempat Anda ingin membuat paket skema, klik menu tindakan more_vert, lalu klik Create schema bundle.

5. Di dialog Create schema bundle, di kolom Schema Bundle ID, masukkan ID paket skema yang unik.

   ID harus memiliki panjang 1 hingga 50 karakter, hanya boleh berisi huruf, angka, garis bawah, dan tanda hubung, tidak boleh diawali dengan tanda hubung, dan tidak boleh berisi karakter titik (.).

6. Di kolom File Descriptor Set (.pb file), klik Browse untuk memilih set deskriptor file protobuf yang Anda buat di bagian Membuat set deskriptor file protobuf dalam dokumen ini. Ukuran file tidak boleh lebih dari 4 MB.

7. Klik Create.

   Paket skema akan terbuka di tab baru.

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 tempat Anda membuat paket skema.
• TABLE_ID: ID tabel tempat Anda membuat paket skema.
• PROTO_DESCRIPTORS_FILE: jalur ke set deskriptor yang Anda buat di bagian Buat set deskriptor file protobuf dalam dokumen ini.

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

Konsol

1. Di konsol Google Cloud , buka daftar instance Bigtable.

   Buka daftar instance

2. Pilih instance dari daftar.

3. Di panel navigasi, klik Bigtable Studio.

4. Di panel Explorer, luaskan tabel yang berisi paket skema, lalu luaskan Schema Bundles.

5. Klik paket skema yang ingin Anda lihat, atau klik menu tindakan more_vert di samping paket skema, lalu klik Lihat detail.

   Tab yang terbuka akan menampilkan definisi paket skema.

6. Opsional: Untuk membuka tab editor kueri SQL dengan kueri contoh yang menggunakan paket skema, klik menu tindakan more_vert di samping paket skema, lalu klik Contoh kueri.

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(
          "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

Konsol

1. Di konsol Google Cloud , buka daftar instance Bigtable.

   Buka daftar instance

2. Pilih instance dari daftar.

3. Di panel navigasi, klik Bigtable Studio.

4. Di panel Explorer, luaskan tabel yang berisi paket skema yang ingin Anda lihat.

5. Luaskan Schema Bundles.

   Daftar paket skema dalam tabel akan muncul. Jika tabel tidak memiliki paket skema, daftar Paket Skema tidak ditampilkan.

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 {
  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 set deskriptor baru kompatibel dengan versi lama. Jika Bigtable mendeteksi ketidakcocokan, update akan gagal dengan error FailedPrecondition. Sebaiknya Anda mencadangkan nomor kolom yang dihapus untuk mencegah penggunaannya kembali. 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. Namun, Anda tidak dapat memaksakan perubahan yang tidak kompatibel jika paket skema sedang digunakan oleh tampilan terwujud berkelanjutan atau tampilan logis. Tampilan bergantung pada definisi pesan paket skema untuk mengurai dan membuat kueri data, sehingga perubahan yang tidak kompatibel akan merusak kueri terhadap tampilan logis dan menyebabkan tampilan terwujud berkelanjutan gagal selama pemrosesan data. Untuk membuat perubahan yang tidak kompatibel dengan versi sebelumnya pada paket skema yang dirujuk oleh tampilan, Anda harus memperbarui atau menghapus tampilan yang merujuk terlebih dahulu.

Konsol

1. Di konsol Google Cloud , buka daftar instance Bigtable.

   Buka daftar instance

2. Pilih instance dari daftar.

3. Di panel navigasi, klik Bigtable Studio.

4. Di panel Explorer, luaskan tabel yang berisi paket skema, lalu luaskan Schema Bundles.

5. Di samping paket skema yang ingin Anda perbarui, klik menu tindakan more_vert, lalu klik Perbarui.

6. Di dialog Update schema bundle, di kolom File Descriptor Set (.pb file), pilih set deskriptor file protobuf baru. Ukuran file tidak boleh melebihi 4 MB.

7. Klik Simpan.

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. Anda tidak dapat memaksakan perubahan yang tidak kompatibel jika paket skema sedang digunakan oleh tampilan terwujud berkelanjutan atau tampilan logis.

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

Peringatan: Tindakan ini bersifat permanen.

Anda tidak dapat menghapus paket skema jika sedang digunakan oleh tampilan terwujud berkelanjutan atau tampilan logis. Menghapus paket akan menyebabkan kueri terhadap tampilan logis gagal dan mencegah tampilan terwujud berkelanjutan memproses data masuk. Untuk menghapus paket skema, Anda harus menghapus tampilan yang mereferensikannya terlebih dahulu, atau memperbaruinya untuk menghapus referensi.

Konsol

1. Di konsol Google Cloud , buka daftar instance Bigtable.

   Buka daftar instance

2. Pilih instance dari daftar.

3. Di panel navigasi, klik Bigtable Studio.

4. Di panel Explorer, luaskan tabel yang berisi paket skema, lalu luaskan Schema Bundles.

5. Di samping paket skema yang ingin Anda hapus, klik menu tindakan more_vert, lalu klik Hapus.

6. Pada dialog konfirmasi, klik Delete.

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(
      "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 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

• Pelajari cara membuat kueri data protobuf.
• Baca tentang kueri yang berubah atau tidak pasti.
• Lihat Ringkasan GoogleSQL untuk Bigtable.