Programar secuencias de comandos y notebooks de SQL te permite poner en funcionamiento los recursos que se crearon en el Workbench de exploración de datos (Explorar).
Programar una secuencia de comandos de SQL o un notebook crea una tarea de Dataplex que se ejecuta a una hora predeterminada, una vez o de forma recurrente. En cada ejecución, se crea un trabajo que captura los metadatos de 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 o un notebook programados, se ejecuta la versión actual del notebook o la secuencia de comandos de SQL. Esto significa que, si programas un notebook o una secuencia de comandos en SQL y, luego, actualizas su contenido, la actualización también se refleja en las ejecuciones programadas del notebook o la secuencia de comandos en SQL.
Costos
Las secuencias de comandos de SQL y los notebooks programados activan la ejecución de trabajos con Dataproc Serverless. Los usos se cobran según el modelo de precios de Dataproc, y los cargos aparecen en Dataproc en lugar de Dataplex.
Antes de comenzar
Revisa y completa los requisitos previos que se describen en los siguientes documentos:
- La sección Antes de comenzar de Cómo usar la mesa 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 usan la API de BigQuery, debes otorgarle a la cuenta de servicio el rol de consumidor de uso del servicio (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 tiempo de ejecución del notebook programado. Para que estén disponibles en el entorno de ejecución, debes crear un programa de notebook que haga referencia a una imagen de contenedor con los paquetes adicionales necesarios. Para obtener más información, consulta Cómo programar notebooks con paquetes personalizados.
No se admite el uso de la consola de Google Cloud para hacer referencia a imágenes de contenedores personalizados cuando se programan notebooks. En su lugar, usa gcloud CLI.
No puedes editar una programación una vez creada. Para actualizar los parámetros de la programación, debes volver a crearla 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 una programación. Cuando se activa el programa, se usa la versión actual de la secuencia de comandos de SQL o el notebook.
Cuando se programan secuencias de comandos y notebooks 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 programas 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 de tiempo de ejecución de tareas correspondientes para las secuencias de comandos SQL programadas se heredan del entorno de esa secuencia de comandos SQL según la siguiente asignación:
Parámetro de configuración del entorno | Parámetro de configuración de tareas de secuencia de comandos de SQL programadas |
---|---|
Tamaño del disco principal | Imagen de contenedor o propiedades: spark.dataproc.driver.disk.size spark.dataproc.executor.disk.size |
Cantidad de nodos | Recuento de lotes o ejecutores |
Cantidad máxima de nodos | Recuento de ejecutores por lotes o máximos |
Versión de la imagen | No se hereda |
Archivos JAR | Imagen de contenedor o archivos JAR de Java |
Paquetes de Python | No se hereda |
Propiedades adicionales | Imagen o propiedades del contenedor |
Programa una secuencia de comandos de SQL
Console
En la consola de Google Cloud, ve a la página Explorar de Dataplex.
Selecciona una secuencia de comandos de SQL que quieras programar. Para ello, elige una secuencia de comandos de SQL de la lista Secuencias de comandos de Spark SQL o abre una secuencia de comandos de SQL en el Editor de Spark SQL.
En el menú Programación, haz clic en Crear programación.
En el campo Nombre de la programación, ingresa un nombre para la instancia programada.
En la sección Schedule Options, selecciona si deseas ejecutar la secuencia de comandos SQL solo una vez o de forma recurrente:
Si seleccionas Run Once, especifica si quieres ejecutar la secuencia de comandos SQL de inmediato o en un horario programado con las opciones del menú Start. Para una ejecución programada, especifica la fecha de inicio y la hora de ejecución.
Si seleccionas Repetir, especifica si deseas ejecutar la secuencia de comandos SQL a diario, semanalmente, mensualmente o en una programación personalizada especificada con una expresión cron. Además, especifica la fecha de inicio y la hora de ejecución de la ejecución programada inicial.
En la sección Destino de los resultados, haz lo siguiente:
En el campo Nombre de la carpeta de salida, haz clic en Explorar y selecciona una carpeta en un bucket de Cloud Storage en el que deseas que se almacenen los resultados de la secuencia de comandos.
Haz clic en Seleccionar.
Selecciona el Formato de salida de la secuencia de comandos. Los formatos compatibles son CSV, JSON, ORC y Parquet.
En la sección Credenciales de la secuencia de comandos programada, selecciona una cuenta de servicio del menú Cuenta de servicio del usuario.
Haga clic en Programar (Schedule).
gcloud
Para obtener información sobre cómo programar secuencias de comandos SQL con gcloud CLI, consulta Cómo programar una tarea de SparkSQL.
REST
Usa el Explorador de API para crear una tarea.
Administra las programaciones de secuencias de comandos de SQL
Console
Abre la lista de todas las programaciones de secuencias de comandos de SQL
En a consola de Google Cloud, ve a la página Proceso de Dataplex.
Haz clic en la pestaña Consultas programadas para ver la lista de programaciones de secuencias de comandos SQL.
Abre la lista de todas las programaciones de una secuencia de comandos de SQL específica.
En la consola de Google Cloud, ve a la página Explorar de Dataplex.
Selecciona la secuencia de comandos de SQL requerida.
En el menú Programar, haz clic en Ver programaciones.
Se abrirá la pestaña Consultas programadas con una lista de programaciones de secuencias de comandos SQL filtradas según la secuencia de comandos SQL seleccionada.
Cómo ver los detalles de una programación de secuencia de comandos de SQL
Ve a la pestaña Consultas programadas y selecciona la programación de la secuencia de comandos de SQL requerida.
Haz clic en la pestaña Detalles para ver los detalles de la programación de la secuencia de comandos de SQL y una preview del contenido programado.
Activa y desactiva una programación de secuencia de comandos de SQL
Ve a la pestaña Consultas programadas y selecciona la programación de la secuencia de comandos de SQL requerida.
Haz clic en Inhabilitar para desactivar una programación activa de secuencias de comandos SQL.
Haz clic en Habilitar para activar una programación de secuencia de comandos de SQL inactiva.
Borra una programación de secuencia de comandos de SQL existente
Ve a la pestaña Consultas programadas y selecciona la programación de la secuencia de comandos de SQL requerida.
Haz clic en Borrar para borrar de forma permanente una programación de secuencia de comandos de SQL existente.
Consulta los registros y administra una programación de secuencias de comandos de SQL
Ve a la pestaña Consultas programadas y selecciona la programación de la secuencia de comandos de SQL requerida.
Haz clic en la pestaña Trabajos y, luego, en el ID de trabajo de la ejecución de la secuencia de comandos de SQL programada que deseas ver.
Haz clic en Ver registros para ver los registros relacionados con la secuencia de comandos de SQL programada que se ejecutó en Cloud Logging.
Haz clic en el 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 de Dataproc Serverless correspondiente.
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 correspondiente de Cloud Storage 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 la CLI de gcloud, consulta la pestaña gcloud en Supervisa tu tarea.
Para obtener información sobre cómo administrar secuencias de comandos de SQL programadas con gcloud CLI, consulta la pestaña gcloud en Administra la programación.
REST
Para obtener información sobre cómo supervisar 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 con REST, consulta la pestaña REST en Administra la programación.
Salida 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 especificaste 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 de tiempo de ejecución de tareas correspondientes para los notebooks programados se heredan del entorno de ese notebook según la siguiente asignación:
Parámetro de configuración del entorno | Parámetro de configuración de la tarea de notebook programada |
---|---|
Tamaño del disco principal | Imagen de contenedor o propiedades: spark.dataproc.driver.disk.size spark.dataproc.executor.disk.size |
Cantidad de nodos | Recuento de lotes o ejecutores |
Cantidad máxima de nodos | Recuento de ejecutores por lotes o máximos |
Versión de la imagen | No se hereda |
Archivos JAR | Imagen de contenedor o archivos JAR de Java |
Paquetes de Python | No se hereda |
Propiedades adicionales | Imagen o propiedades del contenedor |
Programa notebooks con paquetes personalizados
En el caso de los notebooks interactivos, cuando configuras un entorno, Dataplex te permite especificar paquetes de Python personalizados que se instalarán en las sesiones del usuario aprovisionadas para el entorno. Cuando se programa un notebook de este tipo, los paquetes de Python personalizados configurados en su entorno no están disponibles en el tiempo de ejecución para el notebook programado, y el entorno de ejecución predeterminado solo tiene los componentes de la versión 1.0 del entorno de ejecución de Dataproc Serverless Spark. Para que los paquetes de Python personalizados estén disponibles en el entorno de ejecución de los notebooks programados, proporciona una imagen de contenedor personalizada con los paquetes personalizados necesarios.
No se admite especificar 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 paquetes personalizados configurados, recibirás la siguiente advertencia:
Selected environmenthas 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 deseas obtener información para establecer una imagen de contenedor para notebooks programados y instalar los paquetes de Python personalizados necesarios en el Dockerfile de la imagen de contenedor, consulta Compila una imagen de contenedor personalizada para Dataproc Serverless para Spark.
Asegúrate de haber instalado los siguientes paquetes de conda en la imagen del contenedor:
gcsfs
google-cloud-bigquery
google-cloud-storage
google-auth
ipykernel
papermill
Para instalar los componentes de gcloud
en una imagen de contenedor, abre el archivo Dockerfile de la imagen de contenedor y completa los siguientes pasos:
Agrega el paquete
google-cloud-sdk
a la lista de paquetes de Conda que se instalarán.Agrega las siguientes líneas después del paso de instalación de paquetes de conda:
# (Optional) Installing gcloud components RUN gcloud components install alpha beta bq
Programa un notebook
Console
En la consola de Google Cloud, ve a la página Explorar de Dataplex.
Selecciona el notebook que deseas programar. Para ello, selecciona un solo notebook en la vista Notebooks o abre uno en la página de detalles del notebook.
En el menú Programación, haz clic en Crear programación.
En el campo Nombre de la programación, ingresa un nombre para la instancia programada.
En la sección Schedule Options, selecciona si quieres ejecutar el notebook solo una vez o de forma recurrente:
Si seleccionas Run Once, especifica si quieres ejecutar el notebook de inmediato o a una hora programada con las opciones del menú Start. Para una ejecución programada, especifica la fecha de inicio y la hora de ejecución.
Si seleccionas Repetir, especifica si deseas ejecutar el notebook a diario, semanalmente, mensualmente o en un programa personalizado especificado con la expresión cron. Además, especifica la fecha de inicio y la hora de ejecución de la ejecución programada inicial.
En la sección Destino de los resultados, elige una ubicación en la que desees que se almacene el resultado del notebook:
En el campo Nombre de la carpeta de salida, haz clic en Explorar y selecciona una carpeta en un bucket de Cloud Storage en la que deseas que se almacene el resultado del notebook.
Haz clic en Seleccionar.
Selecciona el Formato de salida de la secuencia de comandos. Los formatos compatibles son CSV, JSON, ORC y Parquet.
En la sección Credenciales de notebook programadas, selecciona una cuenta de servicio del menú Cuenta de servicio del usuario.
En la sección Parámetros, haz clic en Agregar nuevo para agregar parámetros de ejecución para el notebook como pares clave-valor.
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
|
Es la 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. No se admite esta opción. Solo debes especificar la ruta de acceso al contenido del notebook para el parámetro --notebook . |
--notebook-archive-uris
|
Los URIs de Cloud Storage de los archivos que se extraerán en el directorio de trabajo de cada ejecutor. Los tipos de archivos admitidos son JAR , tar , tar.gz , tgz y zip . |
--notebook-file-uris |
Los URIs de Cloud Storage de los archivos que se colocarán en el directorio de trabajo de cada ejecutor. |
Recursos de procesamiento necesarios para una tarea cuando se usa Dataproc Serverless | |
--notebook-batch-executors-count |
Cantidad de ejecutores de trabajos. |
--notebook-batch-max-executors-count
|
Es la cantidad máxima de ejecutores configurables. Si notebook-batch-max-executors-count es mayor que notebook-batch-executors-count ,
el ajuste de escala automático está habilitado. |
Configuración del entorno de ejecución de la imagen de contenedor | |
--notebook-container-image |
Opcional: Es la imagen de contenedor personalizada para la tarea. |
--notebook-container-image-java-jars
|
Es una lista de archivos JAR de Java que se agregarán a la ruta de acceso de clases. La entrada válida incluye URIs de Cloud Storage para
objetos binarios JAR. Por ejemplo, gs ://BUCKET_NAME/my/path/to/file.jar . |
--notebook-container-image-properties
|
Son las propiedades que se deben establecer en los archivos de configuración del daemon. Las claves de propiedad se especifican en el formato prefix :property . Por ejemplo,: core :hadoop.tmp.dir . Para obtener más información, consulta Propiedades del clúster. |
Red de VPC de Cloud que se usa para ejecutar la infraestructura | |
--notebook-vpc-network-tags |
Es la lista de etiquetas de red que se aplicarán al trabajo. |
El identificador de la red de VPC de Cloud. Puedes especificar una de las siguientes opciones como máximo. | |
--notebook-vpc-network-name
|
La red de VPC de Cloud en la que se ejecuta la tarea De forma predeterminada, se usa la red de VPC de Cloud llamada Default dentro del proyecto. |
--notebook-vpc-sub-network-name |
La subred de VPC de Cloud en la que se ejecuta la tarea |
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 API para crear una tarea.
Administra las programaciones de notebooks
Console
Abre la lista de todas las agendas de notebooks
En a consola de Google Cloud, ve a la página Proceso de Dataplex.
Haz clic en la pestaña Cuadernos programados para ver la lista de programaciones de secuencias de comandos SQL.
Abre la lista de todos los programas de un notebook específico
En la consola de Google Cloud, ve a la página Explorar de Dataplex.
Selecciona el notebook requerido.
En el menú Programar, haz clic en Ver programaciones.
Se abrirá la pestaña Consultas programadas con una lista de programas de notebooks filtrados por el notebook seleccionado.
Cómo ver los detalles de la programación de un notebook
Ve a la pestaña Notebooks programados y selecciona el programa de notebook requerido.
Haz clic en Detalles para ver los detalles del programa del notebook y una vista previa del contenido programado.
Activa y desactiva una programación de notebooks
Ve a la pestaña Cuaderno programado y selecciona el programa de cuaderno requerido.
Haz clic en Inhabilitar para desactivar una programación activa de notebooks.
Haz clic en Habilitar para activar una programación de notebook inactiva.
Borra el programa de un notebook existente
Ve a la pestaña Cuaderno programado y selecciona el programa de cuaderno requerido.
Haz clic en Borrar para borrar de forma permanente un programa de notebook existente.
Cómo ver registros y administrar la programación de un notebook
Ve a la pestaña Cuaderno programado y selecciona el programa de cuaderno requerido.
Haz clic en la pestaña Trabajos y, luego, en el ID del trabajo de la ejecución de notebook programada que deseas ver.
En la sección Preview Output, revisa el resultado de la ejecución del notebook.
Haz clic en Ver registros para ver los registros relacionados con la ejecución de notebook programada seleccionada en Cloud Logging.
Haz clic en el 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 de Dataproc Serverless correspondiente.
Haz clic en Administrar en Cloud Storage junto a la etiqueta Resultado para abrir la página de Cloud Storage en la consola de Google Cloud. Accede a los detalles del bucket correspondiente de Cloud Storage que contiene el resultado de la ejecución del notebook.
gcloud
Para obtener información sobre cómo supervisar notebooks programados con la CLI de gcloud, consulta la pestaña gcloud en Supervisa tu tarea.
Para obtener información sobre cómo administrar notebooks programados con la CLI de gcloud, consulta la pestaña gcloud en Administra la programación.
REST
Para obtener información sobre cómo supervisar 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.
Salida de un notebook programado
El resultado de cada ejecución de un notebook programado se almacena en la ubicación que especificaste 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?
- Programa tareas personalizadas de Spark y SparkSQL.
- Configura alertas y notificaciones para las tareas de Dataplex.