notebookutils: 파일 다루고 다른 Notebook 부르는 도우미

원문: NotebookUtils (former MSSparkUtils) for Fabric 게시일: 2025-03-31 · Microsoft Fabric 설명서

Fabric Notebook을 열면 별도로 설치하지 않아도 바로 쓸 수 있는 도구 모음이 하나 있어요. 파일을 옮기고, 비밀값을 안전하게 가져오고, 다른 Notebook을 호출하는 것처럼 Spark 코드만으로는 번거로운 일들을 짧은 호출 한 줄로 처리해주는 notebookutils예요. PySpark, Scala, SparkR 노트북은 물론 파이프라인에서도 쓸 수 있어요.

이름이 왜 두 개예요? mssparkutils와 notebookutils

원래 이 패키지 이름은 MSSparkUtils였어요. Fabric이 이 이름을 공식적으로 NotebookUtils로 바꿨는데, 기존에 mssparkutils로 짜둔 코드가 갑자기 깨지는 일은 없도록 하위 호환을 유지하고 있어요. 즉 기존 코드는 그대로 돌아가지만, 새로운 기능과 업데이트는 앞으로 notebookutils 네임스페이스에만 들어가고 mssparkutils는 언젠가 폐지될 예정이에요. 새로 코드를 짠다면 처음부터 notebookutils를 쓰는 게 맞고, notebookutils는 Spark 3.4(런타임 v1.2) 이상을 전제로 설계됐어요.

뭘 할 수 있는지 훑어보기

notebookutils는 기능별로 모듈이 나뉘어 있어요.

모듈	네임스페이스	하는 일
파일 시스템 유틸리티	notebookutils.fs	ADLS Gen2·Blob Storage·Lakehouse 스토리지의 파일·디렉터리 복사, 이동, 읽기, 쓰기, 삭제, 목록 조회
파일 마운트/언마운트	notebookutils.fs	원격 스토리지를 Spark 노드에 로컬 마운트 지점처럼 연결
Notebook 실행·오케스트레이션	notebookutils.notebook	다른 Notebook 실행·체이닝, DAG 기반 병렬 실행, exit 값 처리
Notebook 관리	notebookutils.notebook	Notebook 항목을 코드로 생성·조회·수정·삭제
자격 증명 유틸리티	notebookutils.credentials	Azure 서비스 액세스 토큰 발급, Key Vault 비밀 조회
Lakehouse 유틸리티	notebookutils.lakehouse	Lakehouse 항목·테이블을 코드로 관리

지금 뭐가 있는지 다 기억할 필요는 없고, Notebook 셀에서 직접 물어보면 돼요.

notebookutils.help()          # 전체 모듈 개요
notebookutils.fs.help()       # fs 모듈 상세
notebookutils.notebook.help() # notebook 모듈 상세

fs: 파일 다루기

가장 자주 쓰게 되는 건 역시 notebookutils.fs예요. 기본 Lakehouse에 붙어 있는 파일이라면 상대 경로만으로도 접근할 수 있어요.

notebookutils.fs.ls("Files/tmp")  # 기본 Lakehouse의 Files 폴더 아래 목록
notebookutils.fs.mkdirs("Files/new_dir")

다른 Lakehouse나 ADLS Gen2, Blob Storage처럼 기본 Lakehouse가 아닌 곳에 접근하려면 abfss:// 형식의 절대 경로가 필요해요.

notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")

원격 스토리지를 아예 로컬 경로처럼 마운트해서 표준 파일 입출력 함수로 다루고 싶다면 notebookutils.fs.mount()도 있어요. Key Vault에서 액세스 키나 SAS 토큰을 받아와 마운트에 넘기는 식으로 자격 증명을 코드에 직접 하드코딩하지 않고 처리할 수 있어요.

notebook: 다른 Notebook 부르기, 값 넘기고 받기

notebookutils.notebook.run()은 다른 Notebook을 호출하고 그 결과값(exit 값)을 돌려받는 함수예요.

exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20})
print(exitVal)

세 번째 인자는 호출되는 Notebook의 매개변수 셀에 넘길 값이고, 두 번째 인자는 타임아웃(초)이에요. 호출되는 쪽 Notebook은 notebookutils.notebook.exit()로 결과를 돌려줘요.

notebookutils.notebook.exit("value string")

exit()의 동작은 어디서 호출되느냐에 따라 달라요. 대화형으로 직접 실행하면 예외를 던져 뒤 셀을 건너뛰고 세션은 그대로 유지되고, 파이프라인이 이 Notebook을 호출한 경우에는 그 값이 활동의 출력으로 나가면서 파이프라인도 이어서 진행돼요. 여러 Notebook을 한 번에 병렬로 돌리고 싶을 땐 notebookutils.notebook.runMultiple()을 쓸 수 있는데, 이건 실행할 Notebook 목록을 DAG(방향성 비순환 그래프) 형태로 정의해서 활동 간 의존 관계와 동시 실행 개수까지 지정할 수 있어요.

credentials: 비밀값 안전하게 가져오기

Key Vault에 저장해둔 비밀값을 코드에 노출하지 않고 가져오려면 notebookutils.credentials.getSecret()을 써요.

accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")

이렇게 받아온 값은 셀 출력에도 자동으로 마스킹(비밀 값 수정¹) 처리되기 때문에, 실수로 화면에 그대로 노출되는 사고를 줄여줘요.

정리

notebookutils는 Fabric Notebook에서 파일 조작(fs), 다른 Notebook 호출과 값 주고받기(notebook.run/exit), 안전한 자격 증명 조회(credentials)처럼 자주 반복되는 잡일을 표준화해둔 내장 도구예요. 예전 이름인 mssparkutils로 짜둔 코드도 계속 동작하지만, 새 코드라면 처음부터 notebookutils로 시작하는 게 앞으로의 업데이트를 놓치지 않는 길이에요.

---

어휘 주석

1. 비밀 값 수정(secret redaction): Notebook 셀 출력에 Key Vault 비밀 같은 민감한 값이 그대로 찍히지 않도록 자동으로 가려서 보여주는 기능이에요.