NotebookUtils Notebook 실행 및 오케스트레이션

Notebook 유틸리티를 사용하여 Notebook을 실행하거나, 여러 Notebook을 병렬로 실행하거나, 값이 있는 Notebook을 종료합니다. 사용 가능한 메서드에 관한 개요를 가져오려면 다음 명령을 실행합니다.

notebookutils.notebook.help()

다음 표에서는 사용 가능한 Notebook 실행 및 오케스트레이션 메서드를 나열합니다.

메서드	Signature	설명
`run`	`run(path: str, timeout_seconds: int = 90, arguments: dict = None, workspace: str = ""): str`	Notebook을 실행하고 종료 값을 반환합니다.
`runMultiple`	`runMultiple(dag: Any, config: dict = None): dict[str, dict[str, Any]]`	종속성 관계를 지원하여 여러 Notebook을 동시에 실행합니다.
`validateDAG`	`validateDAG(dag: Any): bool`	DAG 정의가 올바르게 구조화되었는지 여부를 확인합니다.
`exit`	`exit(value: str): None`	값이 있는 현재 Notebook을 종료합니다.

Notebook CRUD 작업(만들기, 가져오기, 업데이트, 삭제, 목록)은 Notebook 아티팩트 관리를 참조하세요.

메모

매개 config 변수는 runMultiple() Python에서만 사용할 수 있습니다. Scala 및 R은 이 매개 변수를 지원하지 않습니다.

메모

Notebook 유틸리티는 Apache Spark SJD(작업 정의)에 적용되지 않습니다.

노트북을 참조하세요

이 메서드는 run() Notebook을 참조하고 종료 값을 반환합니다. 중첩 함수 호출은 Notebook에서 인터랙티브하게 실행하거나 파이프라인에서 실행할 수 있습니다. 참조되고 있는 노트북은 이 함수를 호출하는 노트북의 Spark 풀에서 실행됩니다.

notebookutils.notebook.run("notebook name", <timeout_seconds>, <arguments>, <workspace>)

다음은 그 예입니다.

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

notebookutils.notebook.run("Sample1", 90, Map("input" -> 20), "")

notebookutils.notebook.run("Sample1", 90, list(input = 20), "")

반환 값

이 메서드는 자식 노트북에서 notebookutils.notebook.exit(value)에 전달된 정확히 동일한 문자열을 반환합니다. exit()가 자식 전자 필기장에서 호출되지 않으면 빈 문자열("")이 반환됩니다.

패브릭 Notebook은 작업 영역 ID를 지정하여 작업 영역 간 노트북 참조를 지원합니다.

notebookutils.notebook.run("Sample1", 90, {"input": 20 }, "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

notebookutils.notebook.run("Sample1", 90, Map("input" -> 20), "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

notebookutils.notebook.run("Sample1", 90, list(input = 20), "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

셀 출력에서 스냅샷 링크를 열어 참조 실행을 검사합니다. 스냅샷은 실행 결과를 캡처하고 참조된 Notebook을 디버그하는 데 도움이 됩니다.

자식 노트북들이 매개 변수를 받을 수 있도록 설정하세요.

run() 혹은 runMultiple()을 통해 호출되는 자식 notebook을 만들 때, notebook이 부모로부터 인수를 받을 수 있도록 매개 변수 셀을 설정합니다.

기본 매개 변수 값을 사용하여 코드 셀을 만듭니다.
Notebook UI에서 셀을 매개 변수로 표시를 선택하여 셀을 매개 변수 셀로 표시합니다.
실행하는 동안 매개 변수 셀 값은 부모에서 전달된 인수로 대체됩니다.

# This cell should be marked as "parameters" cell
# Default values are overridden when the notebook is called
date = "2024-01-01"
region = "US"

팁 (조언)

종료 값은 항상 문자열입니다. 부모 Notebook에 숫자 값이 필요한 경우 검색 후 결과를 변환합니다(예: int(result)).

고려 사항

작업 영역 간 참조 Notebook은 런타임 버전 1.2 이상에서 지원됩니다.
Notebook 리소스 아래의 파일을 사용하는 경우 참조된 Notebook에서 notebookutils.nbResPath를 사용해 대화형 실행과 동일한 폴더를 가리키는지 확인합니다.
참조 실행 기능은 자식 노트북이 부모와 동일한 레이크하우스를 사용하거나 부모의 레이크하우스를 상속받거나, 둘 다 정의하지 않을 경우에만 실행되도록 합니다. 자식이 부모 Notebook과 다른 레이크하우스를 지정하면 실행이 차단됩니다. 이 검사를 무시하려면 인수에 설정합니다 useRootDefaultLakehouse: True .
try-catch 블록 내에서 notebookutils.notebook.exit(value)를 호출하지 마세요. 예외 처리에서 래핑된 경우 종료 호출이 적용되지 않습니다.

여러 노트북을 병렬로 실행하는 방법에 대해 참조하세요.

notebookutils.notebook.runMultiple()를 사용하여 여러 노트북을 병렬로 또는 미리 정의된 토폴로지 구조로 실행하세요. API는 Spark 세션 내에서 다중 스레드 구현을 사용합니다. 즉, 참조된 Notebook 실행은 컴퓨팅 리소스를 공유합니다.

notebookutils.notebook.runMultiple()로 다음을 수행할 수 있습니다.

각 Notebook이 완료되는 것을 기다리지 않고 동시에 여러 Notebook을 실행합니다.
간단한 JSON 형식을 사용하여 Notebook에 대한 종속성 및 실행 순서를 지정합니다.
Spark 컴퓨팅 리소스 사용을 최적화하고 Fabric 프로젝트의 비용을 절감합니다.
출력에서 각 Notebook 실행 레코드의 스냅샷을 보고 Notebook 작업을 편리하게 디버그/모니터링합니다.
각 임원 활동의 종료 값을 가져와 다운스트림 작업에 사용합니다.

더 많은 예제 및 사용량 세부 정보를 보려면 실행 notebookutils.notebook.help("runMultiple") 합니다.

간단한 Notebook 목록 실행

다음 예제에서는 Notebook 목록을 병렬로 실행합니다.

notebookutils.notebook.runMultiple(["NotebookSimple", "NotebookSimple2"])

notebookutils.notebook.runMultiple(Seq("NotebookSimple", "NotebookSimple2"))

notebookutils.notebook.runMultiple(list("NotebookSimple", "NotebookSimple2"))

루트 Notebook의 실행 결과는 다음과 같습니다.

반환 값

메서드는 runMultiple() 각 키가 활동 이름이고, 각 값이 다음의 키를 가진 사전인 딕셔너리를 반환합니다.

exitVal: 자식 전자 필기장 exit() 호출에서 반환된 문자열이거나, 호출되지 않은 경우 exit() 빈 문자열입니다.
exception: 작업이 실패했거나 None 성공한 경우 오류 개체입니다.

DAG 구조로 Notebook 실행

다음 예제에서는 notebookutils.notebook.runMultiple()를 사용하여 DAG 구조에서 노트북들을 실행합니다.

# run multiple notebooks with parameters
DAG = {
    "activities": [
        {
            "name": "Process_1", # activity name, must be unique
            "path": "NotebookSimple", # notebook item name
            "timeoutPerCellInSeconds": 90, # max timeout for each cell, default to 90 seconds
            "args": {"p1": "changed value", "p2": 100}, # notebook parameters
            "workspace":"WorkspaceName" # both name and id are supported
        },
        {
            "name": "Process_2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200},
            "workspace":"id" # both name and id are supported
        },
        {
            "name": "Process_1.1",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["Process_1"] # list of activity names that this activity depends on
        }
    ],
    "timeoutInSeconds": 43200, # max timeout for the entire DAG, default to 12 hours
    "concurrency": 12 # max number of notebooks to run concurrently, default to 3x CPU cores, 0 means unlimited
}
notebookutils.notebook.runMultiple(DAG, {"displayDAGViaGraphviz": False})

val dag =
    """
        |{
        |  "activities": [
        |    {
        |      "name": "Process_1",
        |      "path": "NotebookSimple",
        |      "timeoutPerCellInSeconds": 90,
        |      "args": {"p1": "changed value", "p2": 100},
        |      "workspace": "WorkspaceName"
        |    },
        |    {
        |      "name": "Process_2",
        |      "path": "NotebookSimple2",
        |      "timeoutPerCellInSeconds": 120,
        |      "args": {"p1": "changed value 2", "p2": 200},
        |      "workspace": "id"
        |    },
        |    {
        |      "name": "Process_1.1",
        |      "path": "NotebookSimple2",
        |      "timeoutPerCellInSeconds": 120,
        |      "args": {"p1": "changed value 3", "p2": 300},
        |      "retry": 1,
        |      "retryIntervalInSeconds": 10,
        |      "dependencies": ["Process_1"]
        |    }
        |  ],
        |  "timeoutInSeconds": 43200,
        |  "concurrency": 12
        |}
        |""".stripMargin

notebookutils.notebook.runMultiple(dag)

DAG <- '{
    "activities": [
        {
            "name": "Process_1",
            "path": "NotebookSimple",
            "timeoutPerCellInSeconds": 90,
            "args": {"p1": "changed value", "p2": 100},
            "workspace": "WorkspaceName"
        },
        {
            "name": "Process_2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200},
            "workspace": "id"
        },
        {
            "name": "Process_1.1",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["Process_1"]
        }
    ],
    "timeoutInSeconds": 43200,
    "concurrency": 12
}'

notebookutils.notebook.runMultiple(DAG)

루트 Notebook의 실행 결과는 다음과 같습니다.

DAG 매개 변수 참조

다음 표에서는 DAG 정의에서 사용할 수 있는 각 필드에 대해 설명합니다.

분야	수준	필수	설명
`activities`	뿌리	예	실행할 노트북을 정의하는 활동 객체 목록입니다.
`timeoutInSeconds`	뿌리	No	전체 DAG에 대한 최대 시간 제한입니다. 기본값은 43200(12시간)입니다.
`concurrency`	뿌리	No	동시에 실행할 최대 Notebook 수입니다. 기본값은 사용 가능한 CPU 코어 수의 3배입니다. 더 엄격한 제어가 필요하거나 무제한 동시성을 위해 사용하는 `0` 경우 이 값을 명시적으로 설정합니다.
`name`	Activity	예	활동의 고유한 이름입니다. 결과를 식별하고 종속성을 정의하는 데 사용됩니다.
`path`	Activity	예	실행할 Notebook 항목 이름 또는 경로입니다.
`timeoutPerCellInSeconds`	Activity	No	자식 노트북의 각 셀에 대한 최대 시간 제한입니다. 기본값은 90초입니다.
`args`	Activity	No	자식 Notebook에 전달할 매개 변수 사전입니다.
`workspace`	Activity	No	Notebook이 있는 작업 영역 이름 또는 ID입니다. 기본적으로 자식 Notebook은 호출자와 동일한 작업 영역에서 실행됩니다.
`retry`	Activity	No	작업이 실패하는 경우 재시도 횟수입니다. 기본값은 0입니다.
`retryIntervalInSeconds`	Activity	No	재시도 사이의 대기 시간(초)입니다. 기본값은 0입니다.
`dependencies`	Activity	No	이 활동이 시작되기 전에 완료해야 하는 활동 이름 목록입니다.

활동 사이에서 종료 값을 참조하기

식@activity()을 사용하여 필드args에서 종속성 작업의 종료 값을 참조할 수 있습니다. 이 패턴을 사용하면 DAG의 Notebook 간에 데이터를 전달할 수 있습니다.

DAG = {
    "activities": [
        {
            "name": "Extract",
            "path": "ExtractData",
            "timeoutPerCellInSeconds": 120,
            "args": {"source": "prod_db"}
        },
        {
            "name": "Transform",
            "path": "TransformData",
            "timeoutPerCellInSeconds": 180,
            "args": {
                "data_path": "@activity('Extract').exitValue()"
            },
            "dependencies": ["Extract"]
        }
    ]
}

results = notebookutils.notebook.runMultiple(DAG)

팁 (조언)

필드의 @activity('activity_name').exitValue()args 식을 사용하여 한 작업의 결과를 DAG 내의 다른 작업으로 전달합니다.

동적 DAG 빌드

여러 파티션에서 팬아웃 처리와 같은 시나리오에 대해 프로그래밍 방식으로 DAG 구조를 생성할 수 있습니다.

def create_fan_out_dag(partitions):
    activities = []

    for partition in partitions:
        activities.append({
            "name": f"Process_{partition}",
            "path": "ProcessPartition",
            "timeoutPerCellInSeconds": 180,
            "args": {"partition": partition}
        })

    activities.append({
        "name": "Aggregate",
        "path": "AggregateResults",
        "timeoutPerCellInSeconds": 120,
        "dependencies": [f"Process_{p}" for p in partitions]
    })

    return {"activities": activities, "concurrency": 25}

partitions = ["2024-01", "2024-02", "2024-03", "2024-04"]
dag = create_fan_out_dag(partitions)

results = notebookutils.notebook.runMultiple(dag)

DAG 유효성 검사

실행하기 전에 DAG 구조가 유효한지 확인하는 데 사용합니다 validateDAG() . 중복 작업 이름, 누락된 종속성, 순환 참조와 같은 문제를 포착합니다.

notebookutils.notebook.validateDAG(DAG)

notebookutils.notebook.validateDAG(dag)

notebookutils.notebook.validateDAG(DAG)

반환 값

이 메서드는 validateDAG() DAG 구조가 유효한지 반환 True 하거나 유효성 검사가 실패할 경우 예외를 발생합니다.

팁 (조언)

항상 프로덕션 워크플로에서 validateDAG()을(를) 호출하고 그다음에 runMultiple()을(를) 실행하여 구조적 오류를 조기에 발견합니다.

runMultiple 오류 처리

메서드는 각 키가 활동 이름이고 각 값에 exitVal (문자열)과 exception (오류 객체 또는 None)가 포함된 사전을 runMultiple() 반환합니다. 일부 작업이 실패하는 경우에도 부분 결과를 검사할 수 있습니다.

from notebookutils.common.exceptions import RunMultipleFailedException

try:
    results = notebookutils.notebook.runMultiple(DAG)
except RunMultipleFailedException as ex:
    results = ex.result

for activity_name, result in results.items():
    if result["exception"]:
        print(f"{activity_name} failed: {result['exception']}")
    else:
        print(f"{activity_name} succeeded: {result['exitVal']}")

고려 사항

여러 Notebook 실행의 병렬 처리 수준은 Spark 세션의 사용 가능한 총 컴퓨팅 리소스로 제한됩니다.
동시 Notebook의 기본 수는 사용 가능한 CPU 코어 수의 3배입니다. 이 값을 사용자 지정할 수 있지만 과도한 병렬 처리로 인해 높은 컴퓨팅 리소스 사용량으로 인해 안정성 및 성능 문제가 발생할 수 있습니다. 문제가 발생하는 경우, DAG 매개 변수에서 runMultiple 필드를 조정하여 동시 실행 수를 줄이거나 Notebook을 여러 호출로 분리하는 방법을 고려하십시오.
전체 DAG의 기본 시간 제한은 12시간이며 자식 Notebook의 각 셀에 대한 기본 시간 제한은 90초입니다. DAG 매개 변수에서 timeoutInSeconds 및 timeoutPerCellInSeconds 필드를 설정하여 시간 제한을 변경할 수 있습니다.
retry 및 retryIntervalInSeconds를 네트워크 시간 초과 또는 임시 서비스 비가용성과 같은 일시적인 문제로 인해 실패할 수 있는 활동에 맞게 구성합니다.
병렬 Notebook은 단일 Spark 세션 내에서 컴퓨팅 리소스를 공유합니다. 메모리 부족 및 CPU 경합을 방지하기 위해 리소스 사용률을 모니터링합니다.

노트북 종료

exit() 메서드는 특정 값을 사용하여 노트북을 종료합니다. 중첩 함수 호출은 Notebook에서 인터랙티브하게 실행하거나 파이프라인에서 실행할 수 있습니다.

Notebook에서 exit() 함수를 대화형으로 호출하면, Fabric 노트북에서 예외를 발생시키고 후속 셀 실행을 건너뛰며 Spark 세션을 활성 상태로 유지합니다.
함수를 호출하는 파이프라인에서 Notebook을 exit() 오케스트레이션하면 Notebook 활동이 종료 값으로 반환됩니다. 그러면 파이프라인 실행이 완료되고 Spark 세션이 중지됩니다.
참조되는 Notebook에서 함수를 호출 exit() 할 때 Fabric Spark는 참조된 Notebook의 추가 실행을 중지하고 함수를 호출 run() 하는 주 Notebook의 다음 셀을 계속 실행합니다. 예를 들어 Notebook1에는 세 개의 셀이 있으며 두 번째 셀에서 함수를 호출 exit() 합니다. Notebook2에는 5개의 셀이 있으며, 세 번째 셀에서 run(notebook1)가 호출됩니다. Notebook2를 실행하면 Notebook1은 exit() 함수를 만나 두 번째 셀에서 중지됩니다. Notebook2는 네 번째 셀과 다섯 번째 셀을 계속 실행합니다.

notebookutils.notebook.exit("value string")

notebookutils.notebook.exit("value string")

notebookutils.notebook.exit("value string")

반환 동작

메서드는 exit() 값을 반환하지 않습니다. 현재 Notebook을 종료하고 제공된 문자열을 호출 Notebook 또는 파이프라인에 전달합니다.

메모

함수는 exit() 현재 셀 출력을 덮어씁니다. 다른 코드 문의 출력이 손실되지 않도록 하려면 별도의 셀에서 notebookutils.notebook.exit()을 호출하세요.

중요합니다

try-catch 블록 내에서 notebookutils.notebook.exit()를 호출하지 마세요. 예외 처리로 감싸여 있는 경우 종료 명령이 적용되지 않습니다. exit() 제대로 작동하려면 호출이 코드의 최상위 수준에 있어야 합니다.

다음은 그 예입니다.

Sample1 Notebook에는 다음 두 개의 셀이 있습니다.

셀 1은 기본값이 10으로 설정된 입력 매개 변수를 정의합니다.
셀 2는 입력 을 종료 값으로 사용하여 Notebook을 종료합니다.

기본값을 사용하여 다른 Notebook에서 Sample1을 실행할 수 있습니다.

exitVal = notebookutils.notebook.run("Sample1")
print (exitVal)

출력:

다른 Notebook에서 Sample1 을 실행하고 입력 값을 20으로 설정할 수 있습니다.

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

출력:

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-02

다음을 통해 공유

NotebookUtils Notebook 실행 및 오케스트레이션

노트북을 참조하세요

반환 값

자식 노트북들이 매개 변수를 받을 수 있도록 설정하세요.

고려 사항

여러 노트북을 병렬로 실행하는 방법에 대해 참조하세요.

간단한 Notebook 목록 실행

반환 값

DAG 구조로 Notebook 실행

DAG 매개 변수 참조

활동 사이에서 종료 값을 참조하기

동적 DAG 빌드

DAG 유효성 검사

반환 값

runMultiple 오류 처리

고려 사항

노트북 종료

반환 동작

관련 콘텐츠

피드백

추가 리소스