작업에서 매개 변수 값 액세스

Azure Databricks Notebook, Python 스크립트 및 SQL 파일을 포함하여 태스크의 코드에서 매개 변수 값에 액세스합니다.

매개 변수에는 사용자 정의 매개 변수, 업스트림 작업의 값 출력 및 작업에서 생성된 메타데이터 값이 포함됩니다. 매개 변수화 작업을 참조하세요.

세부 정보는 작업 유형따라 다르지만 소스 코드에서 매개 변수 값을 참조하는 데 사용되는 네 가지 일반적인 메서드가 있습니다.

이러한 각 경우에서 매개 변수의 키를 참조하여 해당 값을 검색합니다. 키는 매개 변수의 이름이라고도 합니다.

SQL 작업과 For each 작업을 활용하여 메타데이터 기반 작업에서 이러한 기술이 어떻게 적용되는지 보려면 컨트롤 테이블로 For each 작업 구동하기를 참조하세요.

노트북의 코드에서 dbutils을 사용하세요

작업에서 실행되는 Notebook 코드는 dbutils 라이브러리를 사용하여 매개 변수 값에 액세스할 수 있습니다. 다음 예제에서는 Python dbutils 사용하여 Notebook 작업에 전달되는 year_param 작업 매개 변수의 값을 가져오는 방법을 보여 있습니다.

from pyspark.sql.functions import year

# Retrieve the job-level parameter
year_value = dbutils.widgets.get("year_param")

# Use the value to filter bookings by check-in year
display(spark.read.table("samples.wanderbricks.bookings").filter(year("check_in") == year_value))

매개 변수는 이름으로 액세스됩니다. 작업 매개 변수와 작업 매개 변수가 키를 공유하는 경우 작업 매개 변수가 우선합니다. 작업 매개 변수 푸시다운을 참조하세요.

위의 코드는 매개 변수가 독립 실행형 Notebook으로 전송되지 않으므로 작업의 일부가 아닌 독립 실행형 Notebook에서 실행할 때 오류를 생성합니다. 다음 코드를 사용하여 year_param 매개 변수에 대한 기본값을 설정할 수 있습니다.

from pyspark.sql.functions import year

# Set a default for when the notebook runs outside a job
dbutils.widgets.text("year_param", "2025", "Year Parameter")

# Retrieve the parameter, falling back to the default if it isn't set
year_value = dbutils.widgets.get("year_param")

display(spark.read.table("samples.wanderbricks.bookings").filter(year("check_in") == year_value))

이는 작업 외부에서 테스트하는 데 유용하지만 잘못 구성된 작업 또는 작업 매개 변수도 마스킹합니다.

SQL에서 명명된 매개 변수 사용

Notebook 또는 파이프라인 작업에서 SQL을 실행하는 경우 명명된 매개 변수 구문을 사용하여 작업 매개 변수를 검색할 수 있습니다. 예를 들어, year_param라는 작업 매개 변수를 검색하려면 쿼리에서 :year_param를 사용하여 해당 값을 가져올 수 있습니다.

SELECT year(check_in) AS year_of_stay, count(*) AS bookings, round(avg(total_amount), 2) AS avg_amount
FROM samples.wanderbricks.bookings
WHERE year(check_in) = :year_param
GROUP BY year(check_in)

코드 인수로서 액세스

일부 작업 형식의 경우 매개 변수가 인수로 코드에 전달됩니다. 다음 작업 유형에는 인수가 전달됩니다.

  • Python script
  • Python Wheel
  • JAR
  • Spark Submit

자세한 내용은 이 페이지의 뒷부분에 있는 작업 유형별 세부 정보를 참조하세요.

dbt 작업의 경우 태스크에서 dbt 명령을 호출하여 매개 변수를 전달합니다.

작업을 구성할 때 동적 값 참조 사용

Azure Databricks UI에서 작업을 구성하는 경우 동적 값 참조 구문을 사용하여 작업 매개 변수 또는 기타 동적 값을 검색합니다. 작업 매개 변수를 검색하려면 다음 구문을 {{job.parameters.<name>}}사용합니다. 예를 들어 Python wheel 작업을 구성할 때 매개 변수의 Key 및 입력을 설정하여 year_paramyear / 같은 Year_{{job.parameters.year_param}} 작업 매개 변수를 참조할 수 있습니다. 동적 값은 구성에서 매개 변수에 대한 액세스 권한을 제공하는 것 외에도 작업 또는 작업에 대한 다른 데이터(예: {{job.id}})에 대한 액세스 권한을 제공합니다. 작업 구성에서 {} 클릭하여 가능한 동적 값 목록을 가져와서 구성에 삽입할 수 있습니다.

작업 유형별 세부 정보

이러한 방법 중 작업 유형에 따라 사용하는 메서드가 달라집니다.

작업 유형 구성에서 검색 코드에서 검색
노트북 Azure Databricks UI에서 동적 값 참조를 사용하여 노트북을 설정하도록 할 수 있습니다(예: 작업 매개 변수 값에서 작업 매개 변수를 참조하는 경우). 다른 설정 옵션으로 작업 실행을 사용하여 작업을 수동으로 실행할 때 매개 변수를 재정의하거나 추가할 수 있습니다. Notebook에서 SQL에 대해 명명된 매개변수를 사용하거나 코드에서 dbutils.widgets을 사용할 수 있습니다.
Python 스크립트 태스크에 정의된 매개 변수는 스크립트에 인수로 전달됩니다. 매개 변수 텍스트 상자에서 동적 값 참조를 사용할 수 있습니다. 매개 변수는 위치 인수로 읽거나 Python argparse 모듈을 사용하여 구문 분석할 수 있습니다.
Python 휠 작업 정의에 정의된 매개 변수는 코드에 키워드 인수로 전달됩니다. 키워드 인수를 허용하도록 Python 휠 파일을 구성해야 합니다. 매개 변수 값에 동적 값 참조를 사용할 수 있습니다. 스크립트에 키워드 인수로 접근합니다. Python 휠 파일에 패키지된 Python 스크립트에서 인수를 읽는 예제를 보려면 Lakeflow 작업에서 Python 휠 파일 사용을 참조하세요.
SQL 작업 구성에서 동적 값 참조를 사용할 수 있습니다. 명명된 매개 변수를 사용하여 매개 변수 값을 검색합니다.
파이프라인 (매개 변수는 베타에 있습니다). 동적 값 참조를 사용하여 작업을 구성할 때 매개 변수 텍스트 상자에 매개 변수를 인수로 전달할 수 있습니다. 명명된 매개 변수를 사용하여 매개 변수 값을 검색합니다.
대시보드 작업에서 대시보드 필터를 구성하여 필터 값을 미리 적용할 수 있습니다 . 필터의 URL 식별자가 작업 수준 매개 변수 키와 일치하는 경우 작업은 해당 매개 변수의 값을 필터에 자동으로 적용합니다. 적용할 수 없습니다.
Power BI Power BI 작업은 작업에 매개 변수 전달을 지원하지 않습니다. 지원되지 않습니다.
dbt 동적 값 참조를 사용하여 작업을 구성할 때 매개 변수를 dbt 명령으로 전달할 수 있습니다. dbt 명령으로 액세스합니다.
독 동적 값 참조를 사용하여 작업을 구성할 때 매개 변수 텍스트 상자에 매개 변수를 인수로 전달할 수 있습니다. 매개 변수는 main 클래스의 main 메서드에 대한 인수로 액세스됩니다.
Spark 서브밋 동적 값 참조를 사용하여 작업을 구성할 때 매개 변수 텍스트 상자에 매개 변수를 인수로 전달할 수 있습니다. 매개 변수는 main 클래스의 main 메서드에 대한 인수로 액세스됩니다.
작업 실행 동적 값 참조를 사용하여 작업을 구성할 때 작업 매개 변수 집합을 만들 수 있습니다. 값에는 동적 값 참조가 포함될 수 있습니다. 적용할 수 없습니다.
If/else 조건 예를 들어 조건작업을 구성할 때 동적 값 참조를 사용할 수 있습니다. 적용할 수 없습니다.
각 항목에 대해 작업에 대한 입력 구성할 때 동적 값 참조를 사용할 수 있습니다. 중첩된 태스크는 중첩된 작업의 각 반복에 대해 하나의 입력을 작업 매개 변수로 받습니다. 중첩된 작업은 작업 유형에 따라 매개 변수를 검색합니다.
클린룸 노트북 Azure Databricks UI에서 동적 값 참조를 사용하여 노트북을 설정하도록 할 수 있습니다(예: 작업 매개 변수 값에서 작업 매개 변수를 참조하는 경우). Notebook에서 SQL에 대해 명명된 매개변수를 사용하거나 코드에서 dbutils.widgets을 사용할 수 있습니다.
  • Last updated on