Los parámetros de programación son el mecanismo principal en DataWorks para gestionar tareas y configuraciones de forma dinámica. Le permiten usar marcadores de posición variables en su código e inyectar valores dinámicos durante la programación. Esto resuelve el problema de mantener fechas fijas en las tareas periódicas. Además, separa la configuración del código mediante una jerarquía de parámetros de cuatro niveles: espacio de trabajo, flujo de trabajo, contexto de nodo y nivel local del nodo. Esta separación mejora notablemente la flexibilidad, reutilización y adaptabilidad de las tareas en diversos entornos.
Este tema se centra en los orígenes de asignación y la sintaxis de expresiones de los parámetros de programación. Antes de leer este tema, asegúrese de conocer los métodos básicos de configuración descritos en Configure and use scheduling parameters.
Orígenes de los parámetros de programación
Además de usar los parámetros definidos de manera local en un nodo, también puede utilizar parámetros de contexto, de flujo de trabajo y de espacio de trabajo. A continuación se enumeran estos orígenes según su alcance, desde el más restringido hasta el más amplio.
-
Definición a nivel local del nodo (nodo actual)
Los parámetros definidos en el área Scheduling Parameters de la sección Scheduling Configuration se aplican únicamente al nodo actual. Admiten un conjunto amplio de expresiones de parámetros, como se detalla más adelante.
-
Parámetros de contexto (transmitidos entre nodos)
Utilice los parámetros de contexto para recibir los valores de salida de los nodos anteriores. Con esto no solo se transmiten valores, sino que también se establece una dependencia entre los nodos. Use este método cuando el valor de un parámetro deba determinarse de forma dinámica a partir del resultado de una tarea anterior. Para agregar rápidamente un parámetro de contexto, haga clic en el icono
en el área de asignación de parámetros. Para obtener más información, consulte Configure and use node context parameters . -
Parámetros de flujo de trabajo (compartidos dentro de un flujo de trabajo)
Los parámetros definidos a nivel de flujo de trabajo están disponibles para todos los nodos dentro de ese flujo de trabajo. Puede hacer referencia a ellos directamente con el formato ${workflow.Parameter name}. Las reglas de expresiones de parámetros descritas en este tema también aplican a los parámetros de flujo de trabajo.
-
Parámetros de espacio de trabajo (compartidos dentro de un espacio de trabajo)
Los parámetros de espacio de trabajo son parámetros globales definidos a nivel de espacio de trabajo, por lo que están disponibles para todos los nodos dentro de dicho espacio. Su uso más común es diferenciar las configuraciones entre los entornos de desarrollo y producción. Por ejemplo, puede definir un parámetro llamado
db_namecon el valordb_deven el entorno de desarrollo ydb_proden el entorno de producción. Al establecer el valor de un parámetro de programación, seleccione directamente Workspace Parameters . Para obtener más detalles, consulte Use workspace parameters .
Expresiones de parámetros
Los parámetros de programación definen la lógica de asignación mediante un nombre de parámetro y un valor de parámetro. El valor del parámetro admite varias formas, incluidos los parámetros de tiempo, los parámetros de sistema integrados y las constantes. Una vez definidos los parámetros, puede hacer referencia a ellos en su código con el formato ${parameter name}.
Parámetros de tiempo personalizados: Como
${...}y$[...], que le permiten transformar valores a partir de dos referencias de tiempo (fecha de negocio y hora programada). Para obtener más detalles, consulte Time parameters.Parámetros de sistema integrados: Como $bizdate, $bizmonth y $jobid, que sirven para recuperar la fecha de negocio, el mes de negocio, el identificador del flujo de trabajo, entre otros datos. No se limitan a valores relacionados con el tiempo. Para obtener más detalles, consulte Built-in scheduling parameters.
Constantes: Como '
123','abc', etcétera.
Entre estas opciones, los parámetros de tiempo representan el caso de uso principal de los parámetros de programación. Se utilizan para reemplazar de forma dinámica diversas cadenas de texto de tiempo cuando se ejecutan las tareas.
Parámetros de tiempo
Concepto central: referencia de tiempo
Todos los parámetros de tiempo dinámicos en DataWorks se basan en a continuación dos referencias de tiempo centrales.
|
Concepto |
Definición |
Valor del parámetro |
Formato personalizado |
Precisión de tiempo |
|
Fecha de negocio |
Por lo general, se refiere al día anterior a la fecha de ejecución programada de una tarea. En escenarios de cómputo por lotes T+1, representa la fecha en la que se generaron los datos de negocio. Por ejemplo, si hoy ejecuta una tarea para calcular los ingresos del día anterior, ese día previo —la fecha en la que ocurrieron las transacciones— es la fecha de negocio. |
|
|
Año, mes, día |
|
Hora programada |
Se refiere a la hora configurada en la sección Scheduling Settings de un nodo mediante cron expression. Durante la ejecución de la tarea, se reemplaza por el día en que está programada la instancia de la tarea. Su precisión llega hasta el segundo y es independiente de la hora real de ejecución. Esta hora representa el momento esperado de ejecución de la tarea, el cual podría no coincidir exactamente con la hora de inicio real. Varios factores afectan la hora de inicio real. |
|
|
Año, mes, día, hora, minuto, segundo |
Resumen:
Fecha de negocio ≈ ayer (la fecha de los datos) =
$bizdate=${yyyymmdd}Hora programada ≈ hoy (la hora en que se ejecuta la tarea) =
$cyctime=$[yyyymmddhh24miss]
Una tarea T+1 típica funciona de la siguiente manera: durante las primeras horas de hoy (hora programada), se activa una tarea para procesar los datos de ayer (fecha de negocio).
Si el valor de retorno predeterminado del parámetro de tiempo base no cumple con sus requisitos, personalice los parámetros de tiempo mediante ${...} y $[...]. Los parámetros de tiempo personalizados se derivan de la transformación de estas dos referencias de tiempo base. Se admiten a continuación métodos:
Cuando asigne valores a los parámetros de programación mediante expresiones personalizadas, asegúrese de distinguir entre los dos formatos de corchetes: {...} y [...]. Cada formato utiliza una referencia de tiempo base distinta y devuelve valores completamente diferentes. Si los confunde, podrían generarse errores en los datos de producción.
Parámetros de tiempo personalizados
DataWorks admite el uso de ${...} y $[...] para obtener la fecha de negocio y la hora programada, respectivamente. Los siguientes tipos de transformación le permiten modificar los valores de tiempo de forma flexible para cumplir con sus requisitos de negocio. En estos ejemplos se asume una programación diaria con una hora programada de 02:30:45 y una fecha de negocio de 20251031. Las referencias de tiempo base son:
Fecha de negocio: ${yyyymmdd}, por ejemplo, 20251031.
-
Hora programada: $[yyyymmddhh24miss], por ejemplo, 20251101023045.
ImportanteLa hora programada es el momento de programación preestablecido, el cual queda fijo cuando se genera la instancia de la tarea. Si una instancia se retrasa debido a restricciones de recursos o al estado de los nodos anteriores, la hora programada no cambia según la hora de ejecución real de la instancia.
${...} frente a $[...]: diferencias clave
Primero, comprenda las diferencias clave entre ambos. ${...} y $[...] difieren fundamentalmente en sus referencias de tiempo y capacidades de cálculo. Si combina estos dos formatos, podrían producirse errores en los datos.
|
Dimensión |
|
|
|
Referencia de tiempo |
Fecha de negocio (T-1) |
Hora programada (T) |
|
Precisión de tiempo |
Día (año, mes, día) |
Segundo (año, mes, día, hora, minuto, segundo) |
|
Capacidad de cálculo de desplazamiento |
Admite cálculos de desplazamiento para año, mes, semana y día. |
Admite cálculos de desplazamiento para día, hora y minuto. |
|
Limitación principal |
No admite formato ni cálculos de desplazamiento para unidades de tiempo más pequeñas como hora, minuto y segundo. |
No admite el uso de la sintaxis |
|
Equivalente predeterminado |
|
|
Formato de tiempo
Utilice llaves ${...} o corchetes $[...], combinados con yyyy, yy, mm y dd en combinaciones personalizadas, para generar parámetros de tiempo que obtengan fechas un número determinado de años, meses o días antes o después de la fecha de negocio.
|
Código |
Descripción |
|
|
||
|
Asignación |
Resultado |
Asignación |
Resultado |
||
|
|
Año de 4 dígitos |
|
|
|
|
|
|
Mes de 2 dígitos |
|
|
|
|
|
|
Día de 2 dígitos |
|
|
|
|
|
|
Hora en formato de 24 horas |
No compatible (precisión a nivel de día) |
- |
|
|
|
|
Hora en formato de 12 horas |
- |
|
|
|
|
|
Minuto |
- |
|
|
|
|
|
Segundo |
- |
|
|
|
|
|
Año y mes |
|
|
|
|
|
|
Con formato que usa guion bajo como delimitador |
|
|
|
|
|
|
Con formato que usa guiones como delimitadores |
|
|
|
|
|
|
Con formato que incluye guiones, horas, minutos y segundos |
No compatible (precisión a nivel de día) |
- |
Para conocer el método compatible, consulte String concatenation: Method 2. |
|
Cálculo de desplazamiento
El cálculo de desplazamiento es el núcleo de los parámetros dinámicos. Puede sumar o restar valores a la fecha de negocio o a la hora programada para obtener fechas y horas N años, meses, días, horas o minutos antes o después de la hora base (las horas y los minutos solo son compatibles con la hora programada). ${...} y $[...] admiten rangos distintos debido a la diferente precisión de sus referencias de tiempo base.
-
Cálculo de desplazamiento con
${...}-
Capacidad principal: admite desplazamientos enteros para año, mes, semana y día.
ImportanteNo admite cálculos de desplazamiento por hora ni por minuto. No se admiten expresiones como ${yyyy-mm-dd-1/24}.
-
Sintaxis:
${<time format><±N>}, donde N corresponde a la unidad más pequeña del formato de tiempo. Por ejemplo, si el formato es yyyymm, N representa meses. Si el formato es yyyymmdd, N representa días.Periodo de desplazamiento de fecha
Unidad de desplazamiento
Sintaxis
Ejemplo
N años antes/después
Año
${yyyy±N}o${yy±N}Obtener el año anterior:
${yyyy-1}N meses antes/después
Mes
${yyyymm±N}
Obtener el mes anterior:
${yyyymm-1}N semanas antes/después
Semana
${yyyymmdd±7*N}
Obtener la semana anterior:
${yyyymmdd-7*1}N días antes/después
Día
${yyyymmdd±N}
Obtener el día de antes de ayer:
${yyyymmdd-1}
-
-
Cálculo de desplazamiento con
$[...]-
Capacidad principal: admite desplazamientos fraccionarios para día, hora y minuto.
Importante$[...]no permite usar el formato de tiempo$[yyyy-N]o$[mm-N]para obtener fechas de hace N años o N meses. Para efectuar cálculos de desplazamiento por año o mes, utilice la funciónadd_months. -
Sintaxis:
$[<time format><±N>], donde se usa N/24 para desplazamientos por hora y N/24/60 para desplazamientos por minuto. N es la cantidad de horas o minutos que se van a desplazar.Requisito
Unidad de desplazamiento
Sintaxis
Ejemplo
N años antes/después
Año
$[add_months(yyyymmdd,12N)](N años después)$[add_months(yyyymmdd,-12N)](N años antes)Obtener el año anterior:
$[add_months(yyyymmdd,-12)]N meses antes/después
Mes
$[add_months(yyyymmdd,N)](N meses después)$[add_months(yyyymmdd,-N)](N meses antes)Obtener el mes anterior:
$[add_months(yyyymmdd,-1)]
Obtener el mes siguiente:$[add_months(yyyy_mm,1)]N semanas antes/después
Semana
$[yyyymmdd±7*N]Obtener la semana anterior:
$[yyyymmdd±7*1]N días antes/después
Día
$[yyyymmdd±N]Obtener el día de ayer:
$[yyyymmdd-1]N horas antes/después
Hora
Puede obtener estos datos de tiempo con a continuación métodos:
-
$[hh24miss±N/24],$[hh24±N/24] -
$[custom time format±N/24]
Obtener la hora anterior con distintos formatos de tiempo:
-
Obtener el mes:
$[mm-1/24]. -
Obtener el año:
$[yyyy-1/24]. -
Obtener el año y el mes:
$[yyyymm-1/24]. -
Obtener el año, el mes y el día:
$[yyyymmdd-1/24]. -
Obtener el día y la hora anteriores:
$[yyyymmdd-1-1/24]
N minutos antes/después
Minuto
Puede obtener estos datos de tiempo con a continuación métodos:
-
$[hh24miss±N/24/60] -
$[yyyymmddhh24miss±N/24/60] -
$[mi±N/24/60] -
$[custom time format±N/24/60]
Obtener 15 minutos antes de la hora programada con distintos formatos de tiempo:
-
$[yyyy-15/24/60] -
$[yyyymm-15/24/60] -
$[yyyymmdd-15/24/60] -
$[hh24-15/24/60] -
$[mi-15/24/60]
Desplazamiento combinado complejo
Día + Hora
$[yyyymmdd±N±M/24], donde N es el desplazamiento en días y M es el desplazamiento en horas.Ejemplo: obtener un día y una hora antes →
$[yyyymmdd-1-1/24]NotaAl ejecutar cálculos de desplazamiento por hora o minuto, podría cruzarse el límite del día. Para saber cómo manejan los parámetros este cruce de límite, consulte Handle day boundary crossing in time parameters.
Cuando ejecute un cálculo de desplazamiento mensual sobre una fecha de fin de mes, si el mes de destino no tiene el día correspondiente, el resultado se ajustará automáticamente al último día de ese mes. Por ejemplo, si la fecha actual es 2025-03-31 y se aplica un desplazamiento de un mes hacia atrás, el resultado será 2025-02-28 porque febrero no tiene día 31.
-
-
Transformación secundaria mediante funciones del motor
Cuando el formato y el desplazamiento integrados de los parámetros de programación no generan directamente el valor deseado (como el último día del mes anterior), utilice las funciones integradas del motor de cómputo del nodo de destino o un nodo de asignación para aplicar transformaciones secundarias a los parámetros de tiempo al invocarlos.
Para obtener más información, consulte Perform secondary transformation using engine functions .
Concatenación de cadenas
Utilice este método para construir cadenas de fecha con patrones que la sintaxis integrada no admite. Combina la parte de la fecha generada por los parámetros de programación con cadenas constantes fijas.
Ejemplo 1: obtener dinámicamente el primer día de cada mes.
Escenario: sin importar el día en que se ejecute la tarea, necesita una cadena que represente el primer día del mes actual con el formato
yyyymm01.-
Implementación:
Extraiga el año y el mes: utilice
${yyyymm}para obtener el año y el mes de la fecha de negocio actual (por ejemplo, si la fecha de negocio es20231027, el resultado es202310).Concatene la constante: concatene el año y el mes extraídos con la cadena
'01'.Llamada al parámetro:
first_day_of_month=${yyyymm}01
Resultado: cuando se ejecuta la tarea,
${first_day_of_month}se reemplaza por20231001.
Ejemplo 2: obtener la hora en formato yyyy-mm-dd hh24:mi:ss.
Escenario: obtener una cadena de tiempo en formato
yyyy-mm-dd hh24:mi:ss, como2023-11-01 02:30:45.-
Implementación:
Defina dos parámetros:
datetime1ydatetime2, y asígnelesdatetime1=$[yyyy-mm-dd]ydatetime2=$[hh24:mi:ss-1/24/60].Concatene los parámetros: combine
datetime1ydatetime2con un espacio.Llamada al parámetro: pt=
${datetime1}${datetime2}.
Resultado: cuando se ejecuta la tarea,
${datetime1}${datetime2}se reemplaza por2023-11-01 02:30:45.
Parámetros de programación integrados
DataWorks admite los siguientes parámetros de sistema integrados, que se pueden usar como valores de parámetros de programación. Sin embargo, este enfoque es menos flexible porque el formato de hora es fijo. Se recomienda utilizar parámetros de hora personalizados, ya que admiten transformaciones flexibles.
|
Parámetro integrado |
Definición |
|
$bizdate |
La fecha de negocio, con el formato Este parámetro se usa ampliamente. En la programación diaria, la fecha de negocio toma de forma predeterminada el día anterior a la fecha de ejecución esperada de la tarea. |
|
$cyctime |
La hora programada de la tarea, con el formato |
|
$gmtdate |
La fecha actual, con el formato Este parámetro toma de forma predeterminada la fecha actual. Cuando se rellenan datos, la fecha de entrada es |
|
$bizmonth |
El mes de negocio, con el formato
|
|
$jobid |
El ID del flujo de trabajo al que pertenece la tarea. |
|
$nodeid |
El ID del nodo. |
|
$taskid |
El ID de instancia que genera el nodo. |
Apéndice
Sustitución de parámetros durante el relleno de datos
Después de enviar una tarea a Operation Center, puede backfill data para generar y ejecutar por lotes instancias históricas de tareas dentro de un intervalo de fechas especificado, con fines de reparación de datos, relleno o análisis retrospectivo.
Fecha de negocio ($bizdate): Durante el relleno de datos, la fecha de negocio que seleccione coincide con el resultado de sustitución de $bizdate. Si el parámetro de programación utiliza el formato personalizado
${...}, la hora base es la fecha seleccionada, la cual se transforma después según la expresión de tiempo especificada.-
Hora programada ($cyctime): Durante el relleno de datos, el resultado de sustitución de $cyctime corresponde al día
the selected business date + 1.Por ejemplo, si la fecha de negocio seleccionada para el relleno de datos es
20250315, el resultado de sustitución del parámetro$cyctimeserá20250316000000. Si el parámetro de programación utiliza el formato$[...], la hora base es la fecha de negocio seleccionada más 1, la cual se transforma después según la expresión de tiempo especificada.
Relación entre los parámetros de programación, la fecha de negocio, la hora programada y la hora de ejecución real
|
Tipo de relación |
Descripción y ejemplo |
|
Relación entre los parámetros de programación y la hora de ejecución real. |
Los valores de sustitución de los parámetros de programación se determinan cuando se generan las instancias. Por lo tanto, estos valores no cambian con la hora de ejecución real de la instancia. |
|
Relación entre los parámetros de programación y la hora programada. |
Cuando un parámetro de programación se establece en Por ejemplo, si el nodo actual tiene programación horaria, con un intervalo de hora programada de
|
|
Relación entre los parámetros de programación, la fecha de negocio y la hora programada. |
|
Notas sobre el horario de verano
DataWorks garantiza que las tareas se ejecuten correctamente los días en que inicia y termina el horario de verano (DST). Para obtener detalles sobre cómo el producto gestiona las transiciones de DST, consulte Daylight saving time. Para evitar complejidad adicional en la ejecución de sus tareas debido a estas transiciones, se recomienda revisar este documento si su región aplica el horario de verano.
Comparación de valores de parámetros personalizados
Esta sección utiliza un nodo ODPS SQL como ejemplo. Si se asume que la hora programada de la tarea es July 20, 2025 10:30:00, la siguiente tabla muestra las configuraciones de valores de tiempo para los parámetros ${…} y $[…].
|
Valor de tiempo |
Parámetro ${…} |
Parámetro $[…] |
|
Obtener año: 2025 |
|
|
|
Obtener año: 25 |
|
|
|
Obtener año: 2024 |
|
|
|
Obtener mes: 07 |
|
|
|
Obtener día: 20 |
|
|
|
Obtener fecha: 20 de junio de 2025 |
Importante
Este enfoque requiere considerar la cantidad de días de cada mes, por lo que no se recomienda. Se sugiere utilizar el formato |
|
|
Obtener fecha: 19 de julio de 2025 |
|
|
|
Obtener fecha: 20 de julio de 2024 |
Importante
Este enfoque requiere considerar los años bisiestos, por lo que no se recomienda. Se sugiere utilizar el formato |
|
|
Obtener hora: 10:30:00 |
No compatible |
|
|
Obtener hora: 2025-07-20 10:30:00 |
No compatible |
|
|
Obtener hora: 2025-07-20 10:29:00 |
No compatible |
|
|
Obtener hora: 2025-07-20 09:30:00 |
No compatible |
|
|
Obtener la hora del día anterior, con precisión de segundos y sin espacio entre la fecha y la hora: 2025071910:30:00 |
No compatible |
|
|
Obtener la hora del día anterior, con precisión de segundos y un espacio entre la fecha y la hora: 20250719 10:30:00 |
No compatible |
|