파라미터

파라미터 (Params)

같은 DAG를 상황에 따라 조금씩 다르게 실행하고 싶을 때가 있어요. Airflow는 이를 위해 Param이라는 런타임 설정 메커니즘을 제공해요. DAG 코드에 기본 Params를 정의해 두고, DAG를 트리거할 때 추가 Params를 제공하거나 값을 덮어쓸 수 있죠. Param 값은 JSON Schema로 검증돼요.

출처: Params - Apache Airflow 공식 문서

Params란

Params를 쓰면 태스크에 런타임 설정을 제공할 수 있어요. DAG 코드에서 기본 Params를 구성해 두고, DAG를 트리거할 때 추가 Params를 공급하거나 Param 값을 덮어쓸 수 있어요. 값은 JSON Schema로 검증되고, 스케줄된 Dag Run에서는 기본 Param 값이 사용돼요.

DAG 레벨 Params

DAG에 Params를 추가하려면 params kwarg로 초기화하면 돼요. Param 이름을 Param 객체 또는 해당 파라미터의 기본값을 나타내는 객체에 매핑하는 딕셔너리를 사용해요.

with DAG(
    "the_dag",
    params={"my_int_param": Param(5, type="integer", minimum=3)},
    render_template_as_native_obj=True,
):

태스크 레벨 Params

태스크 레벨 params는 DAG 레벨 params보다 우선해요. 그리고 DAG를 트리거할 때 사용자가 제공한 params는 태스크 레벨 params보다 우선해요. 우선순위는 '사용자 제공 > 태스크 레벨 > DAG 레벨' 순으로 기억하면 돼요.

태스크에서 Params 참조하기

Params는 params 아래의 템플릿 문자열에서 참조할 수 있어요. 예를 들어:

PythonOperator(
    task_id="from_template",
    op_args=[
        "{{ params.my_int_param + 10 }}",
    ],
    python_callable=(
        lambda my_int_param: print(my_int_param)
    ),
)

Params는 다양한 타입을 쓸 수 있지만, 템플릿의 기본 동작은 태스크에 문자열을 제공하는 거예요. DAG를 초기화할 때 render_template_as_native_obj=True를 설정하면 이 동작을 바꿀 수 있어요.

with DAG(
    "the_dag",
    params={"my_int_param": Param(5, type="integer", minimum=3)},
    render_template_as_native_obj=True,
):

이렇게 하면 Param의 타입이 태스크에 제공될 때 존중돼요.

JSON Schema 검증

DAG에 schedule이 정의되어 있으면 기본값이 있는 params는 유효해야 해요. 이건 DAG 파싱 시점에 검증돼요. schedule=None이면 DAG 파싱 때가 아니라 DAG를 트리거하기 전에 params가 검증돼요.

보안상 이유로, 현재로서는 커스텀 클래스에서 파생된 Param 객체는 사용할 수 없어요. Operator ExtraLinks처럼 커스텀 Param 클래스용 등록 시스템을 계획 중이에요.

Params로 트리거 UI 폼 제공하기

트리거 UI 폼은 미리 정의된 DAG Params를 기반으로 렌더링돼요. DAG에 params가 정의되어 있지 않으면 트리거 폼은 생략돼요. 폼 요소는 Param 클래스로 정의할 수 있고, 그 속성들이 폼 필드가 어떻게 표시되는지를 결정해요.

트리거 UI 폼에서 지원하는 기능은 다음과 같아요.

HTML 폼은 JSON 입력의 문법만 검증해요. 특정 구조의 내용을 검증하려면 JSON Schema Object 세부 내용을 참고하세요.

Type에 대한 기본 동작: type 속성은 단일 타입도, 타입 리스트도 받아요. 예를 들어 type=["null", "string"]은 null이거나 string인 값을 허용해요. 기본적으로 타입을 지정하면 해당 필드는 required가 되고 JSON 스키마에 따라 입력이 필요해져요.

{
    "number_param": 3,
    "text_param": "Hello World!",
    "bool_param": False,
}

폼을 더 보기 좋게 만들고 싶다면 파라미터에 설명을 추가할 수 있어요. 설명에 Markdown 서식을 넣으려면 description_md 속성을 사용하면 돼요.

Param(
    "optional text, you can trigger also w/o text",
    type=["null", "string"],
    title="Optional text field",
    description_md="This field is optional. As field content is JSON schema validated you must ...",
)

Params UI 튜토리얼은 가장 흔한 예시 4개 섹션으로 렌더링돼요. 첫 번째 섹션은 Param 클래스 없이 기본 사용법을 보여주고, 두 번째는 Param 클래스로 더 많은 속성을 정의하는 방법, 세 번째는 선택 목록과 드롭다운을 모델링하는 방법이에요.

런타임 Param 수정 비활성화

DAG를 트리거할 때 params를 업데이트할 수 있는지는 core.dag_run_conf_overrides_params 플래그에 달려 있어요. 이 설정을 False로 하면 기본 params가 사실상 상수가 돼요.