---
title: 파이프라인에서 Notebook 호출하고 매개변수 넘기기
description: Notebook activity로 Notebook을 오케스트레이션할 때 매개변수 셀 지정, 파이프라인에서 값 전달, exit 값을 다음 활동에서 받는 방법을 실습 순서로 정리했어요.
date: 2026-09-27
  tags: [Data Pipeline, Notebook activity, 매개변수, 오케스트레이션, Fabric]
cards:
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-01.png
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-02.png
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-03.png
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-04.png
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-05.png
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-06.png
  - /cards/fabric-run-notebook-from-pipeline-parameters/card-07.png
author: Lissa
source: https://interlinear.work/notes/fabric-run-notebook-from-pipeline-parameters/
---

> **원문:** [Notebook activity](https://learn.microsoft.com/en-us/fabric/data-factory/notebook-activity)
> **게시일:** 2025-06-16 · **Microsoft Fabric 설명서**

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

## 매개변수 셀 만들기

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

```python
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()`로 다시 풀어내는 방식을 씁니다.

```python
import json

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

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

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

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

```python
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도 다른 파이프라인 활동과 똑같이 값을 주고받는 부품이 됩니다.

---

## 어휘 주석

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