파이프라인에서 Notebook 호출하고 매개변수 넘기기

원문: Notebook activity 게시일: 2025-06-16 · Microsoft Fabric 설명서

Notebook을 하나 만들어서 잘 돌아가는 걸 확인했다면, 다음 단계는 보통 “이걸 정해진 흐름 안에 끼워 넣기”예요. 매일 새벽에 자동으로 돌리고 싶거나, Copy activity로 데이터를 가져온 다음 그 결과를 Notebook에서 가공하고 싶을 때죠. Fabric 파이프라인의 Notebook activity가 이 역할을 해요. 그런데 그냥 “Notebook을 실행”하는 것만으로는 부족할 때가 많아요 — 어떤 날짜 데이터를 처리할지, 어떤 테이블을 대상으로 할지 같은 값을 매번 다르게 넘겨줘야 하니까요. 이걸 가능하게 하는 게 **매개변수 셀(parameter cell)**이에요.

매개변수 셀 만들기

Notebook 안에서 파라미터로 쓸 변수를 코드 셀 하나에 몰아서 기본값과 함께 적어둡니다.

date = "2024-01-01"
region = "US"

그다음 이 셀의 더보기(…) 메뉴에서 Toggle parameter cell을 선택해 “이 셀이 매개변수 셀이다”라고 표시해줘요. 이렇게 표시해두면 파이프라인이나 다른 Notebook이 이 Notebook을 호출할 때, 실행 엔진이 매개변수 셀 바로 아래에 새 셀을 하나 추가해서 넘겨받은 값으로 원래 기본값을 덮어써요. 원본 셀은 그대로 두고 실행 시점에만 값을 바꿔치기하는 방식이라, 노트북을 대화형으로 열어봐도 원래 기본값이 남아 있어서 헷갈릴 일이 적어요.

Notebook activity에서 값 넘기기

파이프라인 캔버스에 Notebook activity를 올리고 Settings 탭에서 대상 Notebook을 고르면, Base parameters 영역에 값을 넣을 수 있어요. 이때 파이프라인 표현식 언어를 그대로 쓸 수 있어서, 다른 활동의 출력값이나 파이프라인 파라미터를 그대로 실어 보낼 수 있어요.

값을 하나하나 손으로 맞춰 넣는 대신 Auto-populate base parameters 기능을 쓰면 더 편해요. Notebook에 매개변수 셀만 있으면, Notebook activity에서 그 Notebook을 선택하고 Base parameters로 전환하는 순간 이름·타입·기본값이 자동으로 채워져요. Notebook을 바꾸면 목록도 같이 새로고침되고, 매개변수 셀이 없는 Notebook을 고르면 아무것도 채워지지 않아요. 자동으로 채운 값을 그대로 쓰거나 필요한 것만 덮어써도 됩니다.

지원되는 파라미터 타입은 int, float, bool, string 같은 단순 타입이에요. 리스트나 딕셔너리 같은 복합 타입은 아직 직접 지원되지 않아서, JSON 문자열로 직렬화해서 넘긴 뒤 Notebook 안에서 json.loads()로 다시 풀어내는 방식을 씁니다.

import json

params = json.loads(json_string)
param1 = params.get("param1")
param2 = params.get("param2")

파라미터 이름은 Notebook의 매개변수 셀에 적힌 이름과 파이프라인 쪽 이름이 정확히 같아야 해요. 이름이 다르면 그 값은 조용히 무시돼요.

Notebook의 결과값을 다음 활동으로 넘기기

반대 방향, 즉 Notebook이 끝나고 나온 값을 파이프라인 뒤쪽 활동에서 받아쓰고 싶을 때는 notebookutils.notebook.exit()¹를 씁니다.

notebookutils.notebook.exit("value string")

파이프라인 안에서 Notebook activity로 실행된 Notebook이 exit()를 호출하면, 그 문자열이 활동의 출력값으로 나오고 파이프라인은 계속 진행돼요. 대화형으로(직접 셀을 눌러) 실행할 때와 파이프라인이 호출할 때 동작이 달라진다는 점이 중요해요.

대화형 실행: exit()가 예외를 던져서 뒤 셀 실행을 멈추지만, Spark 세션은 살아 있어요.
파이프라인에서 호출: Notebook activity가 그 exit 값을 들고 완료되고, 파이프라인 실행도 함께 끝나면서 해당 Spark 세션도 종료돼요.
다른 Notebook에서 참조 실행할 때: 참조된 Notebook만 그 지점에서 멈추고, 참조한 쪽(부모) Notebook은 나머지 셀을 계속 실행해요.

exit 값은 항상 문자열이에요. 숫자로 다시 쓰고 싶으면 받는 쪽에서 int() 같은 변환을 직접 해줘야 해요. 그리고 한 가지 꼭 지켜야 할 규칙이 있는데, exit()를 try-catch 블록 안에서 부르면 안 돼요. 예외 처리에 감싸여 있으면 exit이 제대로 전달되지 않고 파이프라인이 값을 받지 못해요. exit()는 항상 코드 최상위, 그리고 다른 셀 출력이 지워지지 않도록 별도 셀에 단독으로 둬야 해요.

세션을 아끼는 팁 한 가지

파이프라인 하나가 Notebook activity를 여러 번 호출한다면, **세션 태그(session tag)**를 설정해서 같은 Spark 세션을 재사용하게 할 수 있어요. 임의의 문자열을 태그로 정해두면, 같은 태그를 쓰는 다음 Notebook activity가 기존 세션이 있으면 그걸 그대로 쓰고 없으면 새로 만들어요. 매번 세션을 새로 띄우는 시간을 줄여주는 옵션인데, 워크스페이스 설정에서 High concurrency mode for pipeline running multiple notebooks를 켜둬야 이 태그가 동작해요.

정리

Notebook을 파이프라인 흐름에 붙이는 핵심은 세 가지예요. Notebook 쪽에는 매개변수 셀을 하나 정해두고, 파이프라인 쪽 Notebook activity의 Base parameters로 값을 채워 넣고(자동 채우기 기능을 쓰면 더 편해요), 결과를 뒤로 넘기고 싶으면 notebookutils.notebook.exit()를 최상위 코드에서 호출하면 돼요. 이 세 조각만 맞추면 Notebook도 다른 파이프라인 활동과 똑같이 값을 주고받는 부품이 됩니다.

어휘 주석

notebookutils: Fabric Notebook에 기본 내장된 유틸리티 패키지예요. 이전 이름은 mssparkutils였고, notebook.exit() 외에도 파일 조작, 다른 Notebook 실행 같은 기능을 제공해요.