Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

protobuf スキーマを作成して管理する

このドキュメントでは、スキーマバンドルを作成してオペレーションを実行する方法について説明します。

Bigtable では、プロトコルバッファ（protobuf）スキーマを使用して、列にバイトとして保存されている protobuf メッセージ内の個々のフィールドをクエリできます。これを行うには、スキーマをスキーマバンドル（1 つ以上の protobuf スキーマを含むテーブルレベルのリソース）にアップロードします。

スキーマバンドルを使用すると、次のメリットがあります。

時間と労力を節約する: プロトコルバッファを使用すると、proto ファイルでデータ構造を一度定義するだけで、生成されたソースコードを使用してデータを読み書きできます。
データの整合性を向上させる: proto ファイルを単一の信頼できる情報源として使用することで、すべてのアプリケーションとサービスが同じデータモデルを使用していることを確認できます。
データ重複の排除: 特定のプロジェクトのコードベースの外部にある proto ファイルでメッセージタイプを定義することで、プロジェクト全体でプロトコルバッファを使用できます。

Bigtable でスキーマを使用するプロセスは、proto ファイルから始まります。proto ファイルは、データの構造を定義するテキストファイルです。protobuf コンパイラツール（protoc とも呼ばれます）を使用して、protobuf ファイル記述子セットを生成します。これは、proto ファイルの機械可読スキーマです。この記述子セットを使用して、スキーマバンドルを作成します。

proto ファイルとそれに対応する記述子セットの例については、データの例をご覧ください。

次の図は、Bigtable でスキーマを使用するプロセスを示しています。

Bigtable で protobuf スキーマを使用するプロセス。 — **図 1.** Bigtable で protobuf スキーマを使用するプロセス（クリックして拡大）。

**図 1.** Bigtable で protobuf スキーマを使用するプロセス（クリックして拡大）。

スキーマバンドルは、 Google Cloud コンソールまたは Google Cloud CLI を使用して作成できます。スキーマバンドルを Bigtable にアップロードすると、Bigtable Studio クエリビルダー、Bigtable 用 GoogleSQL、BigQuery の Bigtable 外部テーブルを使用してデータをクエリできます。

始める前に

gcloud CLI を使用する場合は、次の操作を行います。

Google Cloud CLI をインストールします。
gcloud CLI を初期化します。
```
gcloud init
```

必要なロール

スキーマバンドルの作成と管理に必要な権限を取得するには、テーブルに対する Bigtable 管理者（roles/bigtable.admin）Identity and Access Management（IAM）ロールを付与するよう管理者に依頼してください。

この事前定義ロールには、Bigtable がスキーマバンドルを操作するために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

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

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

Bigtable のロールと権限の詳細については、IAM によるアクセス制御をご覧ください。

protobuf ファイル記述子セットを生成する

スキーマバンドルを作成する前に、protobuf コンパイラツールを使用して、proto ファイルから記述子セットを生成する必要があります。

コンパイラをインストールするには、パッケージをダウンロードし、README ファイルの手順に沿って操作します。
コンパイラを実行します。
```
protoc --proto_path=IMPORT_PATH --include_imports \
   --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTO
```
次のように置き換えます。
- IMPORT_PATH: protoc コンパイラが proto ファイルを検索するディレクトリ。
- DESCRIPTOR_OUTPUT_LOCATION: protoc コンパイラが生成された記述子セットを保存するディレクトリ。
- PATH_TO_PROTO: proto ファイルのパス。

たとえば、現在のディレクトリにある library.proto ファイルの library.pb という名前の記述子セットを作成するには、次のコマンドを使用します。

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

スキーマバンドルを作成する

コンソール

Google Cloud コンソールで、Bigtable インスタンスのリストを開きます。

インスタンスのリストを開く
リストからインスタンスを選択します。
ナビゲーションパネルで [Bigtable Studio] をクリックします。
[エクスプローラ] ペインで、スキーマバンドルを作成するテーブルの横にある more_vert アクションメニューをクリックし、[スキーマバンドルを作成] をクリックします。
[スキーマバンドルを作成] ダイアログの [スキーマバンドル ID] フィールドに、スキーマバンドルの一意の識別子を入力します。

ID は 1 ～ 50 文字で指定します。使用できるのは英字、数字、アンダースコア、ハイフンのみです。先頭をハイフンにすることはできません。また、ピリオド（.）を含めることはできません。
[File Descriptor Set (.pb file)] フィールドで、[Browse] をクリックして、このドキュメントの protobuf ファイル記述子セットを生成するで作成した protobuf ファイル記述子セットを選択します。ファイルサイズは 4 MB 以下にしてください。
[作成] をクリックします。

スキーマバンドルが新しいタブで開きます。

gcloud

スキーマバンドルを作成するには、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

次のように置き換えます。

SCHEMA_BUNDLE_ID: 新しいスキーマバンドルの一意の ID。ピリオド（.）文字を含めることはできません。
INSTANCE_ID: スキーマバンドルを作成するインスタンスの ID。
TABLE_ID: スキーマバンドルを作成するテーブルの ID。
PROTO_DESCRIPTORS_FILE: このドキュメントの protobuf ファイル記述子セットを生成するで作成した記述子セットのパス。

Java

スキーマバンドルを作成するには、createSchemaBundle メソッドを使用します。

Bigtable 用のクライアントライブラリをインストールして使用する方法については、Bigtable クライアントライブラリをご覧ください。

Bigtable で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証を設定するをご覧ください。

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());
}

スキーマバンドルに関する情報を表示する

スキーマバンドルに関する情報を表示するには、少なくとも 1 つのスキーマバンドルを含む Bigtable テーブルが必要です。テーブル内のスキーマバンドルに関する情報を取得するには、単一のスキーマバンドルの定義を取得するか、テーブル内のすべてのスキーマバンドルを一覧表示します。

スキーマバンドル定義を取得する

コンソール

Google Cloud コンソールで、Bigtable インスタンスのリストを開きます。

インスタンスのリストを開く
リストからインスタンスを選択します。
ナビゲーションパネルで [Bigtable Studio] をクリックします。
[エクスプローラ] ペインで、スキーマバンドルを含むテーブルを開き、[スキーマバンドル] を開きます。
表示するスキーマバンドルをクリックするか、スキーマバンドルの横にある more_vert 操作メニューをクリックして、[詳細を表示] をクリックします。

スキーマバンドル定義が表示されたタブが開きます。
（省略可）スキーマバンドルを使用するサンプルクエリを含む SQL クエリエディタタブを開くには、スキーマバンドルの横にある more_vert 操作メニューをクリックし、[サンプルクエリ] をクリックします。

gcloud

スキーマバンドルの詳細を取得するには、gcloud bigtable schema-bundles describe コマンドを使用します。

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

次のように置き換えます。

SCHEMA_BUNDLE_ID: スキーマバンドルの ID。
INSTANCE_ID: インスタンスの ID。
TABLE_ID: テーブルの ID。

Java

スキーマバンドルの定義を取得するには、getSchemaBundle メソッドを使用します。このメソッドは、スキーマ定義を含む SchemaBundle オブジェクトを返します。

次の例は、スキーマバンドルを取得し、記述子セットを逆シリアル化してスキーマの内容を出力する方法を示しています。

Bigtable 用のクライアントライブラリをインストールして使用する方法については、Bigtable クライアントライブラリをご覧ください。

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());
}

出力は次のようになります。

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

スキーマバンドルをテーブルで一覧表示する

コンソール

Google Cloud コンソールで、Bigtable インスタンスのリストを開きます。

インスタンスのリストを開く
リストからインスタンスを選択します。
ナビゲーションパネルで [Bigtable Studio] をクリックします。
[エクスプローラ] ペインで、表示するスキーマバンドルを含むテーブルを開きます。
[スキーマバンドル] を開きます。

テーブルにスキーマバンドルのリストが表示されます。テーブルにスキーマバンドルがない場合、[スキーマバンドル] リストは表示されません。

gcloud

テーブルのスキーマバンドルのリストを表示するには、gcloud bigtable schema-bundles list コマンドを使用します。

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

次のように置き換えます。

INSTANCE_ID: インスタンスの ID。
TABLE_ID: テーブルの ID。

Java

テーブル内のすべてのスキーマバンドルのリストを表示するには、listSchemaBundles メソッドを使用します。このメソッドは、スキーマバンドル ID のリストを返します。

次の例は、スキーマバンドルをテーブルに一覧表示する方法を示しています。

Bigtable 用のクライアントライブラリをインストールして使用する方法については、Bigtable クライアントライブラリをご覧ください。

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());
}

出力は次のようになります。

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

スキーマバンドルを更新する

スキーマバンドルを更新すると、Bigtable は新しい記述子セットが既存の記述子セットと下位互換性があるかどうかを確認します。Bigtable が非互換性を検出すると、更新は失敗し、FailedPrecondition エラーが返されます。削除したフィールド番号は、再利用を防ぐために予約することをおすすめします。詳細については、protobuf ドキュメントの Proto のベストプラクティスをご覧ください。

互換性のない変更が安全であることを確認し、更新を強制的に行う場合は、gcloud CLI で --ignore-warnings フラグを使用できます。ただし、スキーマバンドルが継続的マテリアライズドビューまたは論理ビューで使用されている場合は、互換性のない変更を強制することはできません。ビューは、スキーマバンドルのメッセージ定義に依存してデータを解析し、クエリを実行するため、互換性のない変更を行うと、論理ビューに対するクエリが中断され、継続的マテリアライズドビューがデータ処理中に失敗します。ビューで参照されているスキーマバンドルに下位互換性のない変更を加えるには、まず参照ビューを更新または削除する必要があります。

コンソール

Google Cloud コンソールで、Bigtable インスタンスのリストを開きます。

インスタンスのリストを開く
リストからインスタンスを選択します。
ナビゲーションパネルで [Bigtable Studio] をクリックします。
[エクスプローラ] ペインで、スキーマバンドルを含むテーブルを開き、[スキーマバンドル] を開きます。
更新するスキーマバンドルの横にある more_vert 操作メニューをクリックし、[更新] をクリックします。
[スキーマバンドルを更新] ダイアログの [ファイル記述子セット（.pb ファイル）] フィールドで、新しい protobuf ファイル記述子セットを選択します。ファイルサイズは 4 MB 以下にしてください。
[保存] をクリックします。

gcloud

別の記述子セットを使用するようにスキーマバンドルを更新するには、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

次のように置き換えます。

SCHEMA_BUNDLE_ID: 更新するスキーマバンドルの ID。
INSTANCE_ID: スキーマバンドルを含むインスタンスの ID。
TABLE_ID: スキーマバンドルを含むテーブルの ID。
PROTO_DESCRIPTORS_FILE: 新しい記述子セットファイルのパス。

（省略可）互換性のない変更がある場合でも更新を強制するには、コマンドに --ignore-warnings フラグを追加します。スキーマバンドルが継続的マテリアライズドビューまたは論理ビューで使用されている場合、互換性のない変更を強制することはできません。

Java

Bigtable 用のクライアントライブラリをインストールして使用する方法については、Bigtable クライアントライブラリをご覧ください。

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());
}

スキーマバンドルを削除する

継続的マテリアライズドビューまたは論理ビューで使用されているスキーマバンドルは削除できません。バンドルを削除すると、論理ビューに対するクエリが失敗し、継続的マテリアライズドビューが受信データを処理できなくなります。スキーマバンドルを削除するには、まずスキーマバンドルを参照しているビューを削除するか、参照を削除するようにビューを更新する必要があります。

コンソール

Google Cloud コンソールで、Bigtable インスタンスのリストを開きます。

インスタンスのリストを開く
リストからインスタンスを選択します。
ナビゲーションパネルで [Bigtable Studio] をクリックします。
[エクスプローラ] ペインで、スキーマバンドルを含むテーブルを開き、[スキーマバンドル] を開きます。
削除するスキーマバンドルの横にある more_vert 操作メニューをクリックし、[削除] をクリックします。
確認ダイアログで [削除] をクリックします。

gcloud

スキーマバンドルを削除するには、gcloud bigtable schema-bundles delete コマンドを使用します。

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

次のように置き換えます。

SCHEMA_BUNDLE_ID: 削除するスキーマバンドルの ID。
INSTANCE_ID: スキーマバンドルを含むインスタンスの ID。
TABLE_ID: スキーマバンドルを含むテーブルの ID。

Java

Bigtable 用のクライアントライブラリをインストールして使用する方法については、Bigtable クライアントライブラリをご覧ください。

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());
}

制限事項

スキーマバンドルには次の制限があります。

テーブルごとに作成できるスキーマバンドルは最大 10 個です。
スキーマバンドル内のシリアル化されたプロトコルバッファ記述子の合計サイズは 4 MB を超えることはできません。バンドルに含めることができる個々のスキーマの数に直接的な上限はありません。ただし、バンドルの合計サイズがこの上限を超えないようにする必要があります。

protobuf スキーマを作成して管理する

始める前に

必要なロール

必要な権限

protobuf ファイル記述子セットを生成する

スキーマ バンドルを作成する

コンソール

gcloud

Java

スキーマ バンドルに関する情報を表示する

スキーマ バンドル定義を取得する

コンソール

gcloud

Java

スキーマ バンドルをテーブルで一覧表示する

コンソール

gcloud

Java

スキーマ バンドルを更新する

コンソール

gcloud

Java

スキーマ バンドルを削除する

コンソール

gcloud

Java

制限事項

次のステップ

スキーマバンドルを作成する

スキーマバンドルに関する情報を表示する

スキーマバンドル定義を取得する

スキーマバンドルをテーブルで一覧表示する

スキーマバンドルを更新する

スキーマバンドルを削除する