Creare e gestire schemi protobuf

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

In Bigtable, puoi utilizzare gli schemi buffer di protocollo (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 schemi 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 stessomodello dei datiti.
  • 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 compilatore protobuf, chiamato anche protoc, per generare un set di descrittori del file protobuf, ovvero uno schema leggibile da 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 la console Google Cloud o Google Cloud CLI. Dopo aver caricato un bundle di schema in Bigtable, puoi eseguire query sui dati utilizzando lo strumento di creazione di query Bigtable Studio, GoogleSQL per Bigtable o 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ù sui ruoli e sulle autorizzazioni Bigtable, consulta Controllo dell'accesso con IAM.

Generare 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 riquadro di navigazione, fai clic su Bigtable Studio.

  4. Nel riquadro Explorer, accanto alla tabella in cui vuoi creare un bundle di schema, fai clic sul menu Azioni more_vert e poi su Crea bundle di schema.

  5. Nella finestra di dialogo Crea pacchetto di schemi, nel campo ID pacchetto di schemi, inserisci un identificatore univoco per il pacchetto di schemi.

    L'ID deve essere compreso 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 (.).

  6. Nel campo Set di descrittori del file (file .pb), fai clic su Sfoglia per selezionare il set di descrittori del file protobuf 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.

  7. Fai clic su Crea.

    Il bundle dello schema si apre in una nuova scheda.

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 caratteri punto (".").
  • INSTANCE_ID: l'ID dell'istanza in cui crei il bundle di schema.
  • TABLE_ID: l'ID della tabella in cui crei il bundle di schema.
  • 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 riquadro di navigazione, fai clic su Bigtable Studio.

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

  5. Fai clic sul pacchetto di schemi che vuoi visualizzare o sul menu Azioni more_vert accanto al pacchetto di schemi, quindi fai clic su Visualizza dettagli.

    Si apre una scheda che mostra la definizione del bundle di schema.

  6. (Facoltativo) Per aprire una scheda dell'editor di query SQL con una query di esempio che utilizza il bundle di schema, fai clic sul menu Azioni more_vert accanto al bundle di schema, quindi fai clic su Query di esempio.

gcloud

Per ottenere 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 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(
          "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 riquadro di navigazione, fai clic su Bigtable Studio.

  4. Nel riquadro Explorer, espandi la tabella che contiene i bundle di schema 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'elenco Bundle di schemi non viene visualizzato.

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 bundle di schemi.

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 {
  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 quello esistente. Se Bigtable rileva 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 maggiori informazioni, consulta 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. Tuttavia, non puoi forzare modifiche incompatibili se il bundle di schema è in uso da una vista materializzata continua o da una vista logica. Le viste dipendono dalle definizioni dei messaggi del bundle di schema 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 l'elaborazione dei 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 riquadro di navigazione, fai clic su Bigtable Studio.

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

  5. Accanto al bundle di schemi da aggiornare, fai clic sul menu Azioni more_vert, quindi fai clic su Aggiorna.

  6. Nella finestra di dialogo Aggiorna bundle di schemi, nel campo Set di descrittori di file (file .pb), seleziona il nuovo set di descrittori di file protobuf. Le dimensioni del file non possono superare i 4 MB.

  7. Fai clic su Salva.

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. Non puoi forzare modifiche incompatibili se il bundle di schema è 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());
}

Eliminare 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'esito negativo 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 fanno riferimento al bundle 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 riquadro di navigazione, fai clic su Bigtable Studio.

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

  5. Accanto al bundle di schemi che vuoi eliminare, fai clic sul menu azioni more_vert, quindi fai clic 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 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(
      "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 un massimo di 10 bundle di schemi per tabella.
  • Le dimensioni totali dei descrittori del buffer di protocollo serializzato all'interno di un bundle di schemi non possono superare i 4 MB. Non esiste un limite diretto al numero di singoli schemi che puoi includere in un bundle, a condizione che la dimensione totale del bundle non superi questo limite.

Passaggi successivi