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 tus 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 información, puedes asegurarte de 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 si defines 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, usas este conjunto de descriptores para crear un paquete de esquemas.

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. El 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 generador de consultas de Bigtable Studio, GoogleSQL para Bigtable o tablas externas de Bigtable en BigQuery.

Antes de comenzar

Sigue los siguientes pasos si planeas usar gcloud CLI:

  1. Instala la Google Cloud CLI.

  2. Inicializa gcloud CLI:

    gcloud init

Roles obligatorios

Para obtener los permisos que necesitas para crear y administrar esquemas, pídele a tu administrador que te otorgue el rol de Identity and Access Management (IAM) de Administrador de Bigtable (roles/bigtable.admin) 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 protobuf

Antes de crear un paquete de esquemas, 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 protoc busca archivos proto.
    • DESCRIPTOR_OUTPUT_LOCATION: Es el directorio en el que el compilador 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 gcloud bigtable schema-bundles create comando:

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 esquemas.
  • 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 quieres 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);
}

Visualiza 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 si recuperas la definición de un solo paquete de esquemas o si enumeras 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 gcloud bigtable schema-bundles describe comando:

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: Es el ID de la instancia.
  • TABLE_ID: Es el ID de la tabla.

Java

Para obtener la definición de un paquete de esquemas, usa el método getSchemaBundle. Este método muestra 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 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 este:

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

Enumera los paquetes de esquemas en una tabla

gcloud

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

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

Reemplaza lo siguiente:

  • INSTANCE_ID: Es el ID de la instancia.
  • TABLE_ID: Es 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 muestra 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 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 este:

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 no es compatible, la actualización falla con un error FailedPrecondition. Te recomendamos que reserves los números de campo borrados para evitar su reutilización. Para obtener más información, consulta Prácticas recomendadas de Proto en la documentación de protobuf.

Si estás seguro de que los cambios incompatibles son seguros y deseas forzar una actualización, puedes usar la marca --ignore-warnings con la gcloud CLI.

gcloud

Para actualizar un paquete de esquemas para usar un conjunto de descriptores diferente, usa el gcloud bigtable schema-bundles update comando:

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 esquemas.
  • TABLE_ID: Es el ID de la tabla que contiene el paquete de esquemas.
  • 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 el comando con la marca --ignore-warnings. Si una vista materializada continua o una vista lógica usa el paquete de esquemas, no debes forzar cambios incompatibles.

Java

Si quieres 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 gcloud bigtable schema-bundles delete comando:

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

Si una vista materializada continua o una vista lógica usa el paquete de esquemas, no borres el paquete.

Java

Si quieres 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 esquemas no puede exceder los 4 MB. No hay un límite directo en la cantidad de esquemas individuales que puedes incluir en un paquete, siempre que el tamaño total del paquete no exceda este límite.
  • Si una vista materializada continua o una vista lógica usa el paquete de esquemas, no debes forzar cambios incompatibles ni borrar el paquete.

¿Qué sigue?