NotebookUtils (tidligere MSSparkUtils) for Fabric

Notebook Utilities (NotebookUtils) er en innebygd pakke som gjør det enkelt å utføre vanlige oppgaver i Fabric Notebook. Du kan bruke NotebookUtils til å arbeide med filsystemer, få miljøvariabler, kjede notatblokker sammen og til å arbeide med hemmeligheter. NotebookUtils-pakken er tilgjengelig i PySpark (Python) Scala, SparkR-notatblokker og Fabric-rørledninger.

Note

MsSparkUtils er offisielt omdøpt til NotebookUtils. Den eksisterende koden forblir bakoverkompatibel og forårsaker ingen brytende endringer. Det anbefales på det sterkeste å oppgradere til notebookutils for å sikre fortsatt støtte og tilgang til nye funksjoner. Mssparkutils-navneområdet vil bli trukket tilbake i fremtiden.
NotebookUtils er utformet for å fungere med Spark 3.4 (Runtime v1.2) og nyere. Alle nye funksjoner og oppdateringer støttes utelukkende med navneområdet notebookutils fremover.

Filsystemverktøy

notebookutils.fs tilbyr verktøy for å jobbe med ulike filsystemer, inkludert Azure Data Lake Storage (ADLS) Gen2 og Azure Blob Storage. Kontroller at du konfigurerer tilgang til Azure Data Lake Storage Gen2 og Azure Blob Storage på riktig måte.

Kjør følgende kommandoer for en oversikt over de tilgjengelige metodene:

notebookutils.fs.help()

Output

notebookutils.fs provides utilities for working with various FileSystems.

Below is overview about the available methods:

cp(from: String, to: String, recurse: Boolean = false): Boolean -> Copies a file or directory, possibly across FileSystems
fastcp(from: String, to: String, recurse: Boolean = true): Boolean -> Copies a file or directory via azcopy, possibly across FileSystems
mv(from: String, to: String, createPath: Boolean = false, overwrite: Boolean = false): Boolean -> Moves a file or directory, possibly across FileSystems
ls(dir: String): Array -> Lists the contents of a directory
mkdirs(dir: String): Boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
put(file: String, contents: String, overwrite: Boolean = false): Boolean -> Writes the given String out to a file, encoded in UTF-8
head(file: String, maxBytes: int = 1024 * 100): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
append(file: String, content: String, createFileIfNotExists: Boolean): Boolean -> Append the content to a file
rm(dir: String, recurse: Boolean = false): Boolean -> Removes a file or directory
exists(file: String): Boolean -> Check if a file or directory exists
mount(source: String, mountPoint: String, extraConfigs: Map[String, Any]): Boolean -> Mounts the given remote storage directory at the given mount point
unmount(mountPoint: String): Boolean -> Deletes a mount point
mounts(): Array[MountPointInfo] -> Show information about what is mounted
getMountPath(mountPoint: String, scope: String = ""): String -> Gets the local path of the mount point

Use notebookutils.fs.help("methodName") for more info about a method.

NotebookUtils fungerer med filsystemet på samme måte som Spark API-er. Ta notebookutils.fs.mkdirs() og Fabric lakehouse-bruk for eksempel:

Usage	Relativ bane fra HDFS-rot	Absolutt bane for ABFS-filsystem	Absolutt bane for lokalt filsystem i drivernode
Ikke-standard innsjøhus	Støttes ikke	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("fil:/<new_dir>")
Standard innsjøhus	Katalog under Filer eller Tabeller: notebookutils.fs.mkdirs("Filer/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("fil:/<new_dir>")

For standard Lakehouse er filbaner montert i notatblokken med et standard tidsavbrudd for filhurtigbuffer på 120 sekunder. Dette betyr at filer hurtigbufres i notatblokkens lokale midlertidige mappe i 120 sekunder, selv om de fjernes fra Lakehouse. Hvis du vil endre tidsavbruddsregelen, kan du demontere standard Lakehouse-filbaner og montere dem på nytt med en annen fileCacheTimeout-verdi .
For ikke-standard Lakehouse-konfigurasjoner kan du angi riktig fileCacheTimeout-parameter under monteringen av Lakehouse-banene. Hvis du angir tidsavbruddet til 0, sikrer du at den nyeste filen hentes fra Lakehouse-serveren.

Liste filer

Hvis du vil vise innholdet i en katalog, bruker du notebookutils.fs.ls('Katalogbanen'). For eksempel:

notebookutils.fs.ls("Files/tmp") # The relatvie path may work with different base path, details in below 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # The absolute path, like: ABFS file system
notebookutils.fs.ls("file:/tmp")  # The full path of the local file system of driver node

API-en notebookutils.fs.ls() fungerer annerledes når du bruker relativ bane, avhengig av typen notatblokk.

I en Spark-notatblokk: Den relative banen er relativ til standard Lakehouses ABFSS-bane. notebookutils.fs.ls("Files") peker for eksempel til Files-katalogen i standard Lakehouse.

For eksempel:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
I en Python-notatblokk: Den relative banen er relativ til det lokale filsystemets arbeidskatalog, som som standard er /home/trusted-service-user/work. Derfor bør du bruke hele banen i stedet for en relativ bane notebookutils.fs.ls("/lakehouse/default/Files") for å få tilgang til Files katalogen i standard Lakehouse.

For eksempel:
```
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
```

Vis filegenskaper

Denne metoden returnerer filegenskaper, inkludert filnavn, filbane, filstørrelse og om det er en katalog og en fil.

files = notebookutils.fs.ls('Your directory path')
for file in files:
    print(file.name, file.isDir, file.isFile, file.path, file.size)

Opprett ny katalog

Denne metoden oppretter den angitte katalogen hvis den ikke finnes, og oppretter eventuelle nødvendige overordnede mapper.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # based on ABFS file system 
notebookutils.fs.ls("file:/<new_dir>")  # based on local file system of driver node

Kopier fil

Denne metoden kopierer en fil eller katalog, og støtter kopieringsaktivitet på tvers av filsystemer. Vi satte recurse=True til å kopiere alle filer og kataloger rekursivt.

notebookutils.fs.cp('source file or directory', 'destination file or directory', recurse=True)

Note

På grunn av begrensninger for OneLake-snarveien, når du må bruke notebookutils.fs.cp() til å kopiere data fra S3/GCS-snarveien, anbefales det å bruke en montert bane i stedet for en abfss-bane.

Performant kopieringsfil

Denne metoden gir en mer effektiv tilnærming til kopiering eller flytting av filer, spesielt når du arbeider med store datavolumer. For forbedret ytelse på Fabric, er det tilrådelig å bruke som en erstatning for den tradisjonelle fastcpcp metoden.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', recurse=True)

Hensyn:

notebookutils.fs.fastcp() støtter ikke kopiering av filer i OneLake på tvers av områder. I dette tilfellet kan du bruke notebookutils.fs.cp() i stedet.
På grunn av begrensninger for OneLake-snarveien, når du må bruke notebookutils.fs.fastcp() til å kopiere data fra S3/GCS-snarveien, anbefales det å bruke en montert bane i stedet for en abfss-bane.

Forhåndsvis filinnhold

Denne metoden returnerer opptil de første maxBytes-byte for den angitte filen som en strengkodet i UTF-8.

notebookutils.fs.head('file path', maxBytes to read)

Flytt fil

Denne metoden flytter en fil eller katalog, og støtter flyttinger på tvers av filsystemer.

notebookutils.fs.mv('source file or directory', 'destination directory', True) # Set the last parameter as True to firstly create the parent directory if it does not exist
notebookutils.fs.mv('source file or directory', 'destination directory', True, True) # Set the third parameter to True to firstly create the parent directory if it does not exist. Set the last parameter to True to overwrite the updates.

Skrive fil

Denne metoden skriver den angitte strengen ut til en fil, kodet i UTF-8.

notebookutils.fs.put("file path", "content to write", True) # Set the last parameter as True to overwrite the file if it existed already

Tilføy innhold til en fil

Denne metoden tilføyer den angitte strengen til en fil, kodet i UTF-8.

notebookutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it does not exist

Hensyn:

notebookutils.fs.append() og notebookutils.fs.put() støtter ikke samtidig skriving til samme fil på grunn av manglende atomgarantier.
Når du bruker notebookutils.fs.append API-en i en for løkke for å skrive til samme fil, anbefaler vi at du legger til en sleep setning rundt 0,5 s ~ 1 s mellom de regelmessige skrivingene. Denne anbefalingen skyldes at notebookutils.fs.append API-ens interne flush-operasjon er asynkron, så en kort forsinkelse bidrar til å sikre dataintegritet.

Slette fil eller katalog

Denne metoden fjerner en fil eller katalog. Vi satte recurse=True for å fjerne alle filer og kataloger rekursivt.

notebookutils.fs.rm('file path', recurse=True)

Monter/avmonter katalog

Finn mer informasjon om detaljert bruk i Filmontering og demontering.

Notebook-verktøy

Bruk notatblokkverktøyene til å kjøre en notatblokk eller avslutte en notatblokk med en verdi. Kjør følgende kommando for å få en oversikt over de tilgjengelige metodene:

notebookutils.notebook.help()

Output:


The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value.
run(path: String, timeoutSeconds: int, arguments: Map, workspace: String): String -> This method runs a notebook and returns its exit value.
runMultiple(DAG: Any): Map[String, MsNotebookRunResult] -> Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> This method check if the DAG is correctly defined.

Below methods are only support Fabric Notebook.
create(name: String, description: String = "", content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = ""): Artifact -> Create a new Notebook.
get(name: String, workspaceId: String = ""): Artifact -> Get a Notebook by name or id.
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact -> Update a Artifact by name.
delete(name: String, workspaceId: String = ""): Boolean -> Delete a Notebook by name.
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact] -> List all Notebooks in the workspace.
updateDefinition(name: String, content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = "") -> Update the definition of a Notebook.

Use notebookutils.notebook.help("methodName") for more info about a method.

Note

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

Referere til en notatblokk

Denne metoden refererer til en notatblokk og returnerer avslutningsverdien. 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", <timeoutSeconds>, <parameterMap>, <workspaceId>)

For eksempel:

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

Fabric notebook støtter også referanse til notatblokker på tvers av flere arbeidsområder ved å angi arbeidsområde-ID-en.

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

Du kan åpne øyeblikksbildekoblingen for referansekjøringen i celleutdataene. Øyeblikksbildet registrerer resultatene for kjøring av kode og lar deg enkelt feilsøke en referansekjøring.

Hensyn:

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 den underordnede angir et annet innsjøhus til overordnet notatblokk. Hvis du vil omgå denne kontrollen, angir useRootDefaultLakehouse: Truedu .

Referanse kjøre flere notatblokker parallelt

Med metoden notebookutils.notebook.runMultiple() kan du kjøre flere notatblokker parallelt eller med en forhåndsdefinert topologisk struktur. API-en bruker en implementeringsmekanisme med flere tråder i en spark-økt, noe som betyr at referansenotatblokken kjører, deler databehandlingsressursene.

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.

Du kan også prøve å kjøre notebookutils.notebook.help("runMultiple") for å finne eksemplet og detaljert bruk.

Her er et enkelt eksempel på hvordan du kjører en liste over notatblokker parallelt ved hjelp av denne metoden:

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

Utføringsresultatet fra rotnotatblokken er som følger:

Her er et eksempel på hvordan du kjører notatblokker med topologisk struktur ved hjelp av notebookutils.notebook.runMultiple(). Bruk denne metoden til enkelt å organisere notatblokker gjennom en kodeopplevelse.

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

Utføringsresultatet fra rotnotatblokken er som følger:

Vi tilbyr også en metode for å kontrollere om DAG er riktig definert.

notebookutils.notebook.validateDAG(DAG)

Hensyn:

Parallellitetsgraden for kjøring av flere notatblokker er begrenset til den totale tilgjengelige databehandlingsressursen for en Spark-økt.
Standard antall samtidige notatblokker er 50 for Spark-notatblokken, mens det er standard 25 for Python-notatblokken. Du kan tilpasse denne verdien, men overdreven parallellitet kan føre til stabilitets- og ytelsesproblemer på grunn av høy bruk av databehandlingsressurser. 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 tidsavbrudd for hele DAG er 12 timer, og standard tidsavbrudd for hver celle i den underordnede notatblokken er 90 sekunder. Du kan endre tidsavbruddet ved å angi feltene timeoutInSeconds og timeoutPerCellInSeconds i DAG-parameteren.

Avslutte en notatblokk

Denne metoden avslutter en notatblokk med en verdi. Du kan kjøre nestefunksjonskall i en notatblokk interaktivt eller i et datasamlebånd.

Når du kaller en exit() -funksjon fra en notatblokk interaktivt, utløser Fabric-notatblokken et unntak, hopper over å kjøre påfølgende celler og holder Spark-økten i live.
Når du orkestrerer en notatblokk i et datasamlebånd som kaller en exit()-funksjon, returneres notatblokkaktiviteten med en avslutningsverdi. Dette fullfører kjøringen av datasamlebåndet og stopper Spark-økten.
Når du kaller en exit() -funksjon i en notatblokk som det refereres til, stopper Fabric Spark den videre kjøringen av den refererte notatblokken, og fortsetter å kjøre de neste cellene i hovednotatblokken som kaller run() -funksjonen. For eksempel: Notebook1 har tre celler og kaller en exit() -funksjon i den andre cellen. Notebook2 har fem celler og kaller run(notebook1) i den tredje cellen. Når du kjører Notebook2, stopper Notebook1 ved den andre cellen når du trykker på exit() -funksjonen. Notatblokk2 fortsetter å kjøre sin fjerde celle og femte celle.

notebookutils.notebook.exit("value string")

Note

exit () -funksjonen overskriver gjeldende celleutgang. Hvis du vil unngå å miste utdataene fra andre kodesetninger, kaller du notebookutils.notebook.exit() i en egen celle.

For eksempel:

Eksempel1 notatblokk med 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:

Notebook is executed successfully with exit value 10

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:

Notebook is executed successfully with exit value 20

Behandle notatblokkartefakter

notebookutils.notebook inneholder spesialiserte verktøy for administrasjon av notatblokkelementer programmatisk. Disse API-ene kan enkelt hjelpe deg med å opprette, få, oppdatere og slette notatblokkelementer.

Hvis du vil bruke disse metodene effektivt, kan du vurdere følgende brukseksempler:

Opprette en notatblokk

with open("/path/to/notebook.ipynb", "r") as f:
    content = f.read()

artifact = notebookutils.notebook.create("artifact_name", "description", "content", "default_lakehouse_name", "default_lakehouse_workspace_id", "optional_workspace_id")

Hente innhold i en notatblokk

artifact = notebookutils.notebook.get("artifact_name", "optional_workspace_id")

Oppdatere en notatblokk

updated_artifact = notebookutils.notebook.update("old_name", "new_name", "optional_description", "optional_workspace_id")

updated_artifact_definition = notebookutils.notebook.updateDefinition("artifact_name",  "content", "default_lakehouse_name", "default_Lakehouse_Workspace_name", "optional_workspace_id")

Slette en notatblokk

is_deleted = notebookutils.notebook.delete("artifact_name", "optional_workspace_id")

Vise notatblokker i et arbeidsområde

artifacts_list = notebookutils.notebook.list("optional_workspace_id")

UDF-verktøy (User Data Function)

notebookutils.udf gir verktøy som er utformet for å integrere notatblokkkode med UDFs (User Data Functions). Disse verktøyene gir deg tilgang til funksjoner fra et UDF-element i samme arbeidsområde eller på tvers av ulike arbeidsområder. Deretter kan du aktivere funksjoner i et UDF-element etter behov.

Her er noen eksempler på hvordan du bruker UDF-verktøyene:

# Get functions from a UDF item
myFunctions = notebookutils.udf.getFunctions('UDFItemName')
# Or from another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

# Display function and item details
display(myFunctions.functionDetails)
display(myFunctions.itemDetails)

# Invoke a function
myFunctions.functionName('value1', 'value2')
# Or with named parameters
myFunctions.functionName(parameter1='value1', parameter2='value2')

Hente funksjoner fra en UDF

myFunctions = notebookutils.udf.getFunctions('UDFItemName')
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

var myFunctions = notebookutils.udf.getFunctions("UDFItemName")
var myFunctions = notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

myFunctions <- notebookutils.udf.getFunctions("UDFItemName")
myFunctions <- notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

Aktiver en funksjon

myFunctions.functionName('value1', 'value2'...)

val res = myFunctions.functionName('value1', 'value2'...)

myFunctions$functionName('value1', 'value2'...)

Vis detaljer for et UDF-element

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Vis funksjonsdetaljer for en UDF

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Legitimasjonsverktøy

Du kan bruke legitimasjonsverktøyene til å få tilgangstokener og administrere hemmeligheter i et Azure Key Vault.

Kjør følgende kommando for å få en oversikt over de tilgjengelige metodene:

notebookutils.credentials.help()

Output:

Help on module notebookutils.credentials in notebookutils:

NAME
    notebookutils.credentials - Utility for credentials operations in Fabric

FUNCTIONS
    getSecret(akvName, secret) -> str
        Gets a secret from the given Azure Key Vault.
        :param akvName: The name of the Azure Key Vault.
        :param secret: The name of the secret.
        :return: The secret value.
    
    getToken(audience) -> str
        Gets a token for the given audience.
        :param audience: The audience for the token.
        :return: The token.
    
    help(method_name=None)
        Provides help for the notebookutils.credentials module or the specified method.
        
        Examples:
        notebookutils.credentials.help()
        notebookutils.credentials.help("getToken")
        :param method_name: The name of the method to get help with.

DATA
    creds = <notebookutils.notebookutils.handlers.CredsHandler.CredsHandler...

FILE
    /home/trusted-service-user/cluster-env/trident_env/lib/python3.10/site-packages/notebookutils/credentials.py

Skaff deg token

getToken returnerer et Microsoft Entra-token for et gitt målgruppe og navn (valgfritt). Listen nedenfor viser de tilgjengelige målgruppenøklene:

Lagringsgrupperessurs: «lagring»
Power BI-ressurs: «pbi»
Azure Key Vault-ressurs: «keyvault»
Synapse RTA KQL DB-ressurs: "kusto"

Kjør følgende kommando for å hente tokenet:

notebookutils.credentials.getToken('audience Key')

Hensyn:

Tokenomfang med «pbi» som målgruppe kan endres over tid. Følgende omfang støttes for øyeblikket.
Når du kaller notebookutils.credentials.getToken("pbi")), har det returnerte tokenet begrenset omfang hvis notatblokken kjører under en tjenestekontohaver. Tokenet har ikke hele Fabric-tjenesteomfanget. Hvis notatblokken kjører under brukeridentiteten, har tokenet fortsatt hele Fabric-tjenesteomfanget, men dette kan endres med sikkerhetsforbedringer. Hvis du vil sikre at tokenet har hele Fabric-tjenesteomfanget, kan du bruke MSAL-godkjenning i stedet for notebookutils.credentials.getToken-API-en . Hvis du vil ha mer informasjon, kan du se Godkjenne med Microsoft Entra ID.
Følgende er listen over omfang som tokenet har når du kaller notebookutils.credentials.getToken med målgruppenøkkelen pbi under tjenestekontohaveridentiteten:
- Lakehouse.ReadWrite.All
- MLExperiment.ReadWrite.All
- MLModel.ReadWrite.All
- Notebook.ReadWrite.All
- SparkJobDefinition.ReadWrite.All
- Workspace.ReadWrite.All
- Dataset.ReadWrite.All

Bli hemmelig

getSecret returnerer en Azure Key Vault-hemmelighet for et gitt Azure Key Vault-endepunkt og hemmelig navn ved hjelp av brukerlegitimasjon.

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

Filmontering og demontering

Fabric støtter følgende monteringsscenarioer i Microsoft Spark Utilities-pakken. Du kan bruke API-ene mount, unmount, getMountPath() og mounts() til å knytte ekstern lagring (ADLS Gen2) til alle arbeidsnoder (drivernode og arbeidsnoder). Når lagringsmonteringspunktet er på plass, kan du bruke den lokale fil-API-en til å få tilgang til data som om den er lagret i det lokale filsystemet.

Slik monterer du en ADLS Gen2-konto

Følgende eksempel illustrerer hvordan du monterer Azure Data Lake Storage Gen2. Montering av Blob Storage og Azure File Share fungerer på lignende måte.

Dette eksemplet forutsetter at du har én Data Lake Storage Gen2-konto kalt storegen2, som har en beholder kalt mycontainer som du vil montere på /test i Spark-økten i notatblokken.

For å montere beholderen kalt mycontainer, må notebookutils først sjekke om du har tillatelse til å få tilgang til beholderen. For øyeblikket støtter Fabric to godkjenningsmetoder for utløsermonteringsoperasjonen: accountKey og sastoken.

Montere via signaturtoken for delt tilgang eller kontonøkkel

NotebookUtils støtter eksplisitt å sende en kontonøkkel eller SAS-token (Shared Access Signature) som en parameter for å montere målet.

Av sikkerhetsgrunner anbefaler vi at du lagrer kontonøkler eller SAS-tokener i Azure Key Vault (som følgende skjermbilde viser). Du kan deretter hente dem ved hjelp av notebookutils.credentials.getSecret API-en. Hvis du vil ha mer informasjon om Azure Key Vault, kan du se Om administrerte lagringskontonøkler for Azure Key Vault.

Eksempelkode for accountKey-metoden :

# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

Eksempelkode for sastoken:

# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Monter parametere:

fileCacheTimeout: Blober bufres i den lokale temp-mappen i 120 sekunder som standard. I løpet av denne tiden kontrollerer ikke blobfuse om filen er oppdatert eller ikke. Parameteren kan angis for å endre standard tidsavbrudd. Når flere klienter endrer filer samtidig, for å unngå inkonsekvenser mellom lokale og eksterne filer, anbefaler vi at du forkorter hurtigbuffertiden, eller til og med endrer den til 0, og alltid får de nyeste filene fra serveren.
tidsavbrudd: Tidsavbruddet for monteringsoperasjonen er 120 sekunder som standard. Parameteren kan angis for å endre standard tidsavbrudd. Når det er for mange eksekutorer eller når monteringen blir tidsavbrutt, anbefaler vi at du øker verdien.

Du kan bruke disse parameterne slik:

notebookutils.fs.mount(
   "abfss://mycontainer@<accountname>.dfs.core.windows.net",
   "/test",
   {"fileCacheTimeout": 120, "timeout": 120}
)

Note

For sikkerhetsformål anbefales det å unngå innebygging av legitimasjon direkte i kode. Hvis du vil beskytte legitimasjonen ytterligere, blir alle hemmeligheter som vises i notatblokkutdata, redigert. Hvis du vil ha mer informasjon, kan du se Hemmelig skjuling.

Slik monterer du et lakehouse

Eksempelkode for montering av en lakehouse til /<mount_name>:

notebookutils.fs.mount( 
 "abfss://<workspace_name>@onelake.dfs.fabric.microsoft.com/<lakehouse_name>.Lakehouse", 
 "/<mount_name>"
)

Få tilgang til filer under monteringspunktet ved hjelp av notebookutils fs API

Hovedformålet med monteringsoperasjonen er å gi kundene tilgang til dataene som er lagret i en ekstern lagringskonto med en lokal filsystem-API. Du kan også få tilgang til dataene ved hjelp av notebookutils fs API med en montert bane som parameter. Dette baneformatet er litt annerledes.

Anta at du har montert Data Lake Storage Gen2-beholderen mycontainer til /test ved hjelp av monterings-API-en. Når du får tilgang til dataene med en lokal filsystem-API, er baneformatet slik:

/synfs/notebook/{sessionId}/test/{filename}

Når du vil ha tilgang til dataene ved hjelp av notebookutils fs API, anbefaler vi at du bruker getMountPath() for å få den nøyaktige banen:

path = notebookutils.fs.getMountPath("/test")

Liste over kataloger:

notebookutils.fs.ls(f"file://{notebookutils.fs.getMountPath('/test')}")

Les filinnhold:

notebookutils.fs.head(f"file://{notebookutils.fs.getMountPath('/test')}/myFile.txt")

Opprette en katalog:

notebookutils.fs.mkdirs(f"file://{notebookutils.fs.getMountPath('/test')}/newdir")

Få tilgang til filer under monteringspunktet via lokal bane

Du kan enkelt lese og skrive filene i monteringspunktet ved hjelp av standard filsystem. Her er et Python-eksempel:

#File read
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
    print(f.read())
#File write
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
    print(f.write("dummy data"))

Slik kontrollerer du eksisterende monteringspunkter

Du kan bruke notebookutils.fs.mounts() API til å kontrollere all eksisterende informasjon om monteringspunkt:

notebookutils.fs.mounts()

Slik fjerner du monteringspunktet

Bruk følgende kode for å demontere monteringspunktet (/test i dette eksemplet):

notebookutils.fs.unmount("/test")

Kjente begrensninger

Den nåværende monteringen er en konfigurasjon på jobbnivå; Vi anbefaler at du bruker monterings-API-en for å sjekke om det finnes et monteringspunkt eller ikke er tilgjengelig.
Demonteringsmekanismen brukes ikke automatisk. Når programmet kjøres, må du eksplisitt kalle opp en umontert API i koden for å demontere monteringspunktet og frigjøre diskplassen. Ellers vil monteringspunktet fremdeles finnes i noden etter at programkjøringen er fullført.
Montering av en ADLS Gen1-lagringskonto støttes ikke.

Lakehouse-verktøy

notebookutils.lakehouse tilbyr verktøy som er skreddersydde for administrasjon av Lakehouse-gjenstander. Disse verktøyene gir deg mulighet til å opprette, få, oppdatere og slette Lakehouse-artefakter enkelt.

Oversikt over metoder

Her er en oversikt over de tilgjengelige metodene som leveres av notebookutils.lakehouse:

# Create a new Lakehouse artifact
create(name: String, description: String = "", definition: ItemDefinition = null, workspaceId: String = ""): Artifact

# Create Lakehouse with Schema Support
create(name: String, description: String = "", definition: {"enableSchemas": True}): Artifact

# Retrieve a Lakehouse artifact
get(name: String, workspaceId: String = ""): Artifact

# Get a Lakehouse artifact with properties
getWithProperties(name: String, workspaceId: String = ""): Artifact

# Update an existing Lakehouse artifact
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact

# Delete a Lakehouse artifact
delete(name: String, workspaceId: String = ""): Boolean 

# List all Lakehouse artifacts
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact]

# List all tables in a Lakehouse artifact
listTables(lakehouse: String, workspaceId: String = "", maxResults: Int = 1000): Array[Table] 

# Starts a load table operation in a Lakehouse artifact
loadTable(loadOption: collection.Map[String, Any], table: String, lakehouse: String, workspaceId: String = ""): Array[Table]

Eksempler på bruk

Hvis du vil bruke disse metodene effektivt, kan du vurdere følgende brukseksempler:

Opprette et Lakehouse

artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", "optional_workspace_id")
# Create Lakehouse with Schema Support
artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", {"enableSchemas": True})

Få et Lakehouse

artifact = notebookutils.lakehouse.get("artifact_name", "optional_workspace_id")

artifact = notebookutils.lakehouse.getWithProperties("artifact_name", "optional_workspace_id")

Oppdaterer et Lakehouse

updated_artifact = notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")

Slette et Lakehouse

is_deleted = notebookutils.lakehouse.delete("artifact_name", "optional_workspace_id")

Noter lakehouses i et arbeidsområde

artifacts_list = notebookutils.lakehouse.list("optional_workspace_id")

Liste over alle tabeller i et Lakehouse

artifacts_tables_list = notebookutils.lakehouse.listTables("artifact_name", "optional_workspace_id")

Starte en belastningstabelloperasjon i et Lakehouse

notebookutils.lakehouse.loadTable(
    {
        "relativePath": "Files/myFile.csv",
        "pathType": "File",
        "mode": "Overwrite",
        "recursive": False,
        "formatOptions": {
            "format": "Csv",
            "header": True,
            "delimiter": ","
        }
    }, "table_name", "artifact_name", "optional_workspace_id")

Tilleggsinformasjon

Hvis du vil ha mer detaljert informasjon om hver metode og dens parametere, kan du bruke notebookutils.lakehouse.help("methodName") funksjonen.

Runtime-verktøy

Vis kontekstinformasjon for økten

Med notebookutils.runtime.context deg kan du få kontekstinformasjonen for gjeldende live-økt, inkludert notatblokknavnet, standard lakehouse, arbeidsområdeinformasjon, hvis det er en datasamlebåndkjøring osv.

notebookutils.runtime.context

Tabellen nedenfor viser egenskapene.

Parameter	Explanation
`currentNotebookName`	Navnet på gjeldende notatblokk
`currentNotebookId`	Den unike ID-en for gjeldende notatblokk
`currentWorkspaceName`	Navnet på gjeldende arbeidsområde
`currentWorkspaceId`	ID-en for gjeldende arbeidsområde
`defaultLakehouseName`	Visningsnavnet for standard lakehouse, hvis definert
`defaultLakehouseId`	ID-en for standard lakehouse, hvis definert
`defaultLakehouseWorkspaceName`	Arbeidsområdenavnet for standard lakehouse, hvis definert
`defaultLakehouseWorkspaceId`	Arbeidsområde-ID-en for standard lakehouse, hvis definert
`currentRunId`	I en referansekjøring, gjeldende kjøre-ID
`parentRunId`	I en referansekjøring med nestede kjøringer er denne ID-en den overordnede kjøre-ID-en
`rootRunId`	I en referansekjøring med nestede kjøringer er denne ID-en rotkjørings-ID-en
`isForPipeline`	Om kjøringen er for et datasamlebånd
`isReferenceRun`	Om gjeldende kjøring er en referansekjøring
`referenceTreePath`	Trestrukturen for nestede referansekjøringer, som bare brukes for øyeblikksbildehierarkiet på overvåkingssiden L2
`rootNotebookId`	(Bare i referansekjøring) ID-en for rotnotatblokken i en referansekjøring.
`rootNotebookName`	(Bare i referansekjøring) Navnet på rotnotatblokken i en referansekjøring.
`rootWorkspaceId`	(Bare i referansekjøring) Arbeidsområde-ID-en for rotnotatblokken i en referansekjøring.
`rootWorkspaceName`	(Bare i referansekjøring) Arbeidsområdenavnet for rotnotatblokken i en referansekjøring.
`activityId`	Livy-jobb-ID-en for gjeldende aktivitet
`hcRepId`	REPL-ID-en i høy samtidighetsmodus
`clusterId`	Identiteten til Synapse Spark-klyngen
`poolName`	Navnet på Spark-utvalget som brukes
`environmentId`	Miljø-ID-en der jobben kjører
`environmentWorkspaceId`	Arbeidsområdets ID for miljøet
`userId`	Bruker-ID-en til gjeldende bruker
`userName`	Brukernavnet til gjeldende bruker

Administrasjon av økter

Stoppe en interaktiv økt

I stedet for å klikke stopp-knappen manuelt, er det noen ganger mer praktisk å stoppe en interaktiv økt ved å kalle en API i koden. I slike tilfeller gir vi en API-notebookutils.session.stop() for å støtte å stoppe den interaktive økten via kode, den er tilgjengelig for Scala og PySpark.

notebookutils.session.stop()

notebookutils.session.stop() API-en stopper gjeldende interaktive økt asynkront i bakgrunnen. Det stopper også Spark-økten og frigir ressurser som er opptatt av økten, slik at de er tilgjengelige for andre økter i samme utvalg.

Start Python-tolken på nytt

notebookutils.session-verktøyet gjør det mulig å starte Python-tolken på nytt.

notebookutils.session.restartPython()

Hensyn:

I referansekjøringstilfellet for notatblokken starter restartPython() bare Python-tolken for gjeldende notatblokk som det refereres til.
I sjeldne tilfeller kan kommandoen mislykkes på grunn av Spark-gjenspeilingsmekanismen. Hvis du legger til et nytt forsøk, kan problemet reduseres.

Verktøy for variabelt bibliotek

Note

«Verktøy for variabelt bibliotek» i notatblokker er i forhåndsvisning.

Med variabelbiblioteker kan du unngå hardkodingsverdier i notatblokkkoden. Du kan oppdatere verdiene i biblioteket i stedet for å endre koden. Notatblokken refererer til variabelbiblioteket for å hente disse verdiene. Denne tilnærmingen forenkler gjenbruk av kode på tvers av team og prosjekter ved å bruke et sentralt administrert bibliotek.

Kjør følgende kommandoer for en oversikt over de tilgjengelige metodene:

notebookutils.variableLibrary.help()

Output

[Preview] notebookutils.variableLibrary is a utility to Variable Library.

Below is overview about the available methods:

get(variableReference: String): String
-> Run the variable value with type.
getLibrary(variableLibraryName: String): VariableLibrary
-> Get the variable library.
Use notebookutils.variableLibrary.help("methodName") for more info about a method.

Definer variabelen i variabelbiblioteket

Definer variablene først før du bruker notebookutils.variableLibrary.

Hente variabelbiblioteket fra notatblokken

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

val samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

samplevl <- notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

Eksempel på dynamisk bruk av variabelen.

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

file_path = f"abfss://{samplevl.Workspace_name}@onelake.dfs.fabric.microsoft.com/{samplevl.Lakehouse_name}.Lakehouse/Files/<FileName>.csv" 
df = spark.read.format("csv").option("header","true").load(file_path) 

display(df)

Få tilgang til én enkelt variabel etter referanse

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

Note

notebookutils.variableLibrary API-en støtter bare tilgang til variabelbiblioteker i samme arbeidsområde.
Henting av variabelbiblioteker på tvers av arbeidsområder støttes ikke i underordnede notatblokker under en referansekjøring.
Notatblokkkoden refererer til variablene som er definert i det aktive verdisettet i variabelbiblioteket.

Kjente problemer

Når du bruker kjøretidsversjon over 1.2 og kjører notebookutils.help(), vil de oppførte fabricClient, PBIClient-API-ene støttes ikke foreløpig, være tilgjengelige i ytterligere. I tillegg støttes ikke legitimasjons-API-en i Scala-notatblokker foreløpig.
Python-notatblokken støtter ikke stop, restartPython-API-er når du bruker notebookutils.session-verktøyet for øktadministrasjon.
SPN støttes for øyeblikket ikke for variable bibliotekverktøy.

Tilbakemeldinger

Var denne siden nyttig?

Last updated on 2025-08-16

Del via

NotebookUtils (tidligere MSSparkUtils) for Fabric

Filsystemverktøy

Liste filer

Vis filegenskaper

Opprett ny katalog

Kopier fil

Performant kopieringsfil

Forhåndsvis filinnhold

Flytt fil

Skrive fil

Tilføy innhold til en fil

Slette fil eller katalog

Monter/avmonter katalog

Notebook-verktøy

Referere til en notatblokk

Referanse kjøre flere notatblokker parallelt

Avslutte en notatblokk

Behandle notatblokkartefakter

Opprette en notatblokk

Hente innhold i en notatblokk

Oppdatere en notatblokk

Slette en notatblokk

Vise notatblokker i et arbeidsområde

UDF-verktøy (User Data Function)

Hente funksjoner fra en UDF

Aktiver en funksjon

Vis detaljer for et UDF-element

Vis funksjonsdetaljer for en UDF

Legitimasjonsverktøy

Skaff deg token

Bli hemmelig

Filmontering og demontering

Slik monterer du en ADLS Gen2-konto

Montere via signaturtoken for delt tilgang eller kontonøkkel

Slik monterer du et lakehouse

Få tilgang til filer under monteringspunktet ved hjelp av notebookutils fs API

Få tilgang til filer under monteringspunktet via lokal bane

Slik kontrollerer du eksisterende monteringspunkter

Slik fjerner du monteringspunktet

Kjente begrensninger

Lakehouse-verktøy

Oversikt over metoder

Eksempler på bruk

Opprette et Lakehouse

Få et Lakehouse

Oppdaterer et Lakehouse

Slette et Lakehouse

Noter lakehouses i et arbeidsområde

Liste over alle tabeller i et Lakehouse

Starte en belastningstabelloperasjon i et Lakehouse

Tilleggsinformasjon

Runtime-verktøy

Vis kontekstinformasjon for økten

Administrasjon av økter

Stoppe en interaktiv økt

Start Python-tolken på nytt

Verktøy for variabelt bibliotek

Definer variabelen i variabelbiblioteket

Hente variabelbiblioteket fra notatblokken

Få tilgang til én enkelt variabel etter referanse

Kjente problemer

Relatert innhold

Tilbakemeldinger

Flere ressurser