¿Qué es una referencia de valores dinámicos?

Las referencias de valores dinámicos describen una colección de variables disponibles al configurar trabajos y tareas. Use referencias de valores dinámicos para configurar instrucciones condicionales para tareas o para pasar información como parámetros o argumentos.

Las referencias de valores dinámicos incluyen información como:

• Valores configurados para el trabajo, incluidos el nombre del trabajo, los nombres de tarea y el tipo de desencadenador.
• Metadatos generados sobre el trabajo, incluido el identificador de trabajo, el identificador de ejecución y la hora de inicio de la ejecución del trabajo.
• Información sobre cuántos intentos de reparación ha realizado un trabajo o reintento una tarea se ha ejecutado.
• Estado de resultado de una tarea especificada.
• Valores configurados mediante parámetros de trabajo, parámetros de tarea o conjuntos mediante valores de tarea.

Uso de referencias de valores dinámicos

Use referencias de valores dinámicos al configurar trabajos o tareas. No puede hacer referencia directamente a referencias de valores dinámicos de recursos configurados mediante tareas como cuadernos, consultas o JAR. Las referencias de valores dinámicos deben definirse mediante parámetros o campos que pasan contexto a tareas.

Las referencias de valores dinámicos usan llaves ({{ }}). Cuando se ejecuta un trabajo o una tarea, un literal de cadena reemplaza la referencia de valores dinámicos. Por ejemplo, si configura el siguiente par clave-valor como parámetro de tarea:

{"job_run_id": "job_{{job.run_id}}"}

Si el identificador de ejecución es 550315892394120, el valor de job_run_id se evalúa como job_550315892394120.

Nota:

El contenido entre llaves dobles no se evalúa como una expresión. No se pueden ejecutar operaciones ni funciones en llaves dobles.

Los identificadores de valor proporcionados por el usuario admiten caracteres alfanuméricos y de subrayado. Teclas de escape que contienen caracteres especiales rodeando el identificador con marcas de seguridad (` `).

Los errores de sintaxis, incluidos los valores de referencia dinámicos inexistentes y las llaves que faltan, se omiten silenciosamente y se tratan como cadenas literales. Se muestra un mensaje de error si proporciona una referencia no válida que pertenece a un espacio de nombres conocido, por ejemplo, {{job.notebook_url}}.

Uso de referencias de valores dinámicos en la interfaz de usuario de trabajos

Los campos que aceptan referencias de valores dinámicos proporcionan un acceso directo para insertar referencias de valores dinámicos disponibles. Haga clic en { } para ver esta lista e insertarla en el campo proporcionado.

Nota:

La interfaz de usuario no completa automáticamente las claves para hacer referencia a los valores de la tarea.

Muchos campos que aceptan referencias de valores dinámicos requieren formato adicional para usarlos correctamente. Consulte Configure task parameters (Configuración de parámetros de tarea).

Uso de referencias de valores dinámicos en un JSON del trabajo

Use la sintaxis {{ }} para usar valores dinámicos en definiciones de JSON de trabajo usadas por la CLI de Databricks y la API de REST.

Los parámetros de trabajo y tarea tienen una sintaxis diferente y la sintaxis de parámetros de tarea varía según el tipo de tarea.

En el ejemplo siguiente se muestra la sintaxis JSON parcial para configurar parámetros de trabajo mediante referencias de valores dinámicos:

{
  "parameters": [
    {
      "name": "my_job_id",
      "default": "{{job.id}}"
    },
    {
      "name": "run_date",
      "default": "{{job.start_time.iso_date}}"
    }
  ]
}

En el ejemplo siguiente se muestra la sintaxis JSON parcial para configurar parámetros de tarea de cuaderno mediante una referencia de valores dinámicos:

{
  "notebook_task": {
    "base_parameters": {
      "workspace_id": "workspace_{{workspace.id}}",
      "file_arrival_location": "{{job.trigger.file_arrival.location}}"
    }
  }
}

Revisión de los parámetros de una ejecución de trabajo

Una vez que se completa una tarea, puede ver los valores resueltos de los parámetros en Parámetros en la página de detalles de la ejecución. Consulte Visualización de los detalles de ejecución de trabajos.

Referencias de valor admitidas

Se admiten las siguientes referencias de valor dinámico:

Referencia	Descripción
{{job.id}}	Identificador único asignado al trabajo.
{{job.name}}	Nombre del trabajo en el momento de la ejecución del trabajo.
{{job.run_id}}	Identificador único asignado a la ejecución del trabajo.
{{job.repair_count}}	Número de intentos de reparación en la ejecución del trabajo actual.
{{job.start_time.<argument>}}	Valor basado en la hora (en la zona horaria UTC) a la que se ha iniciado la ejecución del trabajo. El valor devuelto se basa en la opción argument. Vea Opciones para los valores de fecha y hora.
{{job.parameters.<name>}}	Valor del parámetro de nivel de trabajo con la clave <name>.
{{job.trigger.type}}	Tipo de desencadenador de la ejecución del trabajo. Los valores posibles son: periodic, one_time, run_job_task, file_arrival, continuous y table.
{{job.trigger.file_arrival.location}}	Si se configura un desencadenador de llegada de archivos para este trabajo, el valor de la ubicación de almacenamiento.
{{job.trigger.time.<argument>}}	Valor basado en la hora (en la zona horaria UTC) a la que se ha desencadenado la ejecución del trabajo, redondeado al minuto más cercano para los trabajos con una programación cron. El valor devuelto se basa en la opción argument. Vea Opciones para los valores de fecha y hora.
{{task.name}}	Nombre de la tarea actual.
{{task.run_id}}	Identificador único de la ejecución de la tarea actual.
{{task.execution_count}}	Número de veces que se ha ejecutado la tarea actual (incluidos reintentos y reparaciones).
{{task.notebook_path}}	Ruta de acceso de la tarea del cuaderno actual.
{{tasks.<task_name>.run_id}}	Identificador único asignado a la ejecución de tarea para <task_name>.
{{tasks.<task_name>.result_state}}	El estado de resultado de la tarea <task_name>. Los valores posibles son success, failed, excluded, canceled, evicted, timedout, upstream_canceled, upstream_evicted y upstream_failed.
{{tasks.<task_name>.error_code}}	El código de error de la tarea <task_name> si se produjo un error al ejecutarla. Algunos ejemplos de valores posibles son RunExecutionError, ResourceNotFound y UnauthorizedError. Para las tareas correctas, esto se evalúa como una cadena vacía.
{{tasks.<task_name>.execution_count}}	Número de veces que se ha ejecutado la tarea <task_name> (incluidos reintentos y reparaciones).
{{tasks.<task_name>.notebook_path}}	Ruta de acceso al cuaderno de la tarea de cuaderno <task_name>.
{{tasks.<task_name>.values.<value_name>}}	Valor de tarea con la clave <value_name> que ha establecido la tarea <task_name>.
{{workspace.id}}	Identificador único asignado al área de trabajo.
{{workspace.url}}	URL del área de trabajo.

Puede establecer estas referencias con cualquier tarea. Consulte Configure task parameters (Configuración de parámetros de tarea).

También puede pasar parámetros entre tareas de un trabajo con valores de tarea. Consulte Use task values to pass information between tasks (Uso de valores de tareas para pasar información entre tareas).

Opciones para los valores de fecha y hora

Use los argumentos siguientes para especificar el valor devuelto de las variables de parámetro basadas en el tiempo. Todos los valores devueltos se basan en una marca de tiempo en la zona horaria UTC.

Argumento	Descripción
iso_weekday	Devuelve un dígito de 1 a 7, que representa el día de la semana de la marca de tiempo.
is_weekday	Devuelve true si la marca de tiempo es un día de la semana.
iso_date	Devuelve la fecha en formato ISO.
iso_datetime	Devuelve la fecha y hora en formato ISO.
year	Devuelve la parte del año de la marca de tiempo.
month	Devuelve la parte del mes de la marca de tiempo.
day	Devuelve la parte del día de la marca de tiempo.
hour	Devuelve la parte de la hora de la marca de tiempo.
minute	Devuelve la parte del minuto de la marca de tiempo.
second	Devuelve la parte del segundo de la marca de tiempo.
timestamp_ms	Devuelve la marca de tiempo en milisegundos.

Referencias de valores dinámicos en desuso

Las siguientes referencias de valores dinámicos están en desuso. La referencia de reemplazo recomendada se incluye en la descripción de cada variable.

Variable	Descripción
{{job_id}}	Identificador único asignado a un trabajo. Use job.id en su lugar.
{{run_id}}	Identificador único asignado a una ejecución de tarea. Use task.run_id en su lugar.
{{start_date}}	Fecha en que se inició la ejecución de una tarea. El formato es aaaa-mm-dd en la zona horaria UTC. En su lugar, use job.start_time.<argument>.
{{start_time}}	Marca de tiempo del inicio de la ejecución después de crear y preparar el clúster. El formato es de milisegundos desde la época de UNIX en la zona horaria UTC, tal y como devuelve System.currentTimeMillis(). En su lugar, use job.start_time.<format>.
{{task_retry_count}}	Número de reintentos que se ha intentado ejecutar una tarea si se produce un error en el primer intento. El valor es 0 para el primer intento y se incrementa con cada reintento. Use task.execution_count en su lugar.
{{parent_run_id}}	Identificador único asignado a la ejecución de un trabajo con varias tareas. Use job.run_id en su lugar.
{{task_key}}	Nombre único asignado a una tarea que forma parte de un trabajo con varias tareas. Use task.name en su lugar.