Administra macros, preferencias y argumentos de tiempo de ejecución

Las macros, las preferencias y los argumentos de entorno de ejecución de Cloud Data Fusion te permiten parametrizar canalizaciones de forma dinámica y crear plantillas reutilizables. Puedes establecer parámetros de configuración predeterminados jerárquicos en tus entornos y anular los valores de configuración cuando obtengas una vista previa de una canalización o la ejecutes.

Términos clave

Macros
Las macros son marcadores de posición dentro de las configuraciones de los complementos de Cloud Data Fusion. Se representan con variables encerradas entre ${ }, como ${input_file_path}. Las macros introducen flexibilidad en tus canalizaciones, ya que te permiten usar valores de marcador de posición, que se reemplazan por valores reales en el entorno de ejecución. Esto habilita la configuración dinámica de parámetros, como rutas de acceso de archivos y nombres de tablas.
Preferencias
Las preferencias son parámetros de configuración predefinidos que se aplican en varios niveles dentro de Cloud Data Fusion, incluidos el sistema, los espacios de nombres, las aplicaciones (que contienen canalizaciones) y los programas individuales dentro de las canalizaciones. Las preferencias te permiten establecer valores predeterminados para los parámetros de configuración de uso frecuente. Las canalizaciones y los programas pueden heredar los valores predeterminados en niveles inferiores, lo que reduce las tareas de configuración repetitivas.
Argumentos del entorno de ejecución
Los argumentos de entorno de ejecución son pares clave-valor que proporcionan valores para las macros y, posiblemente, anulan las preferencias cuando implementas o ejecutas una canalización. Son muy personalizables, lo que te permite ajustar los parámetros de configuración en cada ejecución de la canalización, sin modificar la canalización ni las preferencias subyacentes.

Configura macros

Para usar una macro para el valor de una propiedad de complemento, sigue estos pasos:

  1. En Cloud Data Fusion Studio, ve al nodo del complemento y haz clic en Propiedades.
  2. Ve al campo en el que deseas usar una macro y haz clic en la M que se encuentra junto al campo.
  3. Ingresa una clave para la macro. Por ejemplo, en las propiedades del complemento de la fuente de archivos, ingresa la siguiente clave en el campo Formato: ${format.type}.

Configura valores de macros

Se deben establecer valores para las macros antes de obtener una vista previa de los datos de la canalización y antes de ejecutarla. Se pueden establecer valores de macro en los siguientes lugares:

  • Complementos de Argument Setter
  • Argumentos del entorno de ejecución
  • Preferencias de aplicación
  • Preferencias de espacio de nombres
  • Preferencias del sistema

Cuando ejecutas una canalización con macros, ocurre lo siguiente:

  • Cloud Data Fusion primero comprueba si la canalización incluye un complemento de configuración de argumentos:
    • Si tiene un configurador de argumentos, Cloud Data Fusion usa los valores de las macros de este.
    • Si no hay un configurador de argumentos o si hay macros que no están asignadas en el configurador de argumentos, Cloud Data Fusion usa los valores en los argumentos de ejecución de la canalización.
  • Los argumentos del entorno de ejecución heredan macros de las preferencias de aplicación.
  • Las preferencias de aplicación heredan macros de las preferencias de espacios de nombres.
  • Las preferencias de espacio de nombres heredan macros de las preferencias del sistema.

Ejemplos

Un uso común de las macros es en los campos de ruta de acceso. En lugar de usar rutas hard-coded, puedes usar rutas dinámicas. Por ejemplo, en un complemento de origen de Cloud Storage, puedes reemplazar el valor de la ruta de acceso por varias macros. El siguiente valor divide los elementos de bucket, carpeta y archivo: gs://${bucket.name}/${folder}/${file.name}.

En el siguiente ejemplo, se cargan datos de un bucket estático y un archivo con un nombre que no es estático. Ingresa el nombre del bucket y usa una macro para el nombre del archivo: gs://<BUCKET_NAME>/${folder}/${file.name}.

Para obtener más información, consulta Macros y funciones de macros.

Configura las preferencias

En la siguiente sección, se describe la jerarquía de preferencias, en la que se establecen, heredan o anulan las preferencias.

Establece las preferencias del sistema

Puedes establecer preferencias para el sistema. Debido a que los nombres de las macros deben ser únicos, cada preferencia se aplica a todas las canalizaciones que usan esa macro.

Por ejemplo, tienes una canalización con una fuente de base de datos y usas macros para el nombre de la base de datos y el nombre de usuario. Puedes establecer las preferencias de la base de datos y del nombre de usuario en las preferencias del sistema. Cada espacio de nombres y cada canalización de esa instancia heredan esas preferencias.

Para establecer las preferencias del sistema, sigue estos pasos:

  1. En Cloud Data Fusion Studio, haz clic en Administrador del sistema > Configuración.
  2. Haz clic en Preferencias del sistema > Editar preferencias del sistema.
  3. En el cuadro de diálogo Preferencias, ingresa preferencias nuevas o edita las existentes.
  4. Haz clic en Guardar y cerrar. Estas preferencias están disponibles en todos los espacios de nombres, las aplicaciones y las canalizaciones.

Establece las preferencias de espacio de nombres

Puedes establecer preferencias para espacios de nombres individuales.

Cuando configuras las preferencias de espacio de nombres, se muestran las preferencias del sistema heredadas. Cuando estableces preferencias para un espacio de nombres, puedes anular las preferencias heredadas estableciendo valores diferentes. También puedes agregar nuevas preferencias de espacio de nombres.

Para establecer las preferencias de espacio de nombres, sigue estos pasos:

  1. En Cloud Data Fusion Studio, haz clic en Administrador del sistema > Configuración.
  2. Haz clic en Espacios de nombres y selecciona un espacio de nombres para abrir su página de configuración.
  3. Para editar las preferencias heredadas o agregar preferencias nuevas, ve a la pestaña Preferencias y haz clic en Editar. Se abrirá un diálogo de Preferences, en el que podrás ingresar una preferencia nueva o anular las preferencias del sistema heredadas. Haz clic en Agregar y, luego, ingresa la clave y el valor nuevo de la macro.
  4. Haz clic en Guardar y cerrar. La preferencia de espacio de nombres se crea con el valor nuevo, que tiene prioridad sobre la preferencia del sistema.

Establece las preferencias de la aplicación

Puedes establecer preferencias para cada canalización implementada en un espacio de nombres. Cuando configuras las preferencias de la aplicación, aparecen las preferencias heredadas del sistema y del espacio de nombres. Cuando estableces las preferencias de una aplicación, puedes anular las preferencias heredadas estableciendo valores diferentes o agregar preferencias nuevas para la aplicación:

  1. En Cloud Data Fusion Studio, haz clic en y en el menú Espacio de nombres para seleccionar el espacio de nombres en el que deseas agregar las preferencias de la aplicación.
  2. Haz clic en Centro de control.
  3. Haz clic en el ícono de llave inglesa Establecer preferencias. Aparecerá una lista de todas las preferencias heredadas.
  4. Para editar las preferencias heredadas o agregar preferencias nuevas, ve a la pestaña Preferencias y haz clic en Editar. Se abrirá un diálogo de Preferences, en el que podrás ingresar una preferencia nueva o anular las preferencias del sistema heredadas. Haz clic en Agregar y, luego, ingresa la clave y el valor nuevo de la macro.
  5. Haz clic en Guardar y cerrar. La preferencia de aplicación se crea con el valor nuevo, que anula las preferencias del sistema o del espacio de nombres. Cuando ejecutas la canalización implementada, las preferencias de la aplicación aparecen como argumentos de entorno de ejecución, que puedes editar de forma opcional.

Configura los argumentos del entorno de ejecución

Configura argumentos del entorno de ejecución para proporcionar valores para las macros y, posiblemente, anular las preferencias cuando implementes o ejecutes una canalización.

Argumentos del entorno de ejecución para obtener una vista previa de los datos

Para establecer los valores de cada macro en la canalización cuando obtienes una vista previa de los datos en Cloud Data Fusion Studio, haz clic en Lista > Configurar.

Argumentos del entorno de ejecución para ejecutar canalizaciones implementadas

Si una canalización incluye macros, después de implementarla, debes agregar argumentos del entorno de ejecución, que establecen los valores de las macros.

Cuando implementes una canalización con macros, haz clic en el menú desplegable junto a Ejecutar para abrir el diálogo Argumentos del entorno de ejecución y establecer los valores para cada macro.

Establece las preferencias de la canalización

Para establecer las preferencias de una canalización, sigue estos pasos:

  1. En Cloud Data Fusion Studio, haz clic en Lista > Implementada y selecciona una canalización implementada para verla.
  2. En el lienzo de la canalización, haz clic en el menú desplegable junto a Ejecutar. Se abrirá el diálogo Argumentos del entorno de ejecución.
  3. En el diálogo Argumentos del entorno de ejecución que se abre, especifica el valor de cada macro en la canalización.

Descripción general de las preferencias, las macros y los argumentos del entorno de ejecución

Puedes configurar las preferencias en los siguientes niveles:

  • Preferencias del sistema: Es el nivel más alto en el que estableces las preferencias, como los valores predeterminados, para toda la instancia.
  • Preferencias de espacio de nombres: hereda las preferencias de las preferencias del sistema. Puedes establecer preferencias para un espacio de nombres específico.
  • Preferencias de la aplicación: Hereda las preferencias de las preferencias del espacio de nombres. Pueden ser únicos para aplicaciones individuales (que contienen canalizaciones).
  • Argumentos del entorno de ejecución: Son pares clave-valor que anulan las preferencias en niveles superiores.

Si estableces una preferencia a nivel de las preferencias del sistema, los valores de las macros se propagan automáticamente en las preferencias de espacios de nombres, las preferencias de aplicación y los argumentos del entorno de ejecución.

Si estableces preferencias a nivel del espacio de nombres, estas aparecerán en la lista de preferencias heredadas en las preferencias de la aplicación. Si una canalización usa una macro que se define en una preferencia, los argumentos de entorno de ejecución usan el par clave-valor definido en la preferencia. Puedes anular los valores de las preferencias en cada nivel de preferencia y en los argumentos de entorno de ejecución.

Usa preferencias, macros y argumentos de entorno de ejecución para los siguientes casos de uso:

  • Desarrolla una canalización. Incorpora macros donde necesites valores dinámicos para las propiedades del complemento.
  • Opcional: Establece las preferencias. Establece valores predeterminados para las macros en las preferencias en varios niveles.
  • Implementa y ejecuta una canalización. Cuando ejecutas una canalización, sucede lo siguiente:
    • Se aplican las preferencias para el nivel correspondiente, como las preferencias del sistema o las preferencias de espacios de nombres.
    • Cualquier argumento de entorno de ejecución que proporciones anulará los valores que se asignan a las macros en las preferencias.
    • Cloud Data Fusion resuelve las macros sustituyendo sus valores de los argumentos del entorno de ejecución (o las preferencias si no se proporciona un argumento del entorno de ejecución).

Ejemplo

Una canalización tiene un receptor de BigQuery que tiene un valor de nombre de tabla que debe cambiar de forma dinámica. Para configurar esto, haz lo siguiente:

  1. Configura la macro. En las propiedades del receptor, usa la siguiente macro en el campo Nombre de la tabla: ${output_table}.
  2. Establece la preferencia. En las preferencias de la aplicación, establece una preferencia para ${output_table} con el siguiente valor predeterminado: data_staging.
  3. Establece el argumento del entorno de ejecución. Cuando ejecutes la canalización, proporciona un argumento de entorno de ejecución, por ejemplo, output_table=final_analytics_data.

Durante la ejecución de la canalización, la macro ${output_table}, se reemplaza por final_analytics_data.

¿Qué sigue?