Crea y administra esquemas de Avro

Los esquemas de Apache Avro en Bigtable te permiten consultar campos individuales dentro de los registros de Avro que Bigtable almacena como bytes serializados en tus columnas. Para consultar estos campos, sube tus esquemas de Avro con formato JSON en un paquete de esquemas, un recurso a nivel de tabla que contiene uno o más de tus esquemas de registros de Avro. Para obtener más información sobre los esquemas de Apache Avro, consulta la documentación de Apache Avro.

Subir un paquete de esquemas de Avro no cambia la forma en que escribes datos en Bigtable. Seguirás escribiendo registros de Avro como bytes serializados. La carga útil de la celda solo debe contener los bytes sin procesar, sin un esquema incorporado ni una huella digital del esquema.

Después de subir un paquete de esquemas a Bigtable, puedes consultar tus datos de Avro con GoogleSQL para Bigtable, vistas materializadas continuas o vistas lógicas.

Antes de comenzar

Antes de crear y administrar paquetes de esquemas de Avro, haz lo siguiente:

  1. Instala la Google Cloud CLI.

  2. Inicializa gcloud CLI:

    gcloud init

  3. Asegúrate de tener una instancia y una tabla de Bigtable.

  4. Habilita la API de Cloud Bigtable y la API de Cloud Bigtable Admin:

    gcloud services enable bigtable.googleapis.com bigtableadmin.googleapis.com

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 Identity and Access Management (IAM) de Administrador de Bigtable (roles/bigtable.admin) en la tabla.

Para obtener acceso de solo lectura a los paquetes de esquemas y consultar registros de Avro con GoogleSQL para Bigtable, pídele a tu administrador que te otorgue el rol de lector de Bigtable (roles/bigtable.reader) o usuario de Bigtable (roles/bigtable.user) en la tabla.

Estos roles predefinidos contienen los permisos que necesitas para trabajar con paquetes de esquemas y consultar datos de Avro. Para ver los permisos necesarios, expande la sección Permisos necesarios:

Permisos necesarios

Para crear y administrar paquetes de esquemas, necesitas los siguientes permisos a nivel de la tabla o del paquete de esquemas, según la operación:

  • bigtable.schemaBundles.create: Crea paquetes de esquemas para una tabla
  • bigtable.schemaBundles.update: Actualiza una definición de paquete de esquemas
  • bigtable.schemaBundles.delete: Borra un paquete de esquemas
  • bigtable.schemaBundles.get: Obtén información sobre un paquete de esquemas
  • bigtable.schemaBundles.list: Enumera los paquetes de esquemas en una tabla
  • bigtable.schemaBundles.getIamPolicy: Obtén la política de IAM para un paquete de esquemas
  • bigtable.schemaBundles.setIamPolicy: Establece la política de IAM para un paquete de esquemas.

Para leer o filtrar registros de Avro con GoogleSQL para Bigtable, necesitas los siguientes permisos:

  • bigtable.tables.readRows
  • bigtable.instances.executeQuery

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.

Prepara archivos de esquema de Avro

Antes de crear un paquete de esquemas de Avro, prepara uno o más archivos de esquema de Avro con formato JSON en el formato de archivo AVSC o JSON. Cada archivo debe contener un esquema de Avro record válido y autónomo en el nivel superior con todas las dependencias intercaladas. Si varios archivos de un paquete intercalan el mismo record o enum en el mismo espacio de nombres, las definiciones deben coincidir, incluidos doc y aliases.

Crea un paquete de esquemas de Avro

Para crear un paquete de esquemas de Avro en una tabla, usa el comando gcloud bigtable schema-bundles create:

gcloud bigtable schema-bundles create SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

Reemplaza lo siguiente:

  • SCHEMA_BUNDLE_ID: Es un ID único para el paquete de esquemas. 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 un punto (.).
  • INSTANCE_ID: Es el ID de la instancia que contiene la tabla.
  • TABLE_ID: Es el ID de la tabla en la que se creará el paquete de esquemas.
  • AVRO_SCHEMA_PATH: Es la ruta de acceso a un archivo de esquema de Avro con formato JSON o a un directorio que contiene uno o más archivos de esquema de Avro. Cada archivo debe ser un objeto JSON independiente con todas las dependencias intercaladas.

Visualiza información sobre los paquetes de esquemas

Puedes ver 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 de la tabla.

Obtén una definición de paquete de esquemas de Avro

Para recuperar la definición del esquema de Avro con formato JSON de 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: Es el ID de la instancia.
  • TABLE_ID: el ID de la tabla

Enumera los paquetes de esquemas en una tabla

Para enumerar los IDs de todos los paquetes de esquemas de una tabla, incluidos los paquetes de esquemas de Avro y protobuf, usa el comando gcloud bigtable schema-bundles list:

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

Reemplaza lo siguiente:

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

Para inspeccionar las definiciones de esquema subyacentes de un paquete de esquemas específico de la lista, ejecuta el comando gcloud bigtable schema-bundles describe.

Actualiza un paquete de esquemas de Avro

Para actualizar un paquete de esquemas de Avro, usa el comando gcloud bigtable schema-bundles update. Solo puedes agregar definiciones de registros o enumeraciones de Avro nuevas a un paquete de esquemas de Avro existente, y no puedes cambiar el tipo de un paquete de esquemas entre Avro y protobuf. Cuando actualizas el paquete, debes pasar un archivo o directorio que incluya los esquemas nuevos y todos los existentes.

gcloud bigtable schema-bundles update SCHEMA_BUNDLE_ID \
    --instance=INSTANCE_ID \
    --table=TABLE_ID \
    --avro-schema-path=AVRO_SCHEMA_PATH

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: el ID de la tabla que contiene el paquete de esquemas
  • AVRO_SCHEMA_PATH: Es la ruta de acceso a un archivo de esquema de Avro con formato JSON o a un directorio que contiene uno o más archivos de esquema de Avro.

Borra un paquete de esquemas de Avro

Si una vista materializada continua o una vista lógica hace referencia a un paquete de esquemas, no puedes borrar el paquete. Antes de borrar el paquete, borra las vistas materializadas continuas que hagan referencia a él. En el caso de las vistas lógicas que hacen referencia al paquete, actualízalas para quitar la referencia o bórralas. Para obtener más información, consulta Crea y administra vistas materializadas continuas o Crea y administra vistas lógicas.

Para borrar un paquete de esquemas de Avro, 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: el ID de la tabla que contiene el paquete de esquemas

Precios

No se aplican cargos adicionales por crear o administrar paquetes de esquemas de Avro. Se aplican cargos estándar por el ancho de banda de red para las solicitudes y respuestas. Si usas la computación sin servidores de Data Boost para leer datos de Bigtable, pagas por los recursos de procesamiento que consumen tus consultas. Para obtener más información, consulta los precios de Bigtable.

Limitaciones

Los paquetes de esquemas de Avro tienen las siguientes limitaciones:

  • Puedes leer y consultar una columna como registros de Avro con GoogleSQL para Bigtable, vistas materializadas continuas y vistas lógicas. La API de Bigtable ReadRows y las tablas externas de BigQuery no admiten el análisis de Avro del servidor.
  • Puedes crear hasta 10 paquetes de esquemas por tabla. Este límite se aplica a los paquetes de esquemas de Avro y Protobuf.
  • El tamaño total de los esquemas de Avro con formato JSON dentro de un solo paquete de esquemas no puede superar los 4 MB. Bigtable también convierte el paquete en un conjunto de descriptores de protobuf interno, que no puede superar los 4 MB.
  • Bigtable no admite los siguientes tipos de esquemas, estructuras y patrones de nombres de Avro:
    • El tipo fixed y los tipos lógicos, como date, duration, time-micros y uuid.
    • Uniones de varias ramas con más de un tipo no nulo Solo se admiten uniones que aceptan valores nulos, como ["null", "string"].
    • Colecciones anidadas, como arrays o mapas, que contienen otros arrays o mapas.
    • Arrays con elementos que admiten valores nulos. Se admiten los mapas con valores anulables, como {"type": "map", "values": ["null", "string"]}.
    • Arrays con elementos de registro vacíos y sin campos.
    • Definiciones de registros cíclicos o recursivos, o referencias de registros y objetos JSON complejos, como registros intercalados, arrays, mapas y enumeraciones, anidados a más de 32 niveles.
    • Guiones bajos (_) en los valores namespace de Avro.
    • Duplica los nombres de símbolos enum en diferentes tipos de enum dentro del mismo espacio de nombres.
    • Varios campos map en el mismo registro cuyos nombres se convierten en la misma cadena de mayúsculas mediales, como my_map, myMap y my__map.
  • Cuando se consultan datos, Bigtable ignora ciertos atributos del esquema de Avro, como los valores predeterminados de los campos (default), aliases, doc y el orden de clasificación (order). Sin embargo, si varios archivos de un paquete definen el mismo record o enum en el mismo espacio de nombres, sus definiciones deben coincidir, incluidos doc y aliases.

¿Qué sigue?