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:
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:
- Installieren Sie die gcloud CLI.
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.createbigtable.schemaBundles.updatebigtable.schemaBundles.deletebigtable.schemaBundles.getbigtable.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.
- Laden Sie das Paket herunter und folgen Sie der Anleitung in der README-Datei, um den Compiler zu installieren.
Führen Sie den Compiler aus:
protoc --proto_path=IMPORT_PATH --include_imports \ --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTOErsetzen 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
Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.
Wählen Sie eine Instanz aus der Liste aus.
Klicken Sie im Navigationsmenü auf Bigtable Studio.
Klicken Sie im Bereich Explorer neben der Tabelle, in der Sie ein Schemapaket erstellen möchten, auf Aktionen anzeigen und dann auf Schemapaket erstellen.
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.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.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.
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
Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.
Wählen Sie eine Instanz aus der Liste aus.
Klicken Sie im Navigationsmenü auf Bigtable Studio.
Maximieren Sie im Bereich Explorer die Tabelle, die das Schemapaket enthält, und maximieren Sie dann Schemapakete.
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.
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.
Die Ausgabe sieht etwa so aus:
--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------
Schema-Bundles in einer Tabelle auflisten
Console
Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.
Wählen Sie eine Instanz aus der Liste aus.
Klicken Sie im Navigationsmenü auf Bigtable Studio.
Maximieren Sie im Bereich Explorer die Tabelle, die die Schemabündel enthält, die Sie ansehen möchten.
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.
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
Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.
Wählen Sie eine Instanz aus der Liste aus.
Klicken Sie im Navigationsmenü auf Bigtable Studio.
Maximieren Sie im Bereich Explorer die Tabelle, die das Schemapaket enthält, und maximieren Sie dann Schemapakete.
Klicken Sie neben dem Schema-Bundle, das Sie aktualisieren möchten, auf Aktionen ansehen und dann auf Aktualisieren.
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.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.
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
Öffnen Sie in der Google Cloud Console die Liste der Bigtable-Instanzen.
Wählen Sie eine Instanz aus der Liste aus.
Klicken Sie im Navigationsmenü auf Bigtable Studio.
Maximieren Sie im Bereich Explorer die Tabelle, die das Schemapaket enthält, und maximieren Sie dann Schemapakete.
Klicken Sie neben dem Schemapaket, das Sie löschen möchten, auf Aktionen ansehen und dann auf Löschen.
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.
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
- Protobuf-Daten abfragen
- Avro-Schemas erstellen und verwalten
- Informationen zu wechselnden oder unsicheren Abfragen
- Weitere Informationen finden Sie unter GoogleSQL für Bigtable – Übersicht.