Dataplex Universal Catalog admite la programación de la ejecución de código personalizado, ya sea como una ejecución única, con una programación regular o a pedido. La función a pedido está en versión preliminar y solo está disponible a través de la API. Puedes programar transformaciones de datos del cliente con Spark (Java), PySpark (limitado a la versión 3.2 de Spark) o Spark SQL. Dataplex Universal Catalog ejecuta el código con procesamiento de Spark sin servidores y un programador sin servidores integrado.
Terminología
- Tarea
- Una tarea de Dataplex Universal Catalog representa el trabajo que deseas que Dataplex Universal Catalog realice según una programación. Encapsula tu código, tus parámetros y la programación.
- Trabajo
Un trabajo representa una sola ejecución de una tarea de Dataplex Universal Catalog. Por ejemplo, si una tarea está programada para ejecutarse a diario, Dataplex Universal Catalog creará un trabajo todos los días.
En el caso de los trabajos creados a partir del 10 de mayo de 2023, el campo Activador muestra el tipo de activador de ejecución del trabajo.
Estos son los tipos de activadores de ejecución de trabajos:
RUN_REQUEST: Indica que el trabajo se ejecutó porque se llamó a la API de
RunTask.TASK_CONFIG: Indica que el trabajo se ejecutó debido a la configuración de
TriggerSpecde la tarea.
Modos de programación
Dataplex Universal Catalog admite los siguientes modos de programación:
- Ejecutar una vez
- Usa este modo para ejecutar tu tarea solo una vez. Puedes elegir ejecutarla de inmediato o en un momento determinado en el futuro. Si ejecutas la tarea de inmediato, es posible que la ejecución tarde hasta dos minutos en comenzar.
- Ejecutar según una programación
- Usa este modo para ejecutar la tarea con una frecuencia repetida. Las repeticiones admitidas son diarias, semanales, mensuales o personalizadas.
- Ejecutar a pedido
Usa este modo para ejecutar una tarea creada anteriormente a pedido. El modo de ejecución a pedido solo es compatible con la API de
RunTask. Cuando tu trabajo se ejecuta a pedido, Dataplex Universal Catalog usa parámetros existentes para crear un trabajo. Puedes especificar los argumentosExecutionSpecy las etiquetas para ejecutar el trabajo.
Antes de comenzar
Habilita la API de Dataproc
Habilita el Acceso privado a Google para tu red y subred. Habilita el acceso privado a Google en la red que usas con las tareas de Dataplex Universal Catalog. Si no especificas una red o una subred cuando creas la tarea de Dataplex Universal Catalog, Dataplex Universal Catalog usa la subred predeterminada, y debes habilitar el Acceso privado a Google para la subred predeterminada.
Crea una cuenta de servicio. Se requiere una cuenta de servicio para programar cualquier tarea de Dataplex Universal Catalog. La cuenta de servicio debe pertenecer al proyecto en el que ejecutas las tareas. La cuenta de servicio debe tener los siguientes permisos:
Acceso a los datos de BigQuery y Cloud Storage que se están procesando
Permiso del rol de trabajador de Dataproc en el proyecto en el que ejecutas la tarea.
Si la tarea necesita leer o actualizar la instancia de Dataproc Metastore adjunta al lake, la cuenta de servicio necesita el rol de visualizador o editor de Dataproc Metastore. Este rol se debe otorgar en el proyecto en el que se configura el lago de datos de Dataplex Universal Catalog.
Si la tarea es un trabajo de Spark SQL, debes otorgar a la cuenta de servicio el rol de desarrollador del catálogo universal de Dataplex. Este rol se debe otorgar en el proyecto en el que se configura el lake de Dataplex Universal Catalog.
Si la tarea es un trabajo de Spark SQL, necesitas permisos de administrador de Cloud Storage en el bucket en el que se escriben los resultados.
Para programar y ejecutar tareas personalizadas de Spark y Spark SQL, debes tener los roles de IAM de lector de metadatos de Dataplex Universal Catalog (
roles/dataplex.metadataReader), visualizador de Dataplex Universal Catalog (roles/dataplex.viewer) y usuario de metadatos de Dataproc Metastore (roles/metastore.metadataUser) en tu cuenta de servicio.
Otorga al usuario que envía el trabajo el rol de usuario de cuenta de servicio (
roles/iam.serviceAccountUser) en la cuenta de servicio. Para obtener instrucciones, consulta Administra el acceso a las cuentas de servicio.Otorga permisos a la cuenta de servicio del lake de Dataplex Universal Catalog para usar la cuenta de servicio. Puedes encontrar la cuenta de servicio del lake de Dataplex Universal Catalog en la página Lake Details de la consola deGoogle Cloud .
Si el proyecto que contiene tu lake de Dataplex Universal Catalog es diferente del proyecto en el que se ejecutará la tarea, otorga a la cuenta de servicio del lake de Dataplex Universal Catalog el rol de editor de Dataproc en el proyecto en el que ejecutas la tarea.
Coloca los artefactos de código requeridos (archivos JAR, Python o de secuencias de comandos SQL) o los archivos archivados (
.jar,.tar,.tar.gz,.tgz,.zip) en una ruta de Cloud Storage.Asegúrate de que la cuenta de servicio tenga el permiso
storage.objects.getrequerido para el bucket de Cloud Storage que almacena estos artefactos de código.
Programa una tarea de Spark (Java o Python)
Console
En la consola de Google Cloud , ve a la página Proceso de Dataplex Universal Catalog.
Haz clic en Crear tarea.
En Create Custom Spark Task, haz clic en Create task.
Elige un lake de Dataplex Universal Catalog.
Proporciona un nombre para la tarea.
Crea un ID para tu tarea.
En la sección Configuración de la tarea, en Tipo, selecciona Spark o PySpark.
Ingresa los argumentos pertinentes.
En el campo Cuenta de servicio, ingresa una cuenta de servicio del usuario con la que se pueda ejecutar tu tarea personalizada de Spark.
Haz clic en Continuar.
Opcional: Establecer programa: Selecciona Ejecutar una vez o Repetir. Completa los campos obligatorios.
Haz clic en Continuar.
Opcional: Personaliza recursos y Agrega parámetros de configuración adicionales.
Haz clic en Crear.
gcloud
Puedes programar una tarea de Spark (Java / Python) con el comando de gcloud CLI. En la siguiente tabla, se enumeran los parámetros obligatorios y opcionales que se pueden usar:
| Parámetro | Descripción |
|---|---|
--lake |
Es el ID del recurso del lake del servicio de Dataplex Universal Catalog. |
--location |
Ubicación del servicio de Dataplex Universal Catalog. |
--spark-main-class |
Es la clase principal del controlador. El archivo jar que contiene la clase debe estar en el CLASSPATH predeterminado.
|
--spark-main-jar-file-uri |
Es el URI de Cloud Storage del archivo jar que contiene la clase principal.
|
--spark-archive-uris |
Opcional: Son los URIs de Cloud Storage de los archivos que se extraerán en el directorio de trabajo de cada ejecutor. Tipos de archivos compatibles:
.jar, .tar, .tar.gz,
.tgz y .zip.
|
--spark-file-uris |
Opcional: Son los URIs de Cloud Storage de los archivos que se colocarán en el directorio de trabajo de cada ejecutor. |
--batch-executors-count |
Opcional: Es la cantidad total de ejecutores de trabajos. El valor predeterminado es 2. |
--batch-max-executors-count |
Cantidad máxima de ejecutores configurables (opcional). El valor predeterminado es 1,000. Si batch-max-executors-count es mayor que batch-executors-count, Dataplex Universal Catalog habilita el ajuste de escala automático.
|
--container-image-java-jars |
Opcional: Es una lista de archivos JAR de Java que se agregarán a la ruta de acceso de clase. La entrada válida
incluye los URI de Cloud Storage para los archivos binarios de Jar. Por ejemplo, gs://bucket-name/my/path/to/file.jar.
|
--container-image-properties |
Opcional: Son las claves de propiedad, especificadas en formato prefix:property.Por ejemplo, core:hadoop.tmp.dir.Para obtener más información, consulta Propiedades del clúster. |
--vpc-network-tags |
Opcional: Es una lista de etiquetas de red que se aplicarán al trabajo. |
--vpc-network-name |
Opcional: Es la red de nube privada virtual en la que se ejecuta el trabajo. De forma predeterminada, Dataplex Universal Catalog usa la red de VPC llamada Default dentro del proyecto. Solo debes usar uno de los siguientes elementos: --vpc-network-name o --vpc-sub-network-name.
|
--vpc-sub-network-name |
Opcional: Es la subred de VPC en la que se ejecuta el trabajo.
Solo debes usar uno de los elementos --vpc-sub-network-name o --vpc-network-name.
|
--trigger-type |
Es el tipo de activación de la tarea especificada por el usuario. Los valores deben ser uno de los siguientes:ON_DEMAND: La tarea se ejecuta una vez poco después de su creación.RECURRING: La tarea se ejecuta periódicamente según un programa.
|
--trigger-start-time |
Opcional: Es la fecha y hora de la primera ejecución de la tarea. El formato es `{año}-{mes}-{día}T{hora}:{min}:{seg}Z`, donde la zona horaria es UTC. Por ejemplo, "2017-01-15T01:30:00Z" codifica las 1:30 UTC del 15 de enero de 2017. Si no se especifica este valor, la tarea se ejecutará después de enviarse si el tipo de activador es ON_DEMAND o según la programación especificada si el tipo de activador es RECURRING.
|
--trigger-disabled |
Opcional: Evita que se ejecute la tarea. Este parámetro no cancela las tareas que ya se están ejecutando, sino que inhabilita temporalmente las tareas de RECURRING.
|
--trigger-max-retires |
Opcional: Es la cantidad de reintentos antes de anular la operación. Establece el valor en cero para no intentar nunca reintentar una tarea con errores. |
--trigger-schedule |
Programa cron para ejecutar tareas de forma periódica. |
--description |
Opcional: Descripción de la tarea. |
--display-name |
Opcional: Es el nombre visible de la tarea. |
--labels |
Opcional: Lista de pares de etiquetas KEY=VALUE que se agregarán. |
--execution-args |
Opcional: Argumentos para pasar a la tarea. Los argumentos pueden ser una combinación de pares clave-valor. Puedes pasar una lista de pares clave-valor separados por comas como argumentos de ejecución. Para pasar argumentos posicionales, establece la clave en TASK_ARGS y el valor en una cadena separada por comas de todos los argumentos posicionales. Para usar un delimitador que no sea una coma, consulta escape.En caso de que se pasen key-value y argumentos posicionales
juntos, se pasará TASK_ARGS como el último argumento.
|
--execution-service-account |
Es la cuenta de servicio que se usará para ejecutar una tarea. |
--max-job-execution-lifetime |
Opcional: Es la duración máxima antes de que venza la ejecución del trabajo. |
--container-image |
Opcional: Imagen de contenedor personalizada para el entorno de ejecución del trabajo. Si no se especifica, se usará una imagen de contenedor predeterminada. |
--kms-key |
Opcional: Clave de Cloud KMS que se usará para la encriptación, en el siguiente formato:projects/{project_number}/locations/{location_id}/keyRings/{key-ring-name}/cryptoKeys/{key-name}
|
Ejemplo de Java:
glcoud dataplex tasks create --project=<project-name> --location=<location> --lake=<lake-id> --trigger-type=ON_DEMAND –spark-main-jar-file-uri=<gcs location to java file> --execution-service-account=<service-account-email> --trigger-start-time=<timestamp after which job starts ex. 2099-01-01T00:00:00Z> --labels=key1=value1,key2=value3,key3=value3 --execution-args=arg1=value1,arg2=value3,arg3=value3 <task-id>
Ejemplo de PySpark:
gcloud dataplex tasks create --project=<project-name> --location=<location> --lake=<lake-id> --trigger-type=RECURRING --trigger-schedule=<Cron schedule https://en.wikipedia.org/wiki/Cron> --spark-python-script-file=<gcs location to python script> --execution-service-account=<service-account-email> --execution-args=^::^arg1=value1::arg2=value2::TASK_ARGS="pos-arg1, pos-arg2" <task-id>
REST
Para crear una tarea, usa el Explorador de APIs.
Programa una tarea de Spark SQL
gcloud
Para programar una tarea de Spark SQL, ejecuta el mismo comando de gcloud CLI que en Programa una tarea de Spark (Java o Python), con los siguientes parámetros adicionales:
| Parámetro | Descripción |
|---|---|
--spark-sql-script |
Es el texto de la consulta en SQL. Se requiere spark-sql-script o spark-sql-script-file. |
--spark-sql-script-file |
Es una referencia a un archivo de consulta. Este valor puede ser la URI de Cloud Storage del archivo de consulta o la ruta de acceso al contenido de la secuencia de comandos SQL.
Se requiere spark-sql-script o spark-sql-script-file. |
--execution-args |
Para las tareas de Spark SQL, los siguientes argumentos son obligatorios y deben pasarse como argumentos posicionales:--output_location, <GCS uri of the output directory>--output_format, <output file format>.Los formatos compatibles son archivos CSV, archivos JSON, Parquet y ORC. |
gcloud dataplex tasks create --project=<project-name> --location=<location> --lake=<lake-id> --execution-service-account=<service-account-email> --trigger-type=ON_DEMAND --spark-sql-script=<sql-script> --execution-args=^::^TASK_ARGS="--output_location, <gcs folder location>, --output_format, json" <sql-task-id>
REST
Para crear una tarea, usa el Explorador de APIs.
Supervisa tu tarea
Console
En la consola de Google Cloud , ve a la página Proceso de Dataplex Universal Catalog.
En la pestaña Tareas, hay una lista de tareas filtradas por tipos de plantillas de tareas.
En la columna Nombre, haz clic en cualquier tarea que desees ver.
Haz clic en el ID del trabajo de la tarea que quieres ver.
La página de Dataproc se abre en la consola deGoogle Cloud , lo que te permite ver los detalles de supervisión y salida.
gcloud
En la siguiente tabla, se enumeran los comandos de gcloud CLI para supervisar tus tareas.
| Acción | Comando de gcloud CLI |
|---|---|
| Tareas de creación de listas | gcloud dataplex tasks list --project=<project-name> --location=<location> --lake=<lake-id> |
| Cómo ver los detalles de la tarea | gcloud dataplex tasks describe --project=<project-name> --location=<location> --lake=<lake-id> <task-id> |
| Enumera los trabajos de una tarea | gcloud dataplex tasks jobs list --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> |
| Cómo ver los detalles del trabajo | gcloud dataplex tasks jobs describe --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> <job-id> |
Dataplex Universal Catalog ejecuta trabajos en Dataproc Serverless (lotes). Para ver los registros de ejecución de un trabajo de Dataplex Universal Catalog, sigue estos pasos:
Obtén el ID del trabajo de Dataproc Serverless (lotes). Ejecuta el siguiente comando:
gcloud dataplex tasks jobs describe --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> <job-id>Consulta los registros. Ejecuta el siguiente comando con el ID del trabajo que obtuviste al ejecutar el comando anterior:
gcloud beta dataproc batches wait --project=<project-name> --region=<location> <job-id>
REST
Para get o list una tarea o un trabajo, usa el Explorador de APIs.
Administra la programación
En la consola de Google Cloud , dentro de Dataplex Universal Catalog, puedes editar la programación de una tarea, borrar una tarea o cancelar un trabajo en curso. En la siguiente tabla, se enumeran los comandos de gcloud CLI para estas acciones.
| Acción | Comando de gcloud CLI |
|---|---|
| Editar la programación de la tarea | gcloud dataplex tasks update --project=<project-name> --location=<location> --lake=<lake-id> --trigger-schedule=<updated-schedule> <task-id> |
| Cómo borrar una tarea | gcloud dataplex tasks delete --project=<project-name> --location=<location> --lake=<lake-id> <task-id> |
| Cancelar un trabajo | gcloud dataplex tasks jobs cancel --project=<project-name> --location=<location> --lake=<lake-id> --task=<task-id> <job-id> |
¿Qué sigue?
- Consulta Plantillas de Dataproc.
- Prueba una plantilla prediseñada para transferir datos de forma incremental desde los recursos de Cloud Storage de Dataplex Universal Catalog a BigQuery.
- Consulta Cómo configurar alertas y notificaciones para las tareas de Dataplex Universal Catalog.