Administra macros, preferencias y argumentos del entorno de ejecución

En esta página, se explica cómo configurar preferencias, macros y argumentos de tiempo de ejecución en las canalizaciones de Cloud Data Fusion.

Términos clave

Macros
Las macros
son marcadores de posición dentro de la configuración de los complementos de Cloud Data Fusion. Se representan con variables incluidas 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 tiempo de ejecución. Esto permite la configuración dinámica de parámetros, como rutas de acceso a 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, incluido el sistema en sí, 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 las configuraciones que se usan con frecuencia. Los valores predeterminados pueden heredarse en canalizaciones y programas en niveles inferiores, lo que reduce las tareas de configuración repetitivas.
Argumentos de entorno de ejecución
Los argumentos de tiempo de ejecución son pares clave-valor que proporcionan valores para las macros y, potencialmente, anulan las preferencias cuando implementas o ejecutas una canalización. Son altamente personalizables, lo que te permite ajustar la configuración para cada ejecución de la canalización, sin modificar la canalización o las preferencias subyacentes.

Cómo configurar macros

Para usar una macro para el valor de una propiedad del 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 quieras usar una macro y haz clic en la M junto al campo.
  3. Ingresa una clave para la macro. Por ejemplo, en las propiedades del complemento de la fuente de archivo, ingresa la siguiente clave en el campo Formato: ${format.type}.

Establece valores de macro

Establece valores para las macros antes de obtener una vista previa de los datos de una canalización y antes de ejecutarla. Puedes establecer valores de macros en los siguientes lugares:

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

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

  • Primero, Cloud Data Fusion verifica 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 ese configurador.
    • Si no hay un Argument Setter o si hay macros que no están asignadas en el Argument Setter, Cloud Data Fusion usa los valores de los argumentos de tiempo de ejecución de la canalización.
  • Los argumentos del entorno de ejecución heredan macros de las preferencias de la aplicación.
  • Las preferencias de la aplicación heredan macros de las preferencias del espacio 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. En lugar de usar rutas codificadas, puedes usar rutas dinámicas. Por ejemplo, en un complemento de origen de Cloud Storage, puedes reemplazar el valor de la ruta de acceso con 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 de archivo: gs://<BUCKET_NAME>/${folder}/${file.name}.

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

Cómo configurar las preferencias

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

Cómo establecer las preferencias del sistema

Puedes establecer preferencias para el sistema. Dado 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 el 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, aplicaciones y canalizaciones.

Cómo configurar las preferencias de espacio de nombres

Puedes establecer preferencias para espacios de nombres individuales.

Cuando configuras las preferencias de espacio de nombres, se muestran todas las preferencias del sistema heredadas. Cuando configuras las preferencias de 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 Namespaces y selecciona un espacio de nombres para abrir su página de configuración.
  3. Para editar las preferencias heredadas o agregar nuevas, ve a la pestaña Preferences y haz clic en Edit. Se abrirá un diálogo Preferences en el que podrás ingresar una nueva preferencia 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.

Cómo establecer 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 configuras 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, luego, en el menú Espacio de nombres para seleccionar el espacio de nombres en el que deseas agregar preferencias de la aplicación.
  2. Haz clic en Centro de control.
  3. Haz clic en el ícono de llave Establecer preferencias. Aparecerá una lista de todas las preferencias heredadas.
  4. Para editar las preferencias heredadas o agregar nuevas, ve a la pestaña Preferences y haz clic en Edit. Se abrirá un diálogo Preferences en el que podrás ingresar una nueva preferencia 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 la 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 tiempo de ejecución, que puedes editar de forma opcional.

Configura argumentos de tiempo de ejecución

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

Argumentos de 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 List > Configure.

Argumentos de tiempo de ejecución para ejecutar canalizaciones implementadas

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

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

Cómo establecer preferencias de canalización

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

  1. En Cloud Data Fusion Studio, haz clic en List > Deployed 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 Runtime arguments.
  3. En el cuadro de diálogo Argumentos de tiempo 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 de tiempo de ejecución

Puedes establecer preferencias en los siguientes niveles:

  • Preferencias del sistema: Es el nivel más alto en el que puedes establecer preferencias, como los valores predeterminados, para toda la instancia.
  • Preferencias de espacio de nombres: Hereda las preferencias de Preferencias del sistema. Puedes establecer preferencias para un espacio de nombres específico.
  • Preferencias de la aplicación: Hereda las preferencias de Preferencias del espacio de nombres. Pueden ser únicos para aplicaciones individuales (que contienen canalizaciones).
  • Argumentos de 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 propagarán automáticamente en las preferencias del espacio de nombres, las preferencias de la aplicación y los argumentos de tiempo de ejecución.

Si configuras preferencias a nivel del espacio de nombres, aparecerán en la lista de preferencias heredadas en las preferencias de la aplicación. Si una canalización usa una macro definida en una preferencia, los argumentos de tiempo 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 tiempo 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: Configura 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 pertinente, como las preferencias del sistema o las preferencias del espacio de nombres.
    • Cualquier argumento de tiempo de ejecución que proporciones anulará los valores que se asignen a las macros en las preferencias.
    • Cloud Data Fusion resuelve las macros sustituyendo sus valores de los argumentos de tiempo de ejecución (o las preferencias si no se proporciona un argumento de tiempo 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 esta opción, 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 de entorno de ejecución. Cuando ejecutes la canalización, proporciona un argumento de tiempo 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?