Programa notebooks y secuencias de comandos de SQL

Programar secuencias de comandos y notebooks de SQL te permite poner en funcionamiento los elementos que se crearon en el espacio de trabajo de exploración de datos (Explorar).

La programación de una secuencia de comandos de SQL o un notebook crea una tarea de Dataplex que se ejecuta a un momento predeterminado, una vez o de forma recurrente. En cada ejecución, se crea un trabajo que captura los metadatos de la ejecución, como la hora de inicio y finalización, el estado, los registros y los resultados generados.

Cuando se activa una ejecución para una secuencia de comandos de SQL programada o un notebook, se ejecuta la versión actual del notebook o de la secuencia de comandos de SQL. Esto significa que, si programas un notebook o una secuencia de comandos de SQL y, luego, actualizas su contenido, la actualización también se reflejará en las ejecuciones programadas del notebook o de la secuencia de comandos de SQL.

Costos

Las secuencias de comandos de SQL programadas y los notebooks programados activan la ejecución del trabajo mediante Dataproc Serverless. Los usos se cobran según el modelo de precios de Dataproc y los cargos se muestran en Dataproc en lugar de en Dataplex.

Antes de comenzar

Revisa y completa los requisitos previos que se describen en los siguientes documentos:

  • La sección Antes de comenzar de Usa el área de trabajo de exploración de datos

  • La sección Antes de comenzar de Programa tareas personalizadas de Spark y SparkSQL

Si una secuencia de comandos de SQL o una programación de notebook usa la API de BigQuery, debes otorgar a la cuenta de servicio el rol de consumidor de Service Usage (roles/serviceusage.serviceUsageConsumer).

Limitaciones conocidas

  • Cuando programes un notebook con la consola de Google Cloud, los paquetes de Python adicionales configurados en el entorno seleccionado no estarán disponibles en el entorno de ejecución para el notebook programado. Para que estén disponibles en el entorno de ejecución, debes crear una programación de notebook que haga referencia a una imagen de contenedor con los paquetes adicionales necesarios. Para obtener más información, consulta Programa notebooks con paquetes personalizados.

  • No se admite el uso de la consola de Google Cloud para hacer referencia a imágenes de contenedor personalizadas cuando se programan notebooks. En su lugar, usa gcloud CLI.

  • No puedes editar un programa una vez creado. Para actualizar los parámetros del programa, debes volver a crear el programa con parámetros nuevos.

  • No puedes definir una versión específica de una secuencia de comandos o un notebook de SQL para usar en un programa. Cuando se activa la programación, se usa la versión actual de la secuencia de comandos de SQL o el notebook.

  • Cuando se programan notebooks y secuencias de comandos de SQL con la consola de Google Cloud, se usa la subred predeterminada. Para especificar otra red o subred, usa gcloud CLI.

Además, revisa las limitaciones conocidas de Explorar.

Crea y administra programaciones para secuencias de comandos de SQL

Configuración del entorno de ejecución para secuencias de comandos de SQL programadas

Cuando se programa una secuencia de comandos de SQL, se ejecuta como una tarea de Dataplex. Cuando se crea una programación con la consola de Google Cloud, los parámetros correspondientes del entorno de ejecución de tareas para las secuencias de comandos de SQL programadas se heredan del entorno de esa secuencia de comandos de SQL en función de la siguiente asignación:

Parámetro de configuración del entorno Parámetro de configuración de la tarea de secuencia de comandos de SQL programada
Tamaño del disco principal Imagen o propiedades de contenedor:
   spark.dataproc.driver.disk.size
   spark.dataproc.executor.disk.size
Cantidad de nodos Recuento de lotes y ejecutores
Cantidad máxima de nodos Recuento de ejecutores por lotes o máximo
Versión de la imagen No heredada
Archivos JAR Imagen de contenedor / JARS de Java
Paquetes de Python No heredada
Propiedades adicionales Imagen / propiedades del contenedor

Programa una secuencia de comandos de SQL

Console

  1. En la consola de Google Cloud, ve a la página Explorar de Dataplex.

    Ir a la exploración de Dataplex

  2. Selecciona la secuencia de comandos SQL que desees programar, ya sea seleccionando una sola secuencia de comandos de SQL de la lista de Secuencias de comandos de Spark SQL o abriendo una secuencia de comandos de SQL en el Editor de Spark SQL.

  3. En el menú Programación, haz clic en Crear programación.

  4. En el campo Nombre del programa, ingresa un nombre para la instancia programada.

  5. En la sección Schedule Options, selecciona si quieres ejecutar la secuencia de comandos de SQL
    solo una vez o de forma recurrente:

    1. Si seleccionas Ejecutar una vez, especifica si deseas ejecutar la secuencia de comandos de SQL de inmediato o en un momento programado mediante las opciones del menú Inicio. Para una ejecución programada, especifica la fecha de inicio y la hora de ejecución.

    2. Si seleccionas Repetir, especifica si deseas ejecutar la secuencia de comandos de SQL de forma diaria, semanal, mensual o en una programación personalizada especificada mediante la expresión cron. Además, especifica la fecha de inicio y el tiempo de ejecución para la ejecución programada inicial.

  6. En la sección Destino de los resultados, haz lo siguiente:

    1. En el campo Nombre de la carpeta de salida, haz clic en Explorar y selecciona una carpeta en el bucket de Cloud Storage en la que desees que se almacenen los resultados de la secuencia de comandos.

    2. Haz clic en Seleccionar.

    3. Selecciona el Formato de salida de la secuencia de comandos. Los formatos compatibles son CSV, JSON, ORC y Parquet.

  7. En la sección Credenciales de secuencia de comandos programadas, selecciona una cuenta de servicio del menú Cuenta de servicio de usuario.

  8. Haga clic en Programar (Schedule).

gcloud

Para obtener información sobre cómo programar secuencias de comandos de SQL con gcloud CLI, consulta Programa una tarea de SparkSQL.

REST

Usa el Explorador de APIs para crear una tarea.

Administrar programaciones de secuencias de comandos de SQL

Console

Abrir la lista de todas las programaciones de secuencias de comandos de SQL

  1. En a consola de Google Cloud, ve a la página Proceso de Dataplex.

  2. Haz clic en la pestaña Consultas programadas para ver la lista de programaciones de secuencias de comandos de SQL.

Abrir la lista de todas las programaciones de una secuencia de comandos de SQL específica

  1. En la consola de Google Cloud, ve a la página Explorar de Dataplex.

  2. Selecciona la secuencia de comandos SQL requerida.

  3. En el menú Programación, haz clic en Ver programaciones.

    Se abrirá la pestaña Consultas programadas con una lista de programaciones de secuencias de comandos de SQL filtradas por la secuencia de comandos de SQL seleccionada.

Ver los detalles de una programación de la secuencia de comandos de SQL

  1. Ve a la pestaña Consultas programadas y selecciona la programación de secuencia de comandos de SQL requerida.

  2. Haz clic en la pestaña Detalles para ver los detalles de la programación de la secuencia de comandos de SQL y una vista previa del contenido de la secuencia de comandos de SQL programada.

Activa y desactiva una programación de secuencia de comandos de SQL

  1. Ve a la pestaña Consultas programadas y selecciona la programación de secuencia de comandos de SQL requerida.

  2. Haz clic en Inhabilitar para desactivar una programación activa de secuencia de comandos de SQL.

  3. Haz clic en Habilitar para activar una programación de secuencia de comandos de SQL inactiva.

Borrar una programación de secuencia de comandos de SQL existente

  1. Ve a la pestaña Consultas programadas y selecciona la programación de secuencia de comandos de SQL requerida.

  2. Haz clic en Borrar para borrar de forma permanente una programación de secuencia de comandos de SQL existente.

Consulta registros y administra una programación de secuencias de comandos de SQL

  1. Ve a la pestaña Consultas programadas y selecciona la programación de secuencia de comandos de SQL requerida.

  2. Haz clic en la pestaña Trabajos y, luego, en el ID de trabajo de la ejecución de la secuencia de comandos SQL programada que deseas ver.

  3. Haz clic en Ver registros para ver los registros relacionados con la secuencia de comandos de SQL programada seleccionada que se ejecutan en Cloud Logging.

  4. Haz clic en ID de lote de Dataproc para abrir la página de Dataproc en la consola de Google Cloud. Accede a los detalles de la sesión correspondiente de Dataproc Serverless.

  5. Haz clic en Administrar en Cloud Storage junto a la etiqueta Salida para abrir la página de Cloud Storage en la consola de Google Cloud. Accede a los detalles del bucket de Cloud Storage correspondiente que contiene el resultado de la ejecución de la secuencia de comandos de SQL.

gcloud

Para obtener información sobre cómo supervisar secuencias de comandos de SQL programadas con gcloud CLI, consulta la pestaña de gcloud en Supervisa tu tarea.

Para obtener más información sobre cómo administrar secuencias de comandos de SQL programadas con gcloud CLI, consulta la pestaña de gcloud en Administra la programación.

REST

Para obtener información sobre la supervisión de secuencias de comandos de SQL programadas con REST, consulta la pestaña REST en Supervisa tu tarea.

Para obtener información sobre cómo administrar secuencias de comandos de SQL programadas mediante REST, consulta la pestaña REST en Administra la programación.

Resultado de una secuencia de comandos de SQL programada

El resultado de cada ejecución de una secuencia de comandos de SQL programada se almacena en la ubicación que especifiques para la carpeta de Cloud Storage, en la siguiente estructura:

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

Crea y administra programas para notebooks

Configuración del entorno de ejecución para notebooks programados

Cuando se programa un notebook, se ejecuta como una tarea de Dataplex. Cuando se crea un programa con la consola de Google Cloud, los parámetros correspondientes del entorno de ejecución de las tareas para los notebooks programados se heredan del entorno de ese notebook en función de la siguiente asignación:

Parámetro de configuración del entorno Parámetro de configuración de tareas de notebook programadas
Tamaño del disco principal Imagen o propiedades de contenedor:
   spark.dataproc.driver.disk.size
   spark.dataproc.executor.disk.size
Cantidad de nodos Recuento de lotes y ejecutores
Cantidad máxima de nodos Recuento de ejecutores por lotes o máximo
Versión de la imagen No heredada
Archivos JAR Imagen de contenedor / JARS de Java
Paquetes de Python No heredada
Propiedades adicionales Imagen / propiedades del contenedor

Programa notebooks con paquetes personalizados

En el caso de los notebooks interactivos, cuando configuras un entorno, Dataplex te permite especificar paquetes personalizados de Python para instalar en sesiones de usuario aprovisionadas para el entorno. Cuando se programa un notebook de este tipo, los paquetes personalizados de Python configurados en su entorno no están disponibles en el entorno de ejecución para el notebook programado, y el entorno de ejecución predeterminado solo tiene los componentes del entorno de ejecución de Dataproc Serverless Spark versión 1.0. A fin de que los paquetes personalizados de Python estén disponibles en el entorno de ejecución para los notebooks programados, proporciona una imagen de contenedor personalizada con los paquetes personalizados necesarios.

No se admite la especificación de una imagen de contenedor personalizada cuando se programa un notebook con la consola de Google Cloud. En su lugar, usa gcloud CLI. Para obtener más información, consulta Programa un notebook.

Si programas un notebook con un entorno que tiene configurados paquetes personalizados, verás la siguiente advertencia:

Selected environment  has additional Python packages configured.
These packages will not be available in the default runtime for the scheduled notebook
when scheduling in the Console. To make the required additional Python packages
available in the runtime, please create Notebook Schedule using gcloud command
instead, referencing a container image with required additional packages.

Compila una imagen de contenedor personalizada para notebooks programados

Si quieres obtener información sobre cómo establecer una imagen de contenedor para los notebooks programados y cómo instalar los paquetes personalizados de Python necesarios en el archivo Docker de la imagen del contenedor, consulta Compila una imagen de contenedor personalizada en Dataproc Serverless para Spark.

Asegúrate de haber instalado los siguientes paquetes conda en la imagen del contenedor:

  • gcsfs
  • google-cloud-bigquery
  • google-cloud-storage
  • google-auth
  • ipykernel
  • papermill

Para instalar los componentes gcloud en una imagen de contenedor, abre el Dockerfile de la imagen de contenedor y completa los siguientes pasos:

  1. Agrega el paquete google-cloud-sdk a la lista de paquetes conda que se instalarán.

  2. Agrega las siguientes líneas después del paso de instalación de los paquetes conda:

    # (Optional) Installing gcloud components
RUN gcloud components install alpha beta bq gsutil

Programa un notebook

Console

  1. En la consola de Google Cloud, ve a la página Explorar de Dataplex.

    Ir a la exploración de Dataplex

  2. Selecciona un notebook que desees programar, ya sea seleccionando un solo notebook en la vista Notebooks o abriendo un notebook en la página de detalles del notebook.

  3. En el menú Programación, haz clic en Crear programación.

  4. En el campo Nombre del programa, ingresa un nombre para la instancia programada.

  5. En la sección Opciones de programación, selecciona si deseas ejecutar el notebook solo una vez o de forma recurrente:

    1. Si seleccionas Ejecutar una vez, especifica si deseas ejecutar el notebook de inmediato o en un horario programado, con las opciones del menú Inicio. Para una ejecución programada, especifica la fecha de inicio y la hora de ejecución.

    2. Si seleccionas Repetir, especifica si deseas ejecutar el notebook de forma diaria, semanal, mensual o según una programación personalizada que se especifique mediante la expresión cron. Además, especifica la fecha de inicio y el tiempo de ejecución para la ejecución programada inicial.

  6. En la sección Destino de los resultados, elige la ubicación en la que deseas que se almacene el resultado del notebook:

    1. En el campo Nombre de la carpeta de salida, haz clic en Explorar y selecciona una carpeta en el bucket de Cloud Storage en la que desees que se almacene el resultado del notebook.

    2. Haz clic en Seleccionar.

    3. Selecciona el Formato de salida de la secuencia de comandos. Los formatos compatibles son CSV, JSON, ORC y Parquet.

  7. En la sección Credenciales de notebook programado, selecciona una cuenta de servicio del menú Cuenta de servicio de usuario.

  8. En la sección Parámetros, haz clic en Agregar nuevo para agregar los parámetros de ejecución del notebook como pares clave-valor.

  9. Haga clic en Programar (Schedule).

gcloud

Ejecuta el comando de gcloud CLI que se describe en Programa una tarea de Spark (Java o Python) con los siguientes parámetros adicionales:

Parámetro Descripción
--notebook Ruta de acceso al contenido de un notebook para el notebook de entrada. Se puede acceder a los argumentos de ejecución como variables de entorno. Por ejemplo, TASK_key=value.
Nota: En la documentación de referencia de gcloud para programar notebooks como tareas, se menciona que el valor del parámetro --notebook puede ser el URI de Cloud Storage del archivo de notebook. Esto no se admite. Solo debes especificar la ruta de acceso al contenido del notebook para el parámetro --notebook.
--notebook-archive-uris Los URI de Cloud Storage de los archivos que se extraerán en el directorio de trabajo de cada ejecutor. Los tipos de archivo admitidos son JAR, tar, tar.gz, tgz y zip.
--notebook-file-uris Los URI de Google Cloud Storage de los archivos que se colocarán en el directorio de trabajo de cada ejecutor.
Recursos de procesamiento necesarios para realizar una tarea cuando se usa Dataproc Serverless
--notebook-batch-executors-count Cantidad de ejecutores de trabajos.
--notebook-batch-max-executors-count Máximo de ejecutores configurables.
Si notebook-batch-max-executors-count es mayor que notebook-batch-executors-count, se habilita el ajuste de escala automático.
Configuración del entorno de ejecución de la imagen de contenedor
--notebook-container-image Imagen de contenedor personalizada para el trabajo (opcional).
--notebook-container-image-java-jars Una lista de archivos JAR de Java para agregar a la ruta de clase. La entrada válida incluye URI de Cloud Storage a objetos binarios de JAR. Por ejemplo, gs://BUCKET_NAME/my/path/to/file.jar.
--notebook-container-image-properties Las propiedades para configurar en los archivos de configuración del daemon.
Las claves de las propiedades se especifican en el formato prefix:property. Por ejemplo,:
core:hadoop.tmp.dir.
Para obtener más información, consulta Propiedades del clúster.
La red de VPC de Cloud que se usa para ejecutar la infraestructura
--notebook-vpc-network-tags Lista de etiquetas de red para aplicar al trabajo.
El identificador de red de VPC de Cloud. Puedes especificar como máximo una de las siguientes opciones.
--notebook-vpc-network-name La red de VPC de Cloud en la que se ejecuta el trabajo. De forma predeterminada, se usa la red de VPC de Cloud Default dentro del proyecto.
--notebook-vpc-sub-network-name La subred de VPC de Cloud en la que se ejecuta el trabajo.
Ubicación de los resultados del notebook
--execution-args Para las tareas de notebook, el siguiente argumento es obligatorio y se debe pasar como TASK_ARGS.
--execution-args=^::^TASK_ARGS="--output_location,CLOUD_STORAGE_URI_OF_OUTPUT_DIRECTORY"

El siguiente es un ejemplo del comando gcloud que se usa para programar notebooks: 

gcloud dataplex tasks create sample-task --project=sample-project --location=us-central1 --lake=my-lake --trigger-type=ON_DEMAND --notebook="projects/my-project-id/locations/us-central1/lakes/my-lake/content/my-notebook.ipynb" --execution-service-account=associated-service-account@sample-project.iam.gserviceaccount.com  --execution-args=^::^TASK_ARGS="--output_location,gs://my-bucket/Demo" --notebook-batch-executors-count=2 --notebook-batch-max-executors-count=5 --notebook-container-image=container-image --notebook-container-image-java-jars=java-jar1,java-jar-2

REST

Usa el Explorador de APIs para crear una tarea.

Administrar programas de notebooks

Console

Abrir la lista de todas las programaciones de notebooks

  1. En a consola de Google Cloud, ve a la página Proceso de Dataplex.

  2. Haz clic en la pestaña Notebooks programados para ver la lista de programaciones de secuencias de comandos de SQL.

Abrir la lista de todos los programas de un notebook específico

  1. En la consola de Google Cloud, ve a la página Explorar de Dataplex.

  2. Selecciona el notebook requerido.

  3. En el menú Programación, haz clic en Ver programaciones.

    Se abrirá la pestaña Consultas programadas con una lista de programas de notebooks filtrados por el notebook seleccionado.

Visualiza los detalles de la programación de un notebook

  1. Ve a la pestaña Notebooks programados y selecciona la programación de notebook necesaria.

  2. Haz clic en los detalles de Detalles de la programación del notebook y en una vista previa del contenido del notebook programado.

Activa y desactiva una programación de notebook

  1. Ve a la pestaña Notebook programado y selecciona el programa de notebook requerido.

  2. Haz clic en Inhabilitar para desactivar una programación de notebook activa.

  3. Haz clic en Habilitar para activar una programación de notebook inactivo.

Borrar una programación de notebook existente

  1. Ve a la pestaña Notebook programado y selecciona el programa de notebook requerido.

  2. Haz clic en Borrar para borrar de forma permanente una programación de notebook existente.

Visualiza registros y administra la programación de notebooks

  1. Ve a la pestaña Notebook programado y selecciona el programa de notebook requerido.

  2. Haz clic en la pestaña Trabajos y, luego, en el ID de trabajo de la ejecución programada del notebook que deseas ver.

  3. En la sección Vista previa del resultado, revisa el resultado de la ejecución del notebook.

  4. Haz clic en Ver registros para ver los registros relacionados con la ejecución del notebook programado seleccionado en Cloud Logging.

  5. Haz clic en ID de lote de Dataproc para abrir la página de Dataproc en la consola de Google Cloud. Accede a los detalles de la sesión correspondiente de Dataproc Serverless.

  6. Haz clic en Administrar en Cloud Storage junto a la etiqueta Salida para abrir la página de Cloud Storage en la consola de Google Cloud. Accede a los detalles del bucket de Cloud Storage correspondiente que contiene el resultado de la ejecución del notebook.

gcloud

Para obtener información sobre la supervisión de notebooks programados con gcloud CLI, consulta la pestaña de gcloud en Supervisa tu tarea.

Si quieres obtener información para administrar notebooks programados con gcloud CLI, consulta la pestaña gcloud en Administra la programación.

REST

Para obtener información sobre la supervisión de notebooks programados con REST, consulta la pestaña REST en Supervisa tu tarea.

Para obtener información sobre cómo administrar notebooks programados con REST, consulta la pestaña REST en Administra la programación.

Resultado de un notebook programado

El resultado de cada ejecución de un notebook programado se almacena en la ubicación que especifiques para la carpeta de Cloud Storage, en la siguiente estructura:

CLOUD_STORAGE_FOLDER_LOCATION/projects/PROJECT_ID/locations/LOCATION_ID/lakes/LAKE_ID/tasks/TASK_ID/JOB_ID/QUERY_NUMBER

¿Qué sigue?