Protobuf-Schemas erstellen und verwalten

In diesem Dokument wird beschrieben, wie Sie Schemapakete erstellen und Vorgänge dafür ausführen.

In Bigtable können Sie Protokollzwischenspeicher-Schemas (Protobuf) verwenden, um einzelne Felder in Protobuf-Nachrichten abzufragen, die als Byte in Ihren Spalten gespeichert sind. Dazu laden Sie Ihre Schemas in ein Schema-Bundle hoch, eine Ressource auf Tabellenebene, die ein oder mehrere Protobuf-Schemas enthält.

Die Verwendung von Schemapaketen bietet die folgenden Vorteile:

  • Spart Zeit und Aufwand: Mit Protokollzwischenspeichern 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 Proto-Datei als zentrale Informationsquelle 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.

Die Verwendung von Schemas in Bigtable beginnt mit Ihren Proto-Dateien. Eine Proto-Datei ist eine Textdatei, in der Sie die Struktur Ihrer Daten definieren. Sie verwenden das Protobuf-Compiler-Tool, auch als protoc bezeichnet, um einen Protobuf-Dateideskriptorsatz zu generieren. Dies ist ein maschinenlesbares Schema Ihrer Proto-Datei. Mit diesem Deskriptorsatz erstellen Sie dann ein Schemabundle.

Beispiele für Proto-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 Schemapakete mit der Google Cloud -Console oder der Google Cloud CLI erstellen. Nachdem Sie ein Schemapaket in Bigtable hochgeladen haben, können Sie Ihre Daten mit dem Bigtable Studio-Abfrage-Builder, 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:

  1. Installieren Sie die gcloud CLI.
  2. Initialisieren Sie die gcloud CLI:

    gcloud init
    

Erforderliche Rollen

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

Diese vordefinierte Rolle enthält die Berechtigungen, die Bigtable für die Arbeit mit Schemapaketen 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.

Protobuf-Dateideskriptorsatz generieren

Bevor Sie ein Schemabundle erstellen können, müssen Sie mit dem protobuf-Compiler-Tool einen Deskriptorsatz aus Ihren proto-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 den generierten Deskriptorsatz 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

Schema-Bundle erstellen

Console

  1. Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.

    Liste der Instanzen öffnen

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Bigtable Studio.

  4. Klicken Sie im Bereich Explorer neben der Tabelle, in der Sie ein Schemapaket erstellen möchten, auf  Aktionen anzeigen und dann auf Schemapaket erstellen.

  5. Klicken Sie im Dialogfeld Schemabündel erstellen im Feld Schemadatei (.pb, .avsc oder .json) auf Durchsuchen und wählen Sie dann den Protobuf-Dateideskriptorsatz (.pb-Datei) aus, den Sie im Abschnitt Protobuf-Dateideskriptorsatz generieren dieses Dokuments erstellt haben. Die Datei darf nicht größer als 4 MB sein.

  6. Behalten Sie im Feld Schema Bundle ID (Schema-Bundle-ID) die ID bei, die automatisch aus dem Dateinamen eingefügt wird, oder geben Sie eine eindeutige Kennung für das Schema-Bundle ein.

    Die ID muss 1 bis 50 Zeichen lang sein, darf nur Buchstaben, Ziffern, Unterstriche und Bindestriche enthalten, darf nicht mit einem Bindestrich beginnen und darf keinen Punkt (.) enthalten.

  7. Klicken Sie auf Erstellen.

    Das Schema-Bundle wird in einem neuen Tab geöffnet.

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles create, um ein Schema-Bundle 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 Schemapaket, die keine Punkte („.“) enthalten darf.
  • INSTANCE_ID: die ID der Instanz, in der Sie das Schemapaket erstellen.
  • TABLE_ID: die ID der Tabelle, in der Sie das Schemapaket erstellen.
  • PROTO_DESCRIPTORS_FILE: Der Pfad zum Deskriptorsatz, den Sie im Abschnitt Protobuf-Dateideskriptorsatz generieren dieses Dokuments erstellt haben.

Java

Verwenden Sie zum Erstellen eines Schemapakets 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)) {
  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());
}

Informationen zu Schemapaketen ansehen

Bevor Sie Informationen zu Schemapaketen aufrufen können, benötigen Sie eine Bigtable-Tabelle mit mindestens einem Schemapaket. Sie können Informationen zu Schema-Bundles in einer Tabelle abrufen, indem Sie die Definition eines einzelnen Schema-Bundles abrufen oder alle Schema-Bundles in einer Tabelle auflisten.

Schema-Bundle-Definition abrufen

Console

  1. Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.

    Liste der Instanzen öffnen

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Bigtable Studio.

  4. Maximieren Sie im Bereich Explorer die Tabelle, die das Schemapaket enthält, und maximieren Sie dann Schemapakete.

  5. Klicken Sie auf das Schema-Bundle, das Sie ansehen möchten, oder klicken Sie neben dem Schema-Bundle auf  Aktionen ansehen und dann auf Details ansehen.

    Es wird ein Tab mit den Details des Schemapakets und der Schemadefinition geöffnet.

  6. Optional: Wenn Sie einen Tab im Abfrageeditor öffnen möchten, der bereits mit einer SQL-Beispielabfrage gefüllt ist, die das Schemapaket verwendet, klicken Sie neben dem Schemapaket auf  Aktionen ansehen und dann auf Beispielabfrage.

gcloud

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

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

Ersetzen Sie Folgendes:

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

Java

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

Im folgenden Beispiel wird gezeigt, 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(
          "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());
}

Die Ausgabe sieht etwa so aus:

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

Schema-Bundles in einer Tabelle auflisten

Console

  1. Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.

    Liste der Instanzen öffnen

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Bigtable Studio.

  4. Maximieren Sie im Bereich Explorer die Tabelle, die die Schemabündel enthält, die Sie ansehen möchten.

  5. Maximieren Sie Schema-Bundles.

    Die Liste der Schemapakete in der Tabelle wird angezeigt. Wenn die Tabelle keine Schema-Bundles enthält, wird Schema-Bundles nicht angezeigt.

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles list, um eine Liste der Schemapakete 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 Schemapakete in einer Tabelle aufzurufen. Diese Methode gibt eine Liste von Schemapaket-IDs zurück.

Im folgenden Beispiel wird gezeigt, wie die Schemapakete in einer Tabelle aufgelistet werden:

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

Die Ausgabe sieht etwa so aus:

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

Schema-Bundle aktualisieren

Wenn Sie ein Schema-Bundle aktualisieren, prüft Bigtable, ob der neue Deskriptorsatz mit dem vorhandenen abwärtskompatibel ist. Wenn Bigtable eine Inkompatibilität erkennt, schlägt die Aktualisierung mit dem Fehler FailedPrecondition 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 ein Update erzwingen möchten, können Sie das Flag --ignore-warnings mit der gcloud CLI verwenden. Sie können jedoch keine inkompatiblen Änderungen erzwingen, wenn das Schema-Bundle von einer kontinuierlichen materialisierten Ansicht oder einer logischen Ansicht verwendet wird. Ansichten sind von den Nachrichtendefinitionen des Schemabundles abhängig, um Daten zu parsen und abzufragen. Inkompatible Änderungen würden daher Abfragen für logische Ansichten beeinträchtigen und dazu führen, dass kontinuierliche materialisierte Ansichten während der Datenverarbeitung fehlschlagen. Wenn Sie abwärtskompatible Änderungen an einem Schemabundle vornehmen möchten, auf das von einer Ansicht verwiesen wird, müssen Sie zuerst die verweisenden Ansichten aktualisieren oder löschen.

Console

  1. Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.

    Liste der Instanzen öffnen

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Bigtable Studio.

  4. Maximieren Sie im Bereich Explorer die Tabelle, die das Schemapaket enthält, und maximieren Sie dann Schemapakete.

  5. Klicken Sie neben dem Schema-Bundle, das Sie aktualisieren möchten, auf  Aktionen ansehen und dann auf Aktualisieren.

  6. Klicken Sie im Dialogfeld Schemapaket aktualisieren im Feld Schemadatei (.pb, .avsc oder .json) auf Durchsuchen und wählen Sie dann den neuen Protobuf-Dateideskriptorsatz (.pb-Datei) aus. Die Datei darf nicht größer als 4 MB sein.

  7. Klicken Sie auf Speichern.

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles update, um ein Schemapaket so zu aktualisieren, dass es einen anderen Deskriptorsatz verwendet:

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 Schemapakets.
  • INSTANCE_ID: die ID der Instanz, die das Schemapaket enthält.
  • TABLE_ID: die ID der Tabelle, die das Schema-Bundle enthält.
  • PROTO_DESCRIPTORS_FILE: der Pfad zur neuen Deskriptorsatzdatei.

Optional: Wenn Sie die Aktualisierung auch bei inkompatiblen Änderungen erzwingen möchten, hängen Sie das Flag --ignore-warnings an den Befehl an. Sie können keine inkompatiblen Änderungen erzwingen, wenn das Schema-Bundle von einer kontinuierlichen materialisierten Ansicht oder einer logischen Ansicht verwendet wird.

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

Schema-Bundle löschen

Sie können ein Schema-Bundle nicht löschen, wenn es von einer kontinuierlichen materialisierten Ansicht oder einer logischen Ansicht verwendet wird. Wenn Sie das Bundle löschen, schlagen Abfragen für logische Ansichten fehl und kontinuierliche materialisierte Ansichten können keine eingehenden Daten mehr verarbeiten. Wenn Sie das Schema-Bundle löschen möchten, müssen Sie zuerst alle Ansichten löschen, die darauf verweisen, oder sie aktualisieren, um den Verweis zu entfernen.

Console

  1. Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.

    Liste der Instanzen öffnen

  2. Wählen Sie eine Instanz aus der Liste aus.

  3. Klicken Sie im Navigationsmenü auf Bigtable Studio.

  4. Maximieren Sie im Bereich Explorer die Tabelle, die das Schemapaket enthält, und maximieren Sie dann Schemapakete.

  5. Klicken Sie neben dem Schemapaket, das Sie löschen möchten, auf  Aktionen ansehen und dann auf Löschen.

  6. Klicken Sie im Bestätigungsdialogfeld auf Löschen.

gcloud

Verwenden Sie den Befehl gcloud bigtable schema-bundles delete, um ein Schema-Bundle 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 Schemabundles.
  • INSTANCE_ID: die ID der Instanz, die das Schemapaket enthält.
  • TABLE_ID: die ID der Tabelle, die das Schema-Bundle 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(
      "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());
}

Beschränkungen

Für Schema-Bundles gelten die folgenden Einschränkungen:

  • Sie können bis zu 10 Schema-Bundles pro Tabelle erstellen. Dieses Limit gilt sowohl für Protobuf- als auch für Avro-Schemabundles.
  • Die Gesamtgröße der serialisierten Protokollzwischenspeicher-Deskriptoren in einem Schemabundle darf 4 MB nicht überschreiten. Es gibt keine direkte Beschränkung 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