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:

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

  1. Installa gcloud 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 utilizzare i bundle di schemi. 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ù 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.

  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

Console

  1. Nella console Google Cloud , apri l'elenco delle istanze Bigtable.

    Apri l'elenco delle istanze

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Bigtable Studio.

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

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

  6. 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 (.).

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

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

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

  1. Nella console Google Cloud , apri l'elenco delle istanze Bigtable.

    Apri l'elenco delle istanze

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Bigtable Studio.

  4. Nel riquadro Explorer, espandi la tabella che contiene il bundle di schemi, quindi espandi Bundle di schemi.

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

  6. (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.

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

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

  1. Nella console Google Cloud , apri l'elenco delle istanze Bigtable.

    Apri l'elenco delle istanze

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Bigtable Studio.

  4. Nel riquadro Explorer, espandi la tabella contenente i bundle di schemi che vuoi visualizzare.

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

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

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

  1. Nella console Google Cloud , apri l'elenco delle istanze Bigtable.

    Apri l'elenco delle istanze

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Bigtable Studio.

  4. Nel riquadro Explorer, espandi la tabella che contiene il bundle di schemi, quindi espandi Bundle di schemi.

  5. Accanto al bundle di schemi che vuoi aggiornare, fai clic su  Visualizza azioni, quindi su Aggiorna.

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

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

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

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

  1. Nella console Google Cloud , apri l'elenco delle istanze Bigtable.

    Apri l'elenco delle istanze

  2. Seleziona un'istanza dall'elenco.

  3. Nel menu di navigazione, fai clic su Bigtable Studio.

  4. Nel riquadro Explorer, espandi la tabella che contiene il bundle di schemi, quindi espandi Bundle di schemi.

  5. Accanto al bundle di schemi che vuoi eliminare, fai clic su  Visualizza azioni, quindi su Elimina.

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

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

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