Protobuf-Schemas erstellen und verwalten

In diesem Dokument wird beschrieben, wie Sie Schemabündel erstellen und Vorgänge für sie ausführen.

In Bigtable können Sie Protobuf-Schemas verwenden, um einzelne Felder in Protobuf-Nachrichten abzufragen, die als Byte in Ihren Spalten gespeichert sind. Dazu laden Sie Ihre Schemas in einem Schemabundle hoch. Das ist eine Ressource auf Tabellenebene, die mindestens eines Ihrer Protobuf-Schemas enthält.

Die Verwendung von Schemabündeln bietet folgende Vorteile:

  • Spart Zeit und Aufwand: Mit Protocol Buffers definieren Sie Ihre Datenstruktur einmal in einer Proto-Datei und verwenden dann den generierten Quellcode, um Ihre Daten zu schreiben und zu lesen.
  • Verbessert die Datenkonsistenz: Wenn Sie eine Protodatei als einzige Quelle der Wahrheit verwenden, können Sie dafür sorgen, dass alle Anwendungen und Dienste dasselbe Datenmodell verwenden.
  • Eliminiert Datenduplizierung: Sie können Protokollpuffer projektübergreifend verwenden, indem Sie Nachrichtentypen in Proto-Dateien definieren, die sich außerhalb der Codebasis eines bestimmten Projekts befinden.

Die Verwendung von Schemas in Bigtable beginnt mit Ihren Protobuf-Dateien. Eine Proto-Datei ist eine Textdatei, in der Sie die Struktur Ihrer Daten definieren. Mit dem Protobuf-Compiler-Tool, auch protoc genannt, generieren Sie einen Protobuf-Dateideskriptorsatz, ein maschinenlesbares Schema Ihrer Protobuf-Datei. Mit diesem Deskriptorsatz erstellen Sie dann ein Schemabündel.

Beispiele für Protobuf-Dateien und die entsprechenden Deskriptorsätze finden Sie unter Beispieldaten.

Das folgende Diagramm zeigt den Prozess der Verwendung von Schemas in Bigtable:

Der Prozess der Verwendung von Protobuf-Schemas in Bigtable.
Abbildung 1. Prozess zur Verwendung von Protobuf-Schemas in Bigtable (zum Vergrößern klicken).

Sie können Schemabündel mit der Google Cloud CLI erstellen. Nachdem Sie ein Schemabundle in Bigtable hochgeladen haben, können Sie Ihre Daten mit dem Bigtable Studio-Abfragegenerator, GoogleSQL für Bigtable oder externen Bigtable-Tabellen in BigQuery abfragen.

Hinweise

Wenn Sie die gcloud CLI verwenden möchten, führen Sie die folgenden Schritte aus:

  1. Installieren Sie die Google Cloud CLI.

  2. Initialisieren Sie die gcloud CLI:

    gcloud init

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die IAM-Rolle Bigtable Admin (roles/bigtable.admin) für die Tabelle zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Erstellen und Verwalten von Schemabündeln benötigen.

Diese vordefinierte Rolle enthält die Berechtigungen, die Bigtable für die Arbeit mit Schemabündeln benötigt. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die genau erforderlichen Berechtigungen aufzurufen:

Erforderliche Berechtigungen

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

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Weitere Informationen zu Bigtable-Rollen und -Berechtigungen finden Sie unter Zugriffssteuerung mit IAM.

Satz von Protobuf-Dateideskriptoren generieren

Bevor Sie ein Schemabundle erstellen können, müssen Sie mit dem Protobuf-Compiler-Tool einen Deskriptorsatz aus Ihren Protobuf-Dateien generieren.

  1. Laden Sie das Paket herunter und folgen Sie der Anleitung in der README-Datei, um den Compiler zu installieren.

  2. Führen Sie den Compiler aus:

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

    Ersetzen Sie Folgendes:

    • IMPORT_PATH: das Verzeichnis, in dem der protoc-Compiler nach Proto-Dateien sucht.
    • DESCRIPTOR_OUTPUT_LOCATION: Das Verzeichnis, in dem der protoc-Compiler das generierte Deskriptorset speichert.
    • PATH_TO_PROTO: der Pfad zu Ihrer Proto-Datei.

Wenn Sie beispielsweise einen Deskriptorsatz mit dem Namen library.pb für die Datei library.proto im aktuellen Verzeichnis erstellen möchten, können Sie den folgenden Befehl verwenden:

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

Schemabündel erstellen

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles create, um ein Schemabündel zu erstellen:

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

Ersetzen Sie Folgendes:

  • SCHEMA_BUNDLE_ID: Eine eindeutige ID für das neue Schemabundle, die keinen Punkt („.“) enthalten darf.
  • INSTANCE_ID: die ID der Instanz, in der das Schemabündel erstellt werden soll.
  • TABLE_ID: Die ID der Tabelle, in der das Schemabündel erstellt werden soll.
  • PROTO_DESCRIPTORS_FILE: der Pfad zum Deskriptorsatz, der im vorherigen Schritt generiert wurde.

Java

Verwenden Sie zum Erstellen eines Schemabundles die Methode createSchemaBundle:

Informationen zum Installieren und Verwenden der Clientbibliothek für Bigtable finden Sie unter Bigtable-Clientbibliotheken.

Richten Sie zur Authentifizierung bei Bigtable die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Informationen zu Schemabündeln ansehen

Bevor Sie Informationen zu Schemabundles aufrufen können, benötigen Sie eine Bigtable-Tabelle mit mindestens einem Schemabundle. Sie können Informationen zu Schemabündeln in einer Tabelle abrufen, indem Sie die Definition eines einzelnen Schemabündels abrufen oder alle Schemabündel in einer Tabelle auflisten.

Schemabundle-Definition abrufen

gcloud

Mit dem Befehl gcloud bigtable schema-bundles describe können Sie Details zu einem Schemabündel abrufen:

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

Ersetzen Sie Folgendes:

  • SCHEMA_BUNDLE_ID: Die ID des Schemabundles.
  • INSTANCE_ID: die ID der Instanz.
  • TABLE_ID: Die ID der Tabelle.

Java

Verwenden Sie die Methode getSchemaBundle, um die Definition eines Schemabundles abzurufen. Diese Methode gibt ein SchemaBundle-Objekt zurück, das die Schemadefinition enthält.

Das folgende Beispiel zeigt, wie Sie ein Schemabundle abrufen und den Deskriptorsatz deserialisieren, um den Inhalt des Schemas auszugeben:

Informationen zum Installieren und Verwenden der Clientbibliothek für Bigtable finden Sie unter Bigtable-Clientbibliotheken.

Richten Sie zur Authentifizierung bei Bigtable die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Die Ausgabe sieht etwa so aus:

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

Schema-Bundles in einer Tabelle auflisten

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles list, um eine Liste der Schemabündel für eine Tabelle aufzurufen:

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

Ersetzen Sie Folgendes:

  • INSTANCE_ID: die ID der Instanz.
  • TABLE_ID: Die ID der Tabelle.

Java

Wenn Sie eine Liste aller Schemabündel in einer Tabelle aufrufen möchten, verwenden Sie die Methode listSchemaBundles. Diese Methode gibt eine Liste von Schema-Bundle-IDs zurück.

Das folgende Beispiel zeigt, wie Sie die Schemabündel in einer Tabelle auflisten:

Informationen zum Installieren und Verwenden der Clientbibliothek für Bigtable finden Sie unter Bigtable-Clientbibliotheken.

Richten Sie zur Authentifizierung bei Bigtable die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Die Ausgabe sieht etwa so aus:

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

Schemabundle aktualisieren

Wenn Sie ein Schemabündel aktualisieren, prüft Bigtable, ob der neue Deskriptorsatz abwärtskompatibel mit dem vorhandenen ist. Wenn sie nicht kompatibel ist, schlägt die Aktualisierung mit dem Fehler FailedPrecondition fehl. Wir empfehlen, gelöschte Feldnummern zu reservieren, um eine Wiederverwendung zu verhindern. Weitere Informationen finden Sie in der Protobuf-Dokumentation unter Proto Best Practices.

Wenn Sie sicher sind, dass die inkompatiblen Änderungen sicher sind und ein Update erzwingen möchten, können Sie das Flag --ignore-warnings mit der gcloud CLI verwenden.

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles update, um ein Schemabundle für die Verwendung eines anderen Deskriptorsatzes zu aktualisieren:

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

Ersetzen Sie Folgendes:

  • SCHEMA_BUNDLE_ID: Die ID des zu aktualisierenden Schemabundles.
  • INSTANCE_ID: die ID der Instanz, die das Schemabündel enthält.
  • TABLE_ID: die ID der Tabelle, die das Schemabundle enthält.
  • PROTO_DESCRIPTORS_FILE: der Pfad zur neuen Deskriptorsatzdatei.

Optional: Wenn Sie das Update auch bei inkompatiblen Änderungen erzwingen möchten, hängen Sie das Flag --ignore-warnings an den Befehl an.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für Bigtable finden Sie unter Bigtable-Clientbibliotheken.

Richten Sie zur Authentifizierung bei Bigtable die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Schema-Bundle löschen

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles delete, um ein Schemabündel zu löschen:

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

Ersetzen Sie Folgendes:

  • SCHEMA_BUNDLE_ID: Die ID des zu löschenden Schemabündels.
  • INSTANCE_ID: die ID der Instanz, die das Schemabündel enthält.
  • TABLE_ID: die ID der Tabelle, die das Schemabundle enthält.

Java

Informationen zum Installieren und Verwenden der Clientbibliothek für Bigtable finden Sie unter Bigtable-Clientbibliotheken.

Richten Sie zur Authentifizierung bei Bigtable die Standardanmeldedaten für Anwendungen ein. Weitere Informationen finden Sie unter Authentifizierung für eine lokale Entwicklungsumgebung einrichten. 

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

Beschränkungen

Für Schemabündel gelten die folgenden Einschränkungen:

  • Sie können maximal 10 Schemabündel pro Tabelle erstellen.
  • Die Gesamtgröße der serialisierten Protocol Buffer-Deskriptoren in einem Schemabundle darf 4 MB nicht überschreiten. Es gibt kein direktes Limit für die Anzahl der einzelnen Schemas, die Sie in ein Bundle aufnehmen können, solange die Gesamtgröße des Bundles dieses Limit nicht überschreitet.

Nächste Schritte