Creare e gestire schemi protobuf

Questo documento descrive come creare ed eseguire operazioni sui bundle di schemi.

In Bigtable, puoi utilizzare gli schemi protocol buffer (protobuf) per eseguire query sui singoli campi all'interno dei messaggi protobuf archiviati come byte nelle colonne. A questo scopo, 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 schema offre i seguenti vantaggi:

  • Risparmia tempo e fatica: con i protocol buffer, definisci la struttura dei dati una sola volta in un file proto e poi 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 tutti i servizi utilizzino lo stesso modello dei dati.
  • Elimina la duplicazione dei dati: puoi utilizzare i protocol buffer in più progetti definendo i tipi di messaggio nei file proto che si trovano al di fuori del 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. Utilizzi lo strumento di compilazione protobuf, chiamato anche protoc, per generare un set di descrittori di file protobuf, ovvero uno schema leggibile dalla macchina del tuo file proto. Utilizzi quindi questo set di descrittori per creare un bundle di schema.

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:

Il processo di utilizzo degli schemi protobuf in Bigtable.
Figura 1. Il processo di utilizzo degli schemi protobuf in Bigtable (fai clic per ingrandire).

Puoi creare bundle di schemi utilizzando Google Cloud CLI. Dopo aver caricato un bundle di schema in Bigtable, puoi eseguire query sui dati utilizzando il generatore di query di Bigtable Studio, GoogleSQL per Bigtable o le tabelle esterne Bigtable in BigQuery.

Prima di iniziare

Se prevedi di utilizzare gcloud CLI, segui questi passaggi:

  1. Installa Google Cloud CLI.

  2. 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 lavorare con i bundle di schema. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

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

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Per saperne di più su ruoli e autorizzazioni Bigtable, consulta Controllo dell'accesso 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.

  1. Per installare il compilatore, scarica il pacchetto e segui le istruzioni nel file README.

  2. Esegui il compilatore:

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

    Sostituisci 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

gcloud

Per creare un bundle di schema, 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 il carattere punto (".").
  • INSTANCE_ID: l'ID dell'istanza in cui creare il bundle di schema.
  • TABLE_ID: l'ID della tabella in cui creare il bundle di schema.
  • PROTO_DESCRIPTORS_FILE: il percorso del set di descrittori generato nel passaggio precedente.

Java

Per creare un bundle di schema, 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. 

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

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

gcloud

Per ottenere i dettagli di un bundle di schema, 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 schema.
  • INSTANCE_ID: l'ID dell'istanza.
  • TABLE_ID: l'ID della tabella.

Java

Per ottenere la definizione di un bundle di schema, 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 schemi 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. 

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

L'output è simile al seguente:

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

Elenca i bundle di schemi in una tabella

gcloud

Per visualizzare un elenco di bundle di schema 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 bundle di schema.

Il seguente esempio 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. 

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

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 quello esistente. Se non è compatibile, l'aggiornamento non va a buon fine e viene visualizzato l'errore FailedPrecondition. Ti consigliamo di riservare i numeri dei campi eliminati per impedirne il riutilizzo. Per saperne di più, consulta le best practice per 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.

gcloud

Per aggiornare un bundle di schema 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 schema.
  • TABLE_ID: l'ID della tabella che contiene il bundle di schema.
  • PROTO_DESCRIPTORS_FILE: il percorso del nuovo file del set di descrittori.

(Facoltativo) Per forzare l'aggiornamento anche in presenza di modifiche incompatibili, aggiungi il flag --ignore-warnings al comando.

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. 

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

Eliminare un bundle di schemi

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 schema.
  • TABLE_ID: l'ID della tabella che contiene il bundle di schema.

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. 

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

Limitazioni

I bundle di schemi presentano le seguenti limitazioni:

  • Puoi creare un massimo di 10 bundle di schemi per tabella.
  • Le dimensioni totali dei descrittori del protocol buffer serializzati all'interno di un bundle di schema non possono superare 4 MB. Non esiste un limite diretto al numero di schemi individuali che puoi includere in un bundle, a condizione che la dimensione totale del bundle non superi questo limite.

Passaggi successivi