Crea e gestisci schemi Protobuf
Questo documento descrive come creare ed eseguire operazioni sui bundle di schemi.
In Bigtable, puoi utilizzare gli schemi dei buffer di protocollo (protobuf) per eseguire query su singoli campi all'interno dei messaggi protobuf archiviati come byte nelle colonne. Per farlo, carica gli schemi in un bundle di schemi, una risorsa a livello di tabella che contiene uno o più schemi Protobuf.
L'utilizzo dei bundle di schemi offre i seguenti vantaggi:
- Risparmio di tempo e fatica: con i buffer di protocollo, definisci la struttura dei dati una sola volta in un file proto, quindi utilizzi il codice sorgente generato per scrivere e leggere i dati.
- Migliora la coerenza dei dati: utilizzando un file proto come unica fonte di verità, puoi assicurarti che tutte le applicazioni e i servizi utilizzino lo stesso modello dei dati.
- Elimina la duplicazione dei dati: puoi utilizzare i buffer di protocollo in più progetti definendo i tipi di messaggi nei file proto che si trovano al di fuori della codebase di un progetto specifico.
Il processo di utilizzo degli schemi in Bigtable inizia con i file proto. Un file proto è un file di testo in cui definisci la struttura dei tuoi dati. Utilizza lo strumento di compilazione protobuf, noto anche come protoc, per generare un set di descrittori del file protobuf, ovvero uno schema leggibile da macchina del file proto. Utilizza poi questo set di descrittori per creare un bundle di schemi.
Per esempi di file proto e dei relativi set di descrittori, consulta Dati di esempio.
Il seguente diagramma mostra il processo di utilizzo degli schemi in Bigtable:
Puoi creare bundle di schemi utilizzando la console Google Cloud o Google Cloud CLI. Dopo aver caricato un bundle di schemi in Bigtable, puoi eseguire query sui dati utilizzando il Query Builder di Bigtable Studio, GoogleSQL per Bigtable o le tabelle esterne di Bigtable in BigQuery.
Prima di iniziare
Se prevedi di utilizzare gcloud CLI, segui questi passaggi:
- Installa gcloud CLI.
Inizializza gcloud CLI:
gcloud init
Ruoli obbligatori
Per ottenere le autorizzazioni necessarie per creare e gestire i bundle di schemi, chiedi all'amministratore di concederti il ruolo IAM (Identity and Access Management) Bigtable Admin (roles/bigtable.admin) sulla tabella.
Questo ruolo predefinito contiene le autorizzazioni richieste da Bigtable per utilizzare i bundle di schemi. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
bigtable.schemaBundles.createbigtable.schemaBundles.updatebigtable.schemaBundles.deletebigtable.schemaBundles.getbigtable.schemaBundles.list
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Per saperne di più sui ruoli e sulle autorizzazioni di Bigtable, consulta Controllo degli accessi con IAM.
Genera un set di descrittori di file protobuf
Prima di poter creare un bundle di schemi, devi generare un set di descrittori dai file proto con lo strumento di compilazione protobuf.
- Per installare il compilatore, scarica il pacchetto e segui le istruzioni nel file README.
Esegui il compilatore:
protoc --proto_path=IMPORT_PATH --include_imports \ --descriptor_set_out=DESCRIPTOR_OUTPUT_LOCATION PATH_TO_PROTOSostituisci quanto segue:
IMPORT_PATH: la directory in cui il compilatore protoc cerca i file proto.DESCRIPTOR_OUTPUT_LOCATION: la directory in cui il compilatore protoc salva il set di descrittori generato.PATH_TO_PROTO: il percorso del file proto.
Ad esempio, per creare un set di descrittori denominato library.pb per il file library.proto nella directory corrente, puoi utilizzare il seguente comando:
protoc --include_imports --descriptor_set_out=library.pb
library.proto
Crea un bundle di schemi
Console
Nella console Google Cloud , apri l'elenco delle istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Nel riquadro Explorer, accanto alla tabella in cui vuoi creare un bundle di schemi, fai clic su Visualizza azioni, quindi su Crea bundle di schemi.
Nella finestra di dialogo Crea bundle di schemi, nel campo File di schema (.pb, .avsc o .json), fai clic su Sfoglia, quindi seleziona il set di descrittori del file protobuf (file
.pb) che hai creato nella sezione Genera un set di descrittori del file protobuf di questo documento. Le dimensioni del file non possono superare i 4 MB.Nel campo ID pacchetto schema, mantieni l'ID compilato automaticamente dal nome file o inserisci un identificatore univoco per il pacchetto schema.
L'ID deve avere una lunghezza compresa tra 1 e 50 caratteri, può contenere solo lettere, numeri, trattini bassi e trattini, non può iniziare con un trattino e non può contenere il carattere punto (
.).Fai clic su Crea.
Il bundle di schemi si apre in una nuova scheda.
gcloud
Per creare un bundle di schemi, utilizza il comando 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
Sostituisci quanto segue:
SCHEMA_BUNDLE_ID: un ID univoco per il nuovo bundle di schemi che non può contenere caratteri punto (".").INSTANCE_ID: l'ID dell'istanza in cui crei il bundle di schemi.TABLE_ID: l'ID della tabella in cui crei il bundle di schemi.PROTO_DESCRIPTORS_FILE: il percorso del set di descrittori del file che hai creato nella sezione Genera un set di descrittori di file protobuf di questo documento.
Java
Per creare un bundle di schemi, utilizza il metodo createSchemaBundle:
Per scoprire come installare e utilizzare la libreria client per Bigtable, consulta Librerie client di Bigtable.
Per eseguire l'autenticazione in Bigtable, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Visualizza informazioni sui bundle di schemi
Prima di poter visualizzare le informazioni sui bundle di schemi, devi avere una tabella Bigtable con almeno un bundle di schemi. Puoi ottenere informazioni sui bundle di schemi in una tabella recuperando la definizione di un singolo bundle di schemi o elencando tutti i bundle di schemi in una tabella.
Ottieni la definizione del bundle di schemi
Console
Nella console Google Cloud , apri l'elenco delle istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Nel riquadro Explorer, espandi la tabella che contiene il bundle di schemi, quindi espandi Bundle di schemi.
Fai clic sul bundle di schemi che vuoi visualizzare o, accanto al bundle di schemi, fai clic su Visualizza azioni, quindi su Visualizza dettagli.
Viene visualizzata una scheda con i dettagli del bundle di schemi e la definizione dello schema.
(Facoltativo) Per aprire una scheda dell'editor di query precompilata con una query SQL di esempio che utilizza il bundle di schemi, accanto al bundle di schemi, fai clic su Visualizza azioni, quindi su Query di esempio.
gcloud
Per visualizzare i dettagli di un bundle di schemi, utilizza il comando gcloud bigtable schema-bundles describe:
gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
--instance=INSTANCE_ID \
--table=TABLE_ID
Sostituisci quanto segue:
SCHEMA_BUNDLE_ID: l'ID del bundle di schemi.INSTANCE_ID: l'ID dell'istanza.TABLE_ID: l'ID della tabella.
Java
Per ottenere la definizione di un bundle di schemi, utilizza il metodo getSchemaBundle.
Questo metodo restituisce un oggetto SchemaBundle che contiene la definizione dello schema.
L'esempio seguente mostra come ottenere un bundle di schema e deserializzare il set di descrittori per stampare i contenuti dello schema:
Per scoprire come installare e utilizzare la libreria client per Bigtable, consulta Librerie client di Bigtable.
Per eseguire l'autenticazione in Bigtable, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
L'output è simile al seguente:
--------- Deserialized FileDescriptorSet ---------
File: my_schema.proto
Package: my_package
Message: MyMessage
--------------------------------------------------
Elenca i bundle di schemi in una tabella
Console
Nella console Google Cloud , apri l'elenco delle istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Nel riquadro Explorer, espandi la tabella contenente i bundle di schemi che vuoi visualizzare.
Espandi Bundle di schemi.
Viene visualizzato l'elenco dei bundle di schemi nella tabella. Se la tabella non contiene bundle di schemi, l'opzione Bundle di schemi non viene visualizzata.
gcloud
Per visualizzare un elenco di bundle di schemi per una tabella, utilizza il comando gcloud bigtable schema-bundles list:
gcloud bigtable schema-bundles list \
--instance=INSTANCE_ID \
--table=TABLE_ID
Sostituisci quanto segue:
INSTANCE_ID: l'ID dell'istanza.TABLE_ID: l'ID della tabella.
Java
Per visualizzare un elenco di tutti i bundle di schemi in una tabella, utilizza il metodo listSchemaBundles. Questo metodo restituisce un elenco di ID pacchetto di schemi.
L'esempio seguente mostra come elencare i bundle di schemi in una tabella:
Per scoprire come installare e utilizzare la libreria client per Bigtable, consulta Librerie client di Bigtable.
Per eseguire l'autenticazione in Bigtable, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
L'output è simile al seguente:
my-schema-bundle-1
my-schema-bundle-2
Aggiorna un bundle di schemi
Quando aggiorni un bundle di schemi, Bigtable verifica se il nuovo set di descrittori è compatibile con le versioni precedenti di quello esistente. Se Bigtable rileva un'incompatibilità, l'aggiornamento non va a buon fine e viene visualizzato un errore FailedPrecondition. Ti consigliamo di riservare i numeri dei campi eliminati per impedirne il riutilizzo. Per saperne di più, consulta le best practice per i proto nella documentazione di protobuf.
Se hai la certezza che le modifiche incompatibili siano sicure e vuoi forzare un aggiornamento, puoi utilizzare il flag --ignore-warnings con gcloud CLI.
Tuttavia, non puoi forzare modifiche incompatibili se il bundle di schemi è utilizzato da una vista materializzata continua o da una vista logica. Le viste dipendono dalle definizioni dei messaggi del bundle di schemi per analizzare ed eseguire query sui dati, pertanto le modifiche incompatibili interromperebbero le query sulle viste logiche e causerebbero l'errore delle viste materializzate continue durante il trattamento dati. Per apportare modifiche incompatibili con le versioni precedenti a un bundle di schemi a cui fa riferimento una vista, devi prima aggiornare o eliminare le viste di riferimento.
Console
Nella console Google Cloud , apri l'elenco delle istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Nel riquadro Explorer, espandi la tabella che contiene il bundle di schemi, quindi espandi Bundle di schemi.
Accanto al bundle di schemi che vuoi aggiornare, fai clic su Visualizza azioni, quindi su Aggiorna.
Nella finestra di dialogo Aggiorna bundle di schemi, nel campo File di schema (.pb, .avsc o .json), fai clic su Sfoglia, quindi seleziona il nuovo set di descrittori del file protobuf (file
.pb). Le dimensioni del file non possono superare i 4 MB.Fai clic su Salva.
gcloud
Per aggiornare un bundle di schemi in modo che utilizzi un set di descrittori diverso, utilizza il comando 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
Sostituisci quanto segue:
SCHEMA_BUNDLE_ID: l'ID del bundle di schema da aggiornare.INSTANCE_ID: l'ID dell'istanza che contiene il bundle di schemi.TABLE_ID: l'ID della tabella che contiene il bundle di schemi.PROTO_DESCRIPTORS_FILE: il percorso del nuovo file del set di descrittori.
(Facoltativo) Per forzare l'aggiornamento anche se sono presenti modifiche incompatibili, aggiungi
il flag --ignore-warnings al comando. Non puoi forzare modifiche incompatibili se il bundle di schemi è utilizzato da una vista materializzata continua o da una vista logica.
Java
Per scoprire come installare e utilizzare la libreria client per Bigtable, consulta Librerie client di Bigtable.
Per eseguire l'autenticazione in Bigtable, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Elimina un bundle di schemi
Non puoi eliminare un bundle di schemi se è utilizzato da una vista materializzata continua o da una vista logica. L'eliminazione del bundle causerebbe l'errore delle query sulle viste logiche e impedirebbe alle viste materializzate continue di elaborare i dati in arrivo. Per eliminare il bundle di schemi, devi prima eliminare tutte le visualizzazioni che vi fanno riferimento o aggiornarle per rimuovere il riferimento.
Console
Nella console Google Cloud , apri l'elenco delle istanze Bigtable.
Seleziona un'istanza dall'elenco.
Nel menu di navigazione, fai clic su Bigtable Studio.
Nel riquadro Explorer, espandi la tabella che contiene il bundle di schemi, quindi espandi Bundle di schemi.
Accanto al bundle di schemi che vuoi eliminare, fai clic su Visualizza azioni, quindi su Elimina.
Nella finestra di dialogo di conferma, fai clic su Elimina.
gcloud
Per eliminare un bundle di schemi, utilizza il comando gcloud bigtable schema-bundles delete:
gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
--instance=INSTANCE_ID \
--table=TABLE_ID
Sostituisci quanto segue:
SCHEMA_BUNDLE_ID: l'ID del bundle di schemi da eliminare.INSTANCE_ID: l'ID dell'istanza che contiene il bundle di schemi.TABLE_ID: l'ID della tabella che contiene il bundle di schemi.
Java
Per scoprire come installare e utilizzare la libreria client per Bigtable, consulta Librerie client di Bigtable.
Per eseguire l'autenticazione in Bigtable, configura le Credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Limitazioni
I bundle di schemi presentano le seguenti limitazioni:
- Puoi creare fino a 10 bundle di schemi per tabella. Questo limite si applica sia ai bundle di schemi protobuf che Avro.
- La dimensione totale dei descrittori del buffer di protocollo serializzati all'interno di un bundle di schemi non può superare i 4 MB. Non esiste un limite diretto al numero di singoli schemi che puoi includere in un bundle, purché le dimensioni totali del bundle non superino questo limite.
Passaggi successivi
- Scopri come eseguire query sui dati protobuf
- Scopri come creare e gestire gli schemi Avro
- Scopri di più sulle query mutevoli o incerte
- Consulta la panoramica di GoogleSQL per Bigtable