NotebookUtils notebook-kjøring og orkestrering

Bruk notatbokverktøyene til å kjøre en notatbok, kjør flere notatbøker parallelt, eller avslutt en notatbok med en verdi. Kjør følgende kommando for å få en oversikt over de tilgjengelige metodene:

notebookutils.notebook.help()

Følgende tabell viser tilgjengelige metoder for kjøring og orkestrering av notatbøker:

Metode	Signatur	Beskrivelse
`run`	`run(path: str, timeout_seconds: int = 90, arguments: dict = None, workspace: str = ""): str`	Kjører en notatbok og returnerer utgangsverdien.
`runMultiple`	`runMultiple(dag: Any, config: dict = None): dict[str, dict[str, Any]]`	Kjører flere notatbøker samtidig med støtte for avhengighetsforhold.
`validateDAG`	`validateDAG(dag: Any): bool`	Validerer om en DAG-definisjon er korrekt strukturert.
`exit`	`exit(value: str): None`	Forlater den nåværende notatboken med en verdi.

For notatblokk-CRUD-operasjoner (opprette, hent, oppdater, slett, liste), se Administrer notatblokkartefakter.

Bemerkning

Parameteren config i runMultiple() er kun tilgjengelig i Python. Scala og R støtter ikke denne parameteren.

Bemerkning

Notatblokkverktøy gjelder ikke for Apache Spark-jobbdefinisjoner (SJD).

Referere til en notatblokk

Metoden run() refererer til en notatbok og returnerer utgangsverdien. Du kan kjøre nestefunksjonskall i en notatblokk interaktivt eller i et datasamlebånd. Notatblokken som det refereres til, kjøres i Spark-utvalget i notatblokken som kaller denne funksjonen.

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

Eksempel:

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

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

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

Returverdi

Metoden run() returnerer nøyaktig den strengen som sendes til notebookutils.notebook.exit(value) i barnenotatboken. Hvis ikke exit() kalles i barnenotatboken, returneres en tom streng ("") tilbake.

Fabric-notatbøker støtter også referanse til notatbøker på tvers av arbeidsområder ved å spesifisere arbeidsområdets 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")

Åpne snapshot-linken i celleutgangen for å inspisere referansekjøringen. Snapshot fanger opp kjøreresultater og hjelper deg å feilsøke den refererte notatboken.

Sett opp barnenotatbøker til å motta parametere

Når du oppretter en barnenotatbok som kalles via run() eller runMultiple(), sett opp en parametercelle slik at notatboken kan motta argumenter fra forelderen:

Lag en kodecelle med standardparameterverdier.
Merk cellen som en parametercelle ved å velge Mark celle som parametere i notatbokens brukergrensesnitt.
Under utførelsen erstattes parametercelleverdiene med argumentene som sendes fra forelderen.

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

Tips

Utgangsverdier er alltid strenger. Hvis du trenger en numerisk verdi i foreldreboken, konverter resultatet etter henting (for eksempel int(result)).

Vurderinger

Referansenotatblokken på tvers av arbeidsområder støttes av kjøretidsversjon 1.2 og nyere.
Hvis du bruker filene under Notebook Resource, bruker du notebookutils.nbResPath i den refererte notatblokken til å kontrollere at den peker til samme mappe som den interaktive kjøringen.
Referansekjøring gjør det mulig for underordnede notatblokker å kjøre bare hvis de bruker samme innsjøhus som den overordnede, arver den overordnede innsjøen eller ingen av dem definerer en. Utførelsen blokkeres hvis barnet spesifiserer et annet lakehouse enn foreldre-notatboken. For å omgå denne sjekken, sett useRootDefaultLakehouse: True inn argumentene.
Ikke ring notebookutils.notebook.exit(value) innenfor en blokk.try-catch Exit-kallet trer ikke i kraft når det er pakket inn i unntakshåndtering.

Referanse kjøre flere notatblokker parallelt

Bruk notebookutils.notebook.runMultiple() den til å kjøre flere notatbøker parallelt eller i en forhåndsdefinert topologisk struktur. API-et bruker en multitrådet implementering innenfor en Spark-økt, noe som betyr at refererte notatbøker deler beregningsressurser.

Med notebookutils.notebook.runMultiple()kan du:

Utfør flere notatblokker samtidig, uten å vente på at hver av dem skal fullføres.
Angi avhengighetene og rekkefølgen på kjøringen for notatblokkene, ved hjelp av et enkelt JSON-format.
Optimaliser bruken av Spark-databehandlingsressurser og reduser kostnadene for Fabric-prosjektene dine.
Vis øyeblikksbilder av hver notatblokkkjøringspost i utdataene, og feilsøk/overvåk notatblokkoppgavene på en enkel måte.
Hent avslutningsverdien for hver lederaktivitet, og bruk dem i nedstrømsoppgaver.

Løp notebookutils.notebook.help("runMultiple") for å se flere eksempler og bruksdetaljer.

Kjør en enkel liste over notatbøker

Følgende eksempel kjører en liste over notatbøker parallelt:

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

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

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

Utføringsresultatet fra rotnotatblokken er som følger:

Returverdi

Metoden runMultiple() returnerer en ordbok der hver nøkkel er aktivitetsnavnet og hver verdi er en ordbok med følgende nøkler:

exitVal: Strengen som ble returnert av barnenotatbokens exit() kall, eller en tom streng hvis exit() den ikke ble kalt.
exception: Et feilobjekt hvis aktiviteten mislyktes, eller None hvis den lyktes.

Kjør notatbøker med en DAG-struktur

Følgende eksempel kjører notatbøker i en DAG-struktur ved å bruke notebookutils.notebook.runMultiple().

# 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)

Utføringsresultatet fra rotnotatblokken er som følger:

DAG-parameterreferanse

Følgende tabell beskriver hvert felt du kan bruke i DAG-definisjonen:

Felt	Nivå	Påkrevd	Beskrivelse
`activities`	Rot	Ja	En liste over aktivitetsobjekter som definerer hvilke notatbøker som skal kjøres.
`timeoutInSeconds`	Rot	Nei	Maksimal timeout for hele DAG. Standard er 43200 (12 timer).
`concurrency`	Rot	Nei	Maksimalt antall notatbøker som kan kjøres samtidig. Standard er 3 ganger antall tilgjengelige CPU-kjerner. Sett denne verdien eksplisitt hvis du trenger strengere kontroll, eller bruk `0` for ubegrenset samtidighet.
`name`	Aktivitet	Ja	Et unikt navn på aktiviteten. Brukes til å identifisere resultater og definere avhengigheter.
`path`	Aktivitet	Ja	Notatbokens elementnavn eller sti som skal kjøres.
`timeoutPerCellInSeconds`	Aktivitet	Nei	Maksimal tidsavbrudd for hver celle i barnenotatboken. Standard er 90 sekunder.
`args`	Aktivitet	Nei	En ordbok over parametere som skal sendes til barnenotatboken.
`workspace`	Aktivitet	Nei	Arbeidsområdets navn eller ID der notatboken ligger. Som standard kjører barnenotatboken i samme arbeidsområde som den som ringer.
`retry`	Aktivitet	Nei	Antall forsøk på nytt hvis aktiviteten mislykkes. Standard er 0.
`retryIntervalInSeconds`	Aktivitet	Nei	Ventetid i sekunder mellom forsøkene på nytt. Standard er 0.
`dependencies`	Aktivitet	Nei	En liste over aktivitetsnavn som må fullføres før aktiviteten starter.

Referanseutgangsverdier mellom aktiviteter

Du kan referere til utgangsverdien til en avhengighetsaktivitet i args feltet ved å bruke uttrykket @activity() . Dette mønsteret lar deg sende data mellom notatbøker i en DAG.

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)

Tips

Bruk uttrykket @activity('activity_name').exitValue() i args feltet for å sende resultater fra én aktivitet til en annen innenfor en DAG.

Bygg en dynamisk DAG

Du kan generere DAG-strukturer programmatisk for scenarier som fan-out-prosessering på tvers av flere partisjoner:

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)

Valider en DAG

Bruk validateDAG() for å verifisere at DAG-strukturen din er gyldig før kjøring. Den fanger opp problemer som dupliserte aktivitetsnavn, manglende avhengigheter og sirkulære referanser.

notebookutils.notebook.validateDAG(DAG)

notebookutils.notebook.validateDAG(dag)

notebookutils.notebook.validateDAG(DAG)

Returverdi

Metoden validateDAG() returnerer True hvis DAG-strukturen er gyldig eller utløser et unntak hvis valideringen feiler.

Tips

Ring validateDAG() alltid på forhånd runMultiple() i produksjonsarbeidsflyter for å oppdage strukturelle feil tidlig.

Håndter kjørFlere feil

Metoden runMultiple() returnerer en ordbok der hver nøkkel er aktivitetsnavnet og hver verdi inneholder en exitVal (streng) og en exception (feilobjekt eller None). Du kan inspisere delvise resultater selv når noen aktiviteter feiler:

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']}")

Vurderinger

Parallellitetsgraden for kjøring av flere notatblokker er begrenset til den totale tilgjengelige databehandlingsressursen for en Spark-økt.
Standardantallet samtidige bærbare er 3 ganger antall tilgjengelige CPU-kjerner. Du kan tilpasse denne verdien, men overdreven parallellisme kan føre til stabilitets- og ytelsesproblemer på grunn av høyt bruk av datakraftressurser. Hvis det oppstår problemer, bør du vurdere å dele notatblokker i flere runMultiple kall eller redusere samtidigheten ved å justere samtidighetsfeltet i DAG-parameteren.
Standard timeout for hele DAG er 12 timer, og standard timeout for hver celle i en barnenotatbok er 90 sekunder. Du kan endre tidsavbruddet ved å angi feltene timeoutInSeconds og timeoutPerCellInSeconds i DAG-parameteren.
Konfigurer retry og retryIntervalInSeconds for aktiviteter som kan feile på grunn av midlertidige problemer som nettverkstidsavbrudd eller midlertidig tjenestemangel.
Parallelle notatbøker deler beregningsressurser innenfor én enkelt Spark-økt. Overvåk ressursutnyttelse for å unngå minnepress og CPU-konkurranse.

Avslutte en notatblokk

Metoden exit() avslutter en notatbok med en verdi. Du kan kjøre nestefunksjonskall i en notatblokk interaktivt eller i et datasamlebånd.

Når du kaller en exit() funksjon interaktivt fra en notatbok, kaster Fabric-notatboken et unntak, hopper over kjørende påfølgende celler, og holder Spark-økten i live.
Når du orkestrerer en notatbok i en pipeline som kaller en exit() funksjon, returneres notatbokaktiviteten med en utgangsverdi. Dette fullfører pipeline-kjøringen og stopper Spark-økten.
Når du kaller en exit() funksjon i en notatbok som refereres, stopper Fabric Spark videre kjøring av den refererte notatboken, og fortsetter å kjøre de neste cellene i hovednotatboken som kaller run() funksjonen. For eksempel: Notebook1 har tre celler og kaller en exit() funksjon i den andre cellen. Notebook2 har fem celler og ringer run(notebook1) i den tredje cellen. Når du kjører Notebook2, stopper Notebook1 ved den andre cellen når du trykker exit() på funksjonen. Notatblokk2 fortsetter å kjøre sin fjerde celle og femte celle.

notebookutils.notebook.exit("value string")

notebookutils.notebook.exit("value string")

notebookutils.notebook.exit("value string")

Returatferd

Metoden exit() returnerer ikke en verdi. Den avslutter den nåværende notatboken og sender den oppgitte strengen videre til den kallende notatboken eller pipelinen.

Bemerkning

Funksjonen exit() overskriver den nåværende celleutgangen. Hvis du vil unngå å miste utdataene fra andre kodesetninger, kaller du notebookutils.notebook.exit() i en egen celle.

Viktig!

Ikke ring notebookutils.notebook.exit() innenfor en blokk.try-catch Utgangen trer ikke i kraft når den er innpakket i Exception Handling. Samtalen exit() må være på øverste nivå i koden din for å fungere riktig.

Eksempel:

Sample1-notatboken har følgende to celler:

Celle 1 definerer en inngangsparameter med standardverdi satt til 10.
Celle 2 avslutter notatblokken med inndata som utgangsverdi.

Du kan kjøre Sample1 i en annen notatblokk med standardverdier:

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

Output:

Du kan kjøre Sample1 i en annen notatblokk og angi inndataverdien til 20:

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

Output:

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2026-04-02

Del via

NotebookUtils notebook-kjøring og orkestrering

Referere til en notatblokk

Returverdi

Sett opp barnenotatbøker til å motta parametere

Vurderinger

Referanse kjøre flere notatblokker parallelt

Kjør en enkel liste over notatbøker

Returverdi

Kjør notatbøker med en DAG-struktur

DAG-parameterreferanse

Referanseutgangsverdier mellom aktiviteter

Bygg en dynamisk DAG

Valider en DAG

Returverdi

Håndter kjørFlere feil

Vurderinger

Avslutte en notatblokk

Returatferd

Relatert innhold

Tilbakemeldinger

Flere ressurser