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 Protokollpuffer (protobuf) Schemas verwenden, um einzelne Felder in protobuf-Nachrichten abzufragen, die als Byte in Ihren Spalten gespeichert sind. Dazu laden Sie Ihre Schemas in ein Schemabündel hoch. Das ist eine Ressource auf Tabellenebene, die ein oder mehrere Ihrer protobuf-Schemas enthält.

Die Verwendung von Schemabündeln bietet folgende Vorteile:

Spart Zeit und Aufwand: Mit Protokollpuffern definieren Sie Ihre Daten struktur 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 Proto-Datei als einzige Quelle der Wahrheit verwenden, können Sie sicherstellen, 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.

Der Prozess der Verwendung von Schemas in Bigtable beginnt mit Ihren Proto-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 Satz von protobuf-Dateideskriptoren, ein maschinenlesbares Schema Ihrer Proto-Datei. Anschließend verwenden Sie diesen Satz von Deskriptoren, um ein Schemabündel zu erstellen.

Beispiele für Proto-Dateien und die entsprechenden Sätze von Deskriptoren 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.** Der Prozess der Verwendung von protobuf-Schemas in Bigtable (zum Vergrößern klicken).

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

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

Hinweis

Führen Sie die folgenden Schritte aus, wenn Sie die gcloud CLI verwenden möchten:

Installieren Sie die Google Cloud CLI.
Initialisieren Sie die gcloud CLI:
```
gcloud init
```

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen für die Tabelle die IAM-Rolle Bigtable Admin (roles/bigtable.admin) zuzuweisen, damit Sie die Berechtigungen 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 Schemabündel erstellen können, müssen Sie mit dem protobuf-Compiler-Tool einen Satz von Deskriptoren aus Ihren Proto-Dateien generieren.

Laden Sie das Paket herunter, um den Compiler zu installieren, und folgen Sie der Anleitung in der README-Datei.
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 den generierten Satz von Deskriptoren speichert.
- PATH_TO_PROTO: der Pfad zu Ihrer Proto-Datei.

Wenn Sie beispielsweise einen Satz von Deskriptoren 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 gcloud bigtable schema-bundles create Befehl, 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 Schemabündel, 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 Satz von Deskriptoren, der im vorherigen Schritt generiert wurde.

Java

Verwenden Sie die Methode createSchemaBundle, um ein Schemabündel zu erstellen:

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

Richten Sie Standardanmeldedaten für Anwendungen ein, um sich bei Bigtable zu authentifizieren. 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 Schemabündeln ansehen können, benötigen Sie eine Bigtable-Tabelle mit mindestens einem Schemabündel. 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.

Definition des Schemabündels abrufen

gcloud

Verwenden Sie den gcloud bigtable schema-bundles describe Befehl, um Details zu einem Schemabündel abzurufen:

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

Ersetzen Sie Folgendes:

SCHEMA_BUNDLE_ID: die ID des Schemabündels.
INSTANCE_ID: die ID der Instanz.
TABLE_ID: die ID der Tabelle.

Java

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

Das folgende Beispiel zeigt, wie Sie ein Schemabündel abrufen und den Satz von Deskriptoren deserialisieren, um den Inhalt des Schemas auszugeben:

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

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

Schemabündel in einer Tabelle auflisten

gcloud

Verwenden Sie den gcloud bigtable schema-bundles list Befehl, 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

Verwenden Sie die Methode listSchemaBundles, um eine Liste aller Schemabündel in einer Tabelle aufzurufen. Diese Methode gibt eine Liste von Schemabündel-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.

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

Schemabündel aktualisieren

Wenn Sie ein Schemabündel aktualisieren, prüft Bigtable, ob der neue Satz von Deskriptoren abwärtskompatibel mit dem vorhandenen ist. Wenn er nicht kompatibel ist, schlägt die Aktualisierung mit einem FailedPrecondition-Fehler fehl. Wir empfehlen, gelöschte Feldnummern zu reservieren, um ihre 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 eine Aktualisierung erzwingen möchten, können Sie das Flag --ignore-warnings mit der gcloud CLI verwenden.

gcloud

Verwenden Sie den gcloud bigtable schema-bundles update Befehl, um ein Schemabündel zu aktualisieren und einen anderen Satz von Deskriptoren zu verwenden:

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 Schemabündels.
INSTANCE_ID: die ID der Instanz, die das Schemabündel enthält.
TABLE_ID: die ID der Tabelle, die das Schemabündel enthält.
PROTO_DESCRIPTORS_FILE: der Pfad zur neuen Datei mit dem Satz von Deskriptoren.

Optional: Wenn Sie die Aktualisierung erzwingen möchten, auch wenn inkompatible Änderungen vorhanden sind, fügen Sie dem Befehl das Flag --ignore-warnings an. Wenn eine kontinuierliche materialisierte Ansicht oder eine logische Ansicht das Schemabündel verwendet, dürfen Sie keine inkompatiblen Änderungen erzwingen.

Java

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

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

Schemabündel löschen

gcloud

Verwenden Sie den gcloud bigtable schema-bundles delete Befehl, 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 Schemabündel enthält.

Wenn eine kontinuierliche materialisierte Ansicht oder eine logische Ansicht das Schemabündel verwendet, löschen Sie das Bündel nicht.

Java

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

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 Protokollpuffer-Deskriptoren in einem Schemabündel darf 4 MB nicht überschreiten. Es gibt keine direkte Beschränkung für die Anzahl der einzelnen Schemas, die Sie in ein Bündel aufnehmen können, solange die Gesamtgröße des Bündels diese Beschränkung nicht überschreitet.
Wenn eine kontinuierliche materialisierte Ansicht oder eine logische Ansicht das Schemabündel verwendet, dürfen Sie keine inkompatiblen Änderungen erzwingen oder das Bündel löschen.

Nächste Schritte

Informationen zum Abfragen von protobuf-Daten
Informationen zu wechselnden oder unsicheren Abfragen
Siehe GoogleSQL für Bigtable – Übersicht.