동적 값 참조란?

아티클
10/14/2024

동적 값 참조는 작업 및 태스크를 구성할 때 사용할 수 있는 변수 컬렉션을 기술합니다. 동적 값 참조를 사용하여 태스크에 대한 조건문을 구성하거나 정보를 매개 변수 또는 인수로 전달합니다.

동적 값 참조에는 다음과 같은 정보가 포함됩니다.

작업 이름, 작업 이름, 트리거 유형을 포함한 작업에 대해 구성된 값
작업 ID, 실행 ID, 작업 실행 시작 시간을 포함한 작업에 대해 생성된 메타데이터
작업이 실행한 복구 시도 또는 태스크를 실행한 재시도 횟수에 대한 정보
특정 작업의 결과 상태
작업 매개 변수, 태스크 매개 변수를 사용하여 구성되거나 태스크 값을 사용하여 설정된 값

동적 값 참조 사용

작업 또는 태스크를 구성할 때 동적 값 참조를 사용합니다. Notebook, 쿼리, JAR과 같은 태스크를 사용하여 구성된 자산에서 동적 값 참조를 직접 참조할 수 없습니다. 동적 값 참조는 컨텍스트를 태스크에 전달하는 매개 변수 또는 필드를 사용하여 정의되어야 합니다.

동적 값 참조는 이중 중괄호({{ }})를 사용합니다. 작업 또는 태스크가 실행되면 문자열 리터럴이 동적 값 참조를 대체합니다. 예를 들어 다음 키-값 쌍을 태스크 매개 변수로 구성하는 경우,

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

실행 ID가 550315892394120이면 job_run_id의 값이 .job_550315892394120으로 평가됩니다.

참고 항목

이중 중괄호 사이의 내용은 식으로 평가되지 않습니다. 이중 중괄호 안에 있는 연산 또는 함수를 실행할 수 없습니다.

사용자가 제공한 값 식별자는 영숫자 및 밑줄 문자를 지원합니다. 식별자를 백틱(` `)으로 둘러싸고 특수 문자를 포함하는 이스케이프 키

존재하지 않는 동적 참조 값 및 누락된 괄호를 포함한 구문 오류는 자동으로 무시되며 리터럴 문자열로 처리됩니다. 예를 들어 {{job.notebook_url}}과 같은 알려진 네임스페이스에 속하는 잘못된 참조를 제공하는 경우 오류 메시지가 표시됩니다.

작업 UI에서 동적 값 참조 사용

동적 값 참조를 허용하는 필드는 사용 가능한 동적 값 참조를 삽입하는 바로 가기를 제공합니다. { }를 클릭하여 목록을 보고 제공된 필드에 삽입합니다.

참고 항목

UI는 작업 값을 참조하는 키를 자동으로 완성하지 않습니다.

동적 값 참조를 허용하는 많은 필드를 올바르게 사용하려면 추가 서식 지정이 필요합니다. 태스크 매개 변수 구성을 참조하세요.

작업 JSON에서 동적 값 참조 사용

{{ }} 구문을 사용하여 Databricks CLI 및 REST API에서 사용하는 작업 JSON 정의에 동적 값을 사용합니다.

작업 및 태스크 매개 변수는 구문이 다르며, 태스크 매개 변수 구문은 태스크 유형에 따라 다릅니다.

다음 예제에서는 동적 값 참조를 사용하여 작업 매개 변수를 구성하는 JSON 구문 일부를 보여줍니다.

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

다음 예제에서는 동적 값 참조를 사용하여 Notebook 태스크 매개 변수를 구성하는 JSON 구문 일부를 보여줍니다.

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

작업 실행의 매개 변수 검토

태스크가 완료되면 실행 세부 정보 페이지의 매개 변수에서 확인된 매개 변수 값을 볼 수 있습니다. 작업 실행 세부 정보 보기를 참조하세요.

지원되는 값 참조

지원되는 동적 값 참조는 다음과 같습니다.

참조	설명
`{{job.id}}`	작업에 할당된 고유 식별자
`{{job.name}}`	작업 실행 시의 작업 이름
`{{job.run_id}}`	작업 실행에 할당된 고유 식별자
`{{job.repair_count}}`	현재 작업 실행에 대한 복구 시도 횟수
`{{job.start_time.<argument>}}`	작업 실행이 시작된 시간(UTC 시간대)을 기반으로 하는 값 반환 값은 `argument` 옵션에 따라 달라집니다. 날짜 및 시간 값 옵션을 참조하세요.
`{{job.parameters.<name>}}`	키 `<name>`가 있는 작업 수준 매개 변수 값
`{{job.trigger.type}}`	작업 실행의 트리거 유형 가능한 값은 `periodic`, `one_time`, `run_job_task`, `file_arrival`, `continuous`, `table`입니다.
`{{job.trigger.file_arrival.location}}`	작업에 파일 도착 트리거가 구성된 경우, 스토리지 위치 값
`{{job.trigger.time.<argument>}}`	작업 실행이 트리거된 시간(UTC 표준 시간대)을 기준으로 하는 값, cron 예약된 작업의 경우 가장 가까운 분으로 내림 처리. 반환 값은 `argument` 옵션에 따라 달라집니다. 날짜 및 시간 값 옵션을 참조하세요.
`{{task.name}}`	현재 태스크의 이름
`{{task.run_id}}`	현재 태스크 실행의 고유 식별자
`{{task.execution_count}}`	현재 태스크가 실행된 횟수(재시도 및 복구 포함)
`{{task.notebook_path}}`	현재 Notebook 태스크의 Notebook 경로
`{{tasks.<task_name>.run_id}}`	`<task_name>`의 태스크 실행에 할당된 고유 식별자
`{{tasks.<task_name>.result_state}}`	태스크 `<task_name>`의 결과 상태 가능한 값은 `success`, `failed`, `excluded`, `canceled`, `evicted`, `timedout`, `upstream_canceled`, `upstream_evicted`, `upstream_failed`입니다.
`{{tasks.<task_name>.error_code}}`	태스크 실행 중 오류가 발생한 경우, 태스크 `<task_name>`의 오류 코드 가능한 값의 예시는 `RunExecutionError`, `ResourceNotFound`, `UnauthorizedError`입니다. 태스크가 성공한 경우, 빈 문자열로 평가됩니다.
`{{tasks.<task_name>.execution_count}}`	태스크 `<task_name>`가 실행된 횟수(재시도 및 복구 포함)
`{{tasks.<task_name>.notebook_path}}`	Notebook 태스크 `<task_name>`의 Notebook 경로
`{{tasks.<task_name>.values.<value_name>}}`	태스크 `<task_name>`로 설정된 키 `<value_name>`의 태스크 값
`{{workspace.id}}`	작업 영역에 할당된 고유 식별자
`{{workspace.url}}`	작업 영역의 URL

모든 태스크에서 이러한 참조를 설정할 수 있습니다. 태스크 매개 변수 구성을 참조하세요.

작업 값이 있는 작업의 작업 간에 매개 변수를 전달할 수도 있습니다. 태스크 간에 정보 전달을 위해 태스크 값 사용을 참조하세요.

날짜 및 시간 값 옵션

다음 인수를 사용하여 시간 기반 매개 변수의 반환 값을 지정합니다. 모든 반환 값은 UTC 시간대의 타임스탬프를 기반으로 합니다.

인수	설명
`iso_weekday`	타임스탬프의 요일을 나타내는 1에서 7까지의 숫자를 반환합니다.
`is_weekday`	타임스탬프가 평일이면 `true`을 반환합니다.
`iso_date`	날짜를 ISO 형식으로 반환합니다.
`iso_datetime`	날짜와 시간을 ISO 형식으로 반환합니다.
`year`	타임스탬프의 연 부분을 반환합니다.
`month`	타임스탬프의 월 부분을 반환합니다.
`day`	타임스탬프의 일 부분을 반환합니다.
`hour`	타임스탬프의 시 부분을 반환합니다.
`minute`	타임스탬프의 분 부분을 반환합니다.
`second`	타임스탬프의 초 부분을 반환합니다.
`timestamp_ms`	타임스탬프 밀리초로 반환합니다.

사용되지 않는 동적 값 참조

다음 동적 값 참조는 더 이상 사용되지 않습니다. 각 변수의 설명에 권장되는 대체 참조가 포함되어 있습니다.

변수	설명
`{{job_id}}`	작업에 할당된 고유 식별자입니다. 대신 `job.id`를 사용하세요.
`{{run_id}}`	태스크 실행에 할당된 고유 식별자 대신 `task.run_id`를 사용하세요.
`{{start_date}}`	태스크 실행이 시작된 날짜. UTC 시간대 기준의 yyyy-MM-dd 형식입니다. 대신 `job.start_time.<argument>`를 사용하세요.
`{{start_time}}`	클러스터가 만들어지고 준비된 후 실행의 실행이 시작된 타임스탬프. 형식은 `System.currentTimeMillis()`에서 반환하는 UTC 표준 시간대 기준 UNIX Epoch 이후 밀리초입니다. 대신 `job.start_time.<format>`를 사용하세요.
`{{task_retry_count}}`	첫 번째 시도가 실패하는 경우 태스크를 실행하려고 시도한 다시 시도 횟수. 값은 첫 번째 시도의 경우 0이고 다시 시도할 때마다 증분합니다. 대신 `task.execution_count`를 사용하세요.
`{{parent_run_id}}`	여러 태스크가 있는 작업의 실행에 할당된 고유 식별자입니다. 대신 `job.run_id`를 사용하세요.
`{{task_key}}`	여러 태스크가 있는 작업의 일부인 태스크에 할당된 고유 이름입니다. 대신 `task.name`를 사용하세요.

다음을 통해 공유