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 la 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 una ú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 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 las 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

gcloud

Para crear un paquete de esquemas, 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 esquemas que no puede contener ningún carácter de punto (“.”).
  • INSTANCE_ID: Es el ID de la instancia en la que se creará el paquete de esquemas.
  • TABLE_ID: Es el ID de la tabla en la que se creará el paquete de esquema.
  • PROTO_DESCRIPTORS_FILE: Es la ruta de acceso al conjunto de descriptores generado en el paso anterior.

Java

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

Si deseas obtener información sobre cómo 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);
  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);
}

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

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 deseas obtener información sobre cómo 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(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());
}

El resultado es similar a lo siguiente:

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

Enumera paquetes de esquemas en una tabla

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 deseas obtener información sobre cómo 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 {
  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());
}

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 es incompatible, la actualización falla con 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 Proto Best Practices 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 gcloud CLI.

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 de conjunto de descriptores.

Opcional: Para forzar la actualización incluso si hay cambios incompatibles, agrega la marca --ignore-warnings al comando.

Java

Si deseas obtener información sobre cómo 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);
  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);
}

Borra un paquete de esquemas

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 esquema que se borrará.
  • 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.

Java

Si deseas obtener información sobre cómo 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(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());
}

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 esquema 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?