Crea y administra esquemas de protobuf

En este documento, se describe cómo crear paquetes de esquemas y realizar operaciones en ellos.

En Bigtable, puedes usar esquemas de búfer de protocolo (protobuf) para consultar campos individuales dentro de mensajes protobuf almacenados como bytes en tus columnas. Para ello, sube tus esquemas en un paquete de esquemas, un recurso a nivel de la tabla que contiene uno o más de tus esquemas de protobuf.

El uso de paquetes de esquemas ofrece los siguientes beneficios:

  • Ahorra tiempo y esfuerzo: Con los búferes de protocolo, defines tu estructura de datos una vez en un archivo .proto y, luego, usas el código fuente generado para escribir y leer tus datos.
  • Mejora la coherencia de los datos: Si usas un archivo .proto como única fuente de verdad, puedes garantizar que todas las aplicaciones y los servicios usen el mismo modelo de datos.
  • Elimina la duplicación de datos: Puedes usar búferes de protocolo en todos los proyectos definiendo tipos de mensajes en archivos .proto que residen fuera de la base de código de un proyecto específico.

El proceso de uso de esquemas en Bigtable comienza con tus archivos .proto. Un archivo .proto es un archivo de texto en el que defines la estructura de tus datos. Usas la herramienta del compilador de protobuf, también conocida como protoc, para generar un conjunto de descriptores de archivos protobuf, que es un esquema legible por máquina de tu archivo .proto. Luego, usarás este conjunto de descriptores para crear un paquete de esquema.

Para ver ejemplos de archivos .proto y sus conjuntos de descriptores correspondientes, consulta Datos de ejemplo.

En el siguiente diagrama, se muestra el proceso de uso de esquemas en Bigtable:

Proceso para usar esquemas de Protobuf en Bigtable
Figura 1. Proceso de uso de esquemas de Protobuf en Bigtable (haz clic para ampliar).

Puedes crear paquetes de esquemas con la consola de Google Cloud o Google Cloud CLI. Después de subir un paquete de esquemas a Bigtable, puedes consultar tus datos con el compilador de consultas de Bigtable Studio, GoogleSQL para Bigtable o tablas externas de Bigtable en BigQuery.

Antes de comenzar

Si planeas usar gcloud CLI, sigue estos pasos:

  1. Instala la Google Cloud CLI.

  2. Inicializa la CLI de gcloud:

    gcloud init

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar paquetes de esquemas, pídele a tu administrador que te otorgue el rol de administrador de Bigtable (roles/bigtable.admin) de Identity and Access Management (IAM) en la tabla.

Este rol predefinido contiene los permisos que Bigtable requiere para trabajar con paquetes de esquemas. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

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

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Para obtener más información sobre los roles y permisos de Bigtable, consulta Control de acceso con IAM.

Genera un conjunto de descriptores de archivos .proto

Antes de crear un paquete de esquema, debes generar un conjunto de descriptores a partir de tus archivos .proto con la herramienta del compilador de Protobuf.

  1. Para instalar el compilador, descarga el paquete y sigue las instrucciones del archivo README.

  2. Ejecuta el compilador:

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

    Reemplaza lo siguiente:

    • IMPORT_PATH: Es el directorio en el que el compilador de protoc busca archivos .proto.
    • DESCRIPTOR_OUTPUT_LOCATION: Es el directorio en el que el compilador de protoc guarda el conjunto de descriptores generado.
    • PATH_TO_PROTO: Es la ruta de acceso a tu archivo .proto.

Por ejemplo, para crear un conjunto de descriptores llamado library.pb para el archivo library.proto en el directorio actual, puedes usar el siguiente comando:

protoc --include_imports --descriptor_set_out=library.pb
library.proto

Crea un paquete de esquemas

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, junto a la tabla en la que deseas crear un paquete de esquema, haz clic en el menú de acciones more_vert y, luego, en Crear paquete de esquema.

  5. En el diálogo Create schema bundle, en el campo Schema Bundle ID, ingresa un ID del paquete de esquemas único.

    El ID debe tener entre 1 y 50 caracteres, solo puede contener letras, números, guiones bajos y guiones, no puede comenzar con un guion y no puede contener el carácter de punto (.).

  6. En el campo File Descriptor Set (.pb file), haz clic en Browse para seleccionar el conjunto de descriptores de archivos de protobuf que creaste en la sección Genera un conjunto de descriptores de archivos de protobuf de este documento. El tamaño del archivo no puede superar los 4 MB.

  7. Haz clic en Crear.

    El paquete de esquemas se abrirá en una pestaña nueva.

gcloud

Para crear un paquete de esquema, usa el 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

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es un ID único para el nuevo paquete de esquema que no puede contener ningún carácter de período (".").
  • INSTANCE_ID: Es el ID de la instancia en la que creas el paquete de esquemas.
  • TABLE_ID: Es el ID de la tabla en la que creas el paquete de esquema.
  • PROTO_DESCRIPTORS_FILE: Es la ruta de acceso al conjunto de descriptores que creaste en la sección Genera un conjunto de descriptores de archivos .proto de este documento.

Java

Para crear un paquete de esquemas, usa el método createSchemaBundle:

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

Consulta información sobre los paquetes de esquemas

Antes de poder ver información sobre los paquetes de esquemas, debes tener una tabla de Bigtable con al menos un paquete de esquemas. Puedes obtener información sobre los paquetes de esquemas en una tabla recuperando la definición de un solo paquete de esquemas o enumerando todos los paquetes de esquemas en una tabla.

Obtén la definición del paquete de esquemas

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene el paquete de esquemas y, luego, expande Paquetes de esquemas.

  5. Haz clic en el paquete de esquemas que deseas ver o en el menú de acciones more_vert junto al paquete de esquemas y, luego, en Ver detalles.

    Se abrirá una pestaña que muestra la definición del paquete de esquema.

  6. Opcional: Para abrir una pestaña del editor de consulta en SQL con una consulta de ejemplo que usa el paquete de esquema, haz clic en el menú de acciones more_vert junto al paquete de esquema y, luego, en Consulta de ejemplo.

gcloud

Para obtener detalles sobre un paquete de esquemas, usa el comando gcloud bigtable schema-bundles describe:

gcloud bigtable schema-bundles describe SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID del paquete de esquemas.
  • INSTANCE_ID: el ID de la instancia
  • TABLE_ID: el ID de la tabla.

Java

Para obtener la definición de un paquete de esquema, usa el método getSchemaBundle. Este método devuelve un objeto SchemaBundle que contiene la definición del esquema.

En el siguiente ejemplo, se muestra cómo obtener un paquete de esquemas y deserializar el conjunto de descriptores para imprimir el contenido del esquema:

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

El resultado es similar a lo siguiente:

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

Enumera los paquetes de esquemas en una tabla

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene los paquetes de esquemas que deseas ver.

  5. Expande Schema Bundles.

    Aparecerá la lista de paquetes de esquemas en la tabla. Si la tabla no tiene ningún paquete de esquemas, no se muestra la lista Paquetes de esquemas.

gcloud

Para ver una lista de los paquetes de esquemas de una tabla, usa el comando gcloud bigtable schema-bundles list:

gcloud bigtable schema-bundles list \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Reemplaza lo siguiente:

  • INSTANCE_ID: el ID de la instancia
  • TABLE_ID: el ID de la tabla.

Java

Para ver una lista de todos los paquetes de esquemas en una tabla, usa el método listSchemaBundles. Este método devuelve una lista de IDs de paquetes de esquemas.

En el siguiente ejemplo, se muestra cómo enumerar los paquetes de esquemas en una tabla:

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

El resultado es similar a lo siguiente:

my-schema-bundle-1
my-schema-bundle-2

Actualiza un paquete de esquemas

Cuando actualizas un paquete de esquemas, Bigtable verifica si el nuevo conjunto de descriptores es retrocompatible con el existente. Si Bigtable detecta incompatibilidad, la actualización falla y se muestra un error FailedPrecondition. Te recomendamos que reserves los números de los campos borrados para evitar que se reutilicen. Para obtener más información, consulta Prácticas recomendadas de Proto en la documentación de protobuf.

Si tienes la certeza de que los cambios incompatibles son seguros y quieres forzar una actualización, puedes usar la marca --ignore-warnings con la gcloud CLI. Sin embargo, no puedes forzar cambios incompatibles si el paquete de esquema está en uso por una vista materializada continua o una vista lógica. Las vistas dependen de las definiciones de mensajes del paquete de esquemas para analizar y consultar datos, por lo que los cambios incompatibles interrumpirían las consultas en las vistas lógicas y provocarían que las vistas materializadas continuas fallaran durante el procesamiento de datos. Para realizar cambios incompatibles con versiones anteriores en un paquete de esquemas al que hace referencia una vista, primero debes actualizar o borrar las vistas que hacen referencia a él.

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene el paquete de esquemas y, luego, expande Paquetes de esquemas.

  5. Junto al paquete de esquemas que deseas actualizar, haz clic en el menú de acciones more_vert y, luego, en Actualizar.

  6. En el diálogo Update schema bundle, en el campo File Descriptor Set (.pb file), selecciona el nuevo conjunto de descriptores de archivos .proto. El tamaño del archivo no puede superar los 4 MB.

  7. Haz clic en Guardar.

gcloud

Para actualizar un paquete de esquemas para que use un conjunto de descriptores diferente, usa el 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

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID del paquete de esquemas que se actualizará.
  • INSTANCE_ID: Es el ID de la instancia que contiene el paquete de esquema.
  • TABLE_ID: Es el ID de la tabla que contiene el paquete de esquema.
  • PROTO_DESCRIPTORS_FILE: Es la ruta de acceso al nuevo archivo del conjunto de descriptores.

Opcional: Para forzar la actualización incluso si hay cambios incompatibles, agrega la marca --ignore-warnings al comando. No puedes forzar cambios incompatibles si el paquete de esquema está en uso por una vista materializada continua o una vista lógica.

Java

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

Borra un paquete de esquemas

No puedes borrar un paquete de esquemas si lo usa una vista materializada continua o una vista lógica. Si se borra el paquete, fallarán las consultas en las vistas lógicas y se impedirá que las vistas materializadas continuas procesen los datos entrantes. Para borrar el paquete de esquemas, primero debes borrar todas las vistas que hagan referencia a él o actualizarlas para quitar la referencia.

Console

  1. En la consola de Google Cloud , abre la lista de instancias de Bigtable.

    Abrir la lista de instancias

  2. Elige una instancia de la lista.

  3. En el panel de navegación, haz clic en Bigtable Studio.

  4. En el panel Explorador, expande la tabla que contiene el paquete de esquemas y, luego, expande Paquetes de esquemas.

  5. Junto al paquete de esquemas que deseas borrar, haz clic en el menú de acciones more_vert y, luego, en Borrar.

  6. En el diálogo de confirmación, haz clic en Borrar.

gcloud

Para borrar un paquete de esquemas, usa el comando gcloud bigtable schema-bundles delete:

gcloud bigtable schema-bundles delete SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es el ID del paquete de esquemas que se borrará.
  • INSTANCE_ID: Es el ID de la instancia que contiene el paquete de esquemas.
  • TABLE_ID: Es el ID de la tabla que contiene el paquete de esquema.

Java

Si quieres obtener información para instalar y usar la biblioteca cliente de Bigtable, consulta las bibliotecas cliente de Bigtable.

Para autenticarte en Bigtable, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local. 

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

Limitaciones

Los paquetes de esquemas tienen las siguientes limitaciones:

  • Puedes crear un máximo de 10 paquetes de esquemas por tabla.
  • El tamaño total de los descriptores de búfer de protocolo serializados dentro de un paquete de esquemas no puede superar los 4 MB. No hay un límite directo en la cantidad de esquemas individuales que puedes incluir en un paquete, siempre y cuando el tamaño total del paquete no supere este límite.

¿Qué sigue?