NotebookUtils (tidligere MSSparkUtils) til Fabric

Notebook Utilities (NotebookUtils) er en indbygget pakke, der hjælper dig med nemt at udføre almindelige opgaver i Fabric Notebook. Du kan bruge NotebookUtils til at arbejde med filsystemer, til at hente miljøvariabler, til at sammenkæde notesbøger og til at arbejde med hemmeligheder. NotebookUtils-pakken er tilgængelig i PySpark (Python) Scala, SparkR-notesbøger og Fabric-pipelines.

Note

MsSparkUtils er officielt omdøbt til NotebookUtils. Den eksisterende kode forbliver bagudkompatibel og forårsager ingen ændringer i baggrunden. Det anbefales kraftigt at opgradere til notebookutils for at sikre fortsat support og adgang til nye funktioner. Navneområdet mssparkutils udgår i fremtiden.
NotebookUtils er udviklet til at fungere sammen med Spark 3.4(Runtime v1.2) og nyere. Alle nye funktioner og opdateringer understøttes udelukkende med navneområdet notebookutils fremover.

Filsystemværktøjer

notebookutils.fs indeholder værktøjer til at arbejde med forskellige filsystemer, herunder Azure Data Lake Storage (ADLS) Gen2 og Azure Blob Storage. Sørg for at konfigurere adgang til Azure Data Lake Storage Gen2 og Azure Blob Storage korrekt.

Kør følgende kommandoer for at få en oversigt over de tilgængelige metoder:

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 sammen med filsystemet på samme måde som Spark-API'er. Tag notebookutils.fs.mkdirs() og Fabric lakehouse-brug for eksempel:

Usage	Relativ sti fra HDFS-rod	Absolut sti til ABFS-filsystem	Absolut sti til lokalt filsystem i drivernoden
Ikke-standard søhus	Ikke understøttet	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("fil:/<new_dir>")
Standard søhus	Mappe under 'Filer' eller 'Tabeller': notebookutils.fs.mkdirs("Files/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("fil:/<new_dir>")

For lakehouse-standarden er filstierne tilsluttet i notesbogen med en standardtimeout for filcachen på 120 sekunder. Det betyder, at filer cachelagres i notesbogens lokale midlertidige mappe i 120 sekunder, selvom de fjernes fra Lakehouse. Hvis du vil ændre timeoutreglen, kan du afbryde standardstierne til Lakehouse-filer og tilknytte dem igen med en anden fileCacheTimeout-værdi .
For ikke-standard Lakehouse-konfigurationer kan du indstille den relevante fileCacheTimeout-parameter under monteringen af Lakehouse-stierne. Hvis timeout angives til 0, sikrer du, at den nyeste fil hentes fra Lakehouse-serveren.

Liste filer

Hvis du vil angive indholdet af en mappe, skal du bruge notebookutils.fs.ls('Din mappesti'). 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 anderledes, når du bruger en relativ sti, afhængigt af notesbogtypen.

I en Spark-notesbog: Den relative sti er relativ i forhold til Standard Lakehouses ABFSS-sti. notebookutils.fs.ls("Files") peger f.eks. på mappen Files i standardmappen Lakehouse.

For eksempel:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
I en Python-notesbog: Den relative sti er i forhold til det lokale filsystems arbejdsmappe, som som standard er /home/trusted-service-user/work. Derfor skal du bruge den fulde sti i stedet for en relativ sti notebookutils.fs.ls("/lakehouse/default/Files") til at få adgang til den Files mappe i Standard Lakehouse.

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

Vis filegenskaber

Denne metode returnerer filegenskaber, herunder filnavn, filsti, filstørrelse, og om det er en mappe 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)

Opret en ny mappe

Denne metode opretter den angivne mappe, hvis den ikke findes, og opretter 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 metode kopierer en fil eller mappe og understøtter kopieringsaktivitet på tværs af filsystemer. Vi indstillede recurse=True os til at kopiere alle filer og mapper rekursivt.

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

Note

På grund af de begrænsninger for OneLake-genvejen, anbefales det at bruge en tilsluttet sti i stedet for en abfss-sti, når du har brug for at bruge notebookutils.fs.cp() til at kopiere data fra genvejstypen S3/GCS.

Kopifil med effektiv udførelse

Denne metode giver en mere effektiv tilgang til kopiering eller flytning af filer, især når du arbejder med store datamængder. For forbedret ydeevne på Fabric anbefales det at bruge fastcp som en erstatning for den traditionelle cp metode.

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

Overvejelser:

notebookutils.fs.fastcp() understøtter ikke kopiering af filer i OneLake på tværs af områder. I dette tilfælde kan du bruge notebookutils.fs.cp() i stedet.
På grund af de begrænsninger for OneLake-genvejen, anbefales det at bruge en tilsluttet sti i stedet for en abfss-sti, når du har brug for at bruge notebookutils.fs.fastcp() til at kopiere data fra genvejstypen S3/GCS.

Vis filindhold

Denne metode returnerer op til de første 'maxBytes' byte i den angivne fil som en streng, der er kodet i UTF-8.

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

Flyt fil

Denne metode flytter en fil eller mappe og understøtter flytninger på tværs af 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.

Skriv fil

Denne metode skriver den angivne streng ud til en fil, der er 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

Føj indhold til en fil

Denne metode føjer den angivne streng til en fil, der er 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

Overvejelser:

notebookutils.fs.append() og notebookutils.fs.put() understøtter ikke samtidig skrivning til den samme fil på grund af manglende atomiske garantier.
Når du bruger api'en notebookutils.fs.append i en for-løkke til at skrive til den samme fil, anbefaler vi, at du tilføjer en sleep sætning omkring 0,5 s ~ 1 s mellem de tilbagevendende skrivninger. Denne anbefaling skyldes, at notebookutils.fs.append API'ens interne flush handling er asynkron, så en kort forsinkelse hjælper med at sikre dataintegritet.

Slet fil eller mappe

Denne metode fjerner en fil eller mappe. Vi indstiller recurse=True os til at fjerne alle filer og mapper rekursivt.

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

Monter/afmonter mappe

Du kan finde flere oplysninger om detaljeret brug i Filtilslut og fjern forbindelse.

Hjælpeprogrammer til bærbare pc'er

Brug hjælpeprogrammerne til notesbog til at køre en notesbog eller afslutte en notesbog med en værdi. Kør følgende kommando for at få en oversigt over de tilgængelige metoder:

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

Hjælpeprogrammer til notesbøger er ikke relevante for Apache Spark-jobdefinitioner (SJD).

Reference til en notesbog

Denne metode refererer til en notesbog og returnerer dens afslutningsværdi. Du kan køre indlejrede funktionskald i en notesbog interaktivt eller i en pipeline. Den notesbog, der refereres til, kører på Spark-gruppen for den notesbog, der kalder denne funktion.

notebookutils.notebook.run("notebook name", <timeoutSeconds>, <parameterMap>, <workspaceId>)

For eksempel:

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

Fabric notesbog understøtter også referering af notesbøger på tværs af flere arbejdsområder ved at angive arbejdsområde-id'et.

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

Du kan åbne snapshotlinket for referencekørslen i celleoutputtet. Snapshottet henter resultaterne af kodekørsel og giver dig mulighed for nemt at foretage fejlfinding af en referencekørsel.

Overvejelser:

Referencenotesbogen på tværs af arbejdsområder understøttes af runtime version 1.2 og nyere.
Hvis du bruger filerne under Notebook-ressource, skal du bruge notebookutils.nbResPath den notesbog, der refereres til, i den notesbog, der refereres til, for at sikre, at den peger på den samme mappe som den interaktive kørsel.
Referencekørsel gør det kun muligt for underordnede notesbøger at køre, hvis de bruger det samme søhus som det overordnede, arver det overordnede søhus, eller ingen af dem definerer et. Udførelsen blokeres, hvis den underordnede angiver et andet søhus til en overordnet notesbog. Hvis du vil tilsidesætte denne kontrol, skal du indstille useRootDefaultLakehouse: True.

Referencen kører flere notesbøger parallelt

notebookutils.notebook.runMultiple() Metoden giver dig mulighed for at køre flere notesbøger parallelt eller med en foruddefineret topologisk struktur. API'en bruger en multitrådsimplementeringsmekanisme i en spark-session, hvilket betyder, at kørselerne af referencenotesbogen deler beregningsressourcerne.

Med notebookutils.notebook.runMultiple()kan du:

Udfør flere notesbøger samtidigt uden at vente på, at hver enkelt afsluttes.
Angiv afhængighederne og rækkefølgen af udførelsen af dine notesbøger ved hjælp af et simpelt JSON-format.
Optimer brugen af Spark-beregningsressourcer, og reducer omkostningerne ved dine Fabric-projekter.
Få vist snapshots af hver notesbogs kørselspost i outputtet, og foretag en nem fejlfinding/overvågning af dine opgaver i notesbogen.
Hent afslutningsværdien for hver lederaktivitet, og brug dem i downstream-opgaver.

Du kan også prøve at køre notebookutils.notebook.help("runMultiple") for at finde eksemplet og detaljeret brug.

Her er et simpelt eksempel på kørsel af en liste over notesbøger parallelt ved hjælp af denne metode:

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

Udførelsesresultatet fra rodnotesbogen er som følger:

Her er et eksempel på kørsel af notesbøger med topologisk struktur ved hjælp af notebookutils.notebook.runMultiple(). Brug denne metode til nemt at orkestrere notesbøger via en kodeoplevelse.

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

Udførelsesresultatet fra rodnotesbogen er som følger:

Vi angiver også en metode til at kontrollere, om DAG er korrekt defineret.

notebookutils.notebook.validateDAG(DAG)

Overvejelser:

Parallelitetsgraden for kørsel af flere notesbøger er begrænset til den samlede tilgængelige beregningsressource for en Spark-session.
Standardantallet af samtidige notesbøger er 50 for Spark-notesbog, mens det som standard er 25 for Python Notebook. Du kan tilpasse denne værdi, men overdreven parallelitet kan føre til problemer med stabilitet og ydeevne på grund af højt forbrug af beregningsressourcer. Hvis der opstår problemer, kan du overveje at opdele notesbøger i flere runMultiple kald eller reducere samtidigheden ved at justere samtidighedsfeltet i parameteren DAG.
Standardtime out for hele DAG er 12 timer, og standardtime-out for hver celle i den underordnede notesbog er 90 sekunder. Du kan ændre timeout ved at angive felterne timeoutInSeconds og timeoutPerCellInSeconds i parameteren DAG.

Afslut en notesbog

Denne metode afslutter en notesbog med en værdi. Du kan køre indlejrede funktionskald i en notesbog interaktivt eller i en pipeline.

Når du kalder en exit() -funktion fra en notesbog interaktivt, udløser Fabric-notesbogen en undtagelse, springer over at køre efterfølgende celler og holder Spark-sessionen i live.
Når du organiserer en notesbog i en pipeline, der kalder en exit()-funktion, returneres notesbogaktiviteten med en afslutningsværdi. Dette fuldfører pipelinekørslen og stopper Spark-sessionen.
Når du kalder en exit() -funktion i en notesbog, der refereres til, stopper Fabric Spark den videre udførelse af den notesbog, der refereres til, og fortsætter med at køre de næste celler i den primære notesbog, der kalder run() -funktionen. For eksempel: Notebook1 har tre celler og kalder en exit() -funktion i den anden celle. Notebook2 har fem celler og kalder run(notebook1) i den tredje celle. Når du kører Notebook2, stopper Notebook1 ved den anden celle, når du trykker på exit() -funktionen. Notebook2 fortsætter med at køre den fjerde celle og femte celle.

notebookutils.notebook.exit("value string")

Note

Funktionen exit() overskriver det aktuelle celleoutput. Hvis du vil undgå at miste outputtet fra andre kodesætninger, skal du kalde notebookutils.notebook.exit() i en separat celle.

For eksempel:

Eksempel1 notesbog med følgende to celler:

Celle 1 definerer en inputparameter med standardværdien indstillet til 10.
Celle 2 afslutter notesbogen med input som udgangsværdi.

Du kan køre Sample1 i en anden notesbog med standardværdier:

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

Output:

Notebook is executed successfully with exit value 10

Du kan køre Sample1 i en anden notesbog og angive inputværdien som 20:

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

Output:

Notebook is executed successfully with exit value 20

Administrer notesbogartefakter

notebookutils.notebook indeholder specialiserede hjælpeprogrammer til programmering af elementer i notesbogen. Disse API'er kan hjælpe dig med nemt at oprette, hente, opdatere og slette elementer i notesbogen.

Hvis du vil bruge disse metoder effektivt, skal du overveje følgende anvendelseseksempler:

Oprettelse af en notesbog

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

Hentning af indhold i en notesbog

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

Opdaterer en notesbog

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

Sletning af en notesbog

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

Liste over notesbøger i et arbejdsområde

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

UdF-hjælpeprogrammer (User Data Function)

notebookutils.udf indeholder hjælpeprogrammer, der er udviklet til integration af notesbogkode med UDF'er (User Data Functions). Disse hjælpeprogrammer giver dig adgang til funktioner fra et UDF-element i det samme arbejdsområde eller på tværs af forskellige arbejdsområder. Du kan derefter aktivere funktioner i et UDF-element efter behov.

Her er nogle eksempler på, hvordan du bruger UDF-værktøjerne:

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

Hent funktioner 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")

Aktivere en funktion

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

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

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

Vis oplysninger om et UDF-element

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Vis funktionsoplysninger for en UDF

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Værktøjer til legitimationsoplysninger

Du kan bruge hjælpeprogrammerne til legitimationsoplysninger til at få adgangstokens og administrere hemmeligheder i en Azure Key Vault.

Kør følgende kommando for at få en oversigt over de tilgængelige metoder:

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

Hent token

getToken returnerer et Microsoft Entra-token for en given målgruppe og et givet navn (valgfrit). På følgende liste vises de målgruppenøgler, der er tilgængelige i øjeblikket:

Ressource for lagermålgruppe: "lager"
Power BI-ressource: "pbi"
Azure Key Vault-ressource: "keyvault"
Synapse RTA KQL DB-ressource: "kusto"

Kør følgende kommando for at hente tokenet:

notebookutils.credentials.getToken('audience Key')

Overvejelser:

Token-omfang med 'pbi' som målgruppe kan ændre sig over tid. Følgende områder understøttes i øjeblikket.
Når du kalder notebookutils.credentials.getToken("pbi")), har det returnerede token begrænset omfang, hvis notesbogen kører under en tjenesteprincipal. Tokenet har ikke det fulde Fabric-tjenesteomfang. Hvis notesbogen kører under brugeridentiteten, har tokenet stadig det fulde Fabric-tjenesteomfang, men dette kan ændre sig med sikkerhedsforbedringer. Hvis du vil sikre, at tokenet har det fulde Fabric-tjenesteomfang, skal du bruge MSAL-godkendelse i stedet for notebookutils.credentials.getToken-API'en . Du kan finde flere oplysninger under Godkend med Microsoft Entra ID.
Følgende er listen over områder, som tokenet har, når du kalder notebookutils.credentials.getToken med målgruppenøglen pbi under tjenesteprincipalidentiteten:
- Lakehouse.ReadWrite.All
- MLExperiment.ReadWrite.All
- MLModel.ReadWrite.All
- Notebook.ReadWrite.All
- SparkJobDefinition.ReadWrite.All
- Workspace.ReadWrite.All
- Dataset.ReadWrite.All

Bliv hemmelig

getSecret returnerer en Azure Key Vault-hemmelighed for et givet Azure Key Vault-slutpunkt og et hemmeligt navn ved hjælp af brugerlegitimationsoplysninger.

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

Filtilslut og fjern forbindelse

Fabric understøtter følgende monteringsscenarier i Pakken Microsoft Spark Utilities. Du kan bruge API'erne mount, unmount, getMountPath() og mounts() til at knytte fjernlager (ADLS Gen2) til alle arbejdsnoder (drivernoder og arbejdsnoder). Når lagertilslutpunktet er på plads, skal du bruge API'en for den lokale fil til at få adgang til data, som om de er gemt i det lokale filsystem.

Sådan monterer du en ADLS Gen2-konto

I følgende eksempel illustreres det, hvordan du monterer Azure Data Lake Storage Gen2. Montering af Blob Storage og Azure File Share fungerer på samme måde.

I dette eksempel antages det, at du har én Data Lake Storage Gen2-konto med navnet storegen2, som har en objektbeholder med navnet mycontainer , som du vil tilknytte til /test i din Spark-session i notesbogen.

For at montere containeren kaldet mycontainer, skal notebookutils først kontrollere, om du har tilladelse til at få adgang til containeren. I øjeblikket understøtter Fabric to godkendelsesmetoder til udløsertilslutningshandlingen: accountKey og sastoken.

Opret forbindelse via et signaturtoken eller en kontonøgle med delt adgang

NotebookUtils understøtter eksplicit overførsel af en kontonøgle eller SAS-token (Shared Access Signature) som en parameter for at montere destinationen.

Af sikkerhedsmæssige årsager anbefaler vi, at du gemmer kontonøgler eller SAS-tokens i Azure Key Vault (som vist på følgende skærmbillede). Du kan derefter hente dem ved hjælp af notebookutils.credentials.getSecret-API'en . Du kan få flere oplysninger om Azure Key Vault under Om administrerede lagerkontonøgler i 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}
)

Parametre for montering:

fileCacheTimeout: Blobs cachelagres som standard i den lokale midlertidige mappe i 120 sekunder. I denne periode kontrollerer blobfuse ikke, om filen er opdateret eller ej. Parameteren kan indstilles til at ændre standardtidspunktet for timeout. Når flere klienter ændrer filer på samme tid for at undgå uoverensstemmelser mellem lokale filer og fjernfiler, anbefaler vi, at du forkorter cachetiden eller endda ændrer den til 0 og altid henter de nyeste filer fra serveren.
timeout: Timeout for tilslutningshandlingen er som standard 120 sekunder. Parameteren kan indstilles til at ændre standardtidspunktet for timeout. Når der er for mange eksekveringsforetagender, eller når der opstår timeout for tilslutning, anbefaler vi, at værdien øges.

Du kan bruge disse parametre på følgende måde:

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

Note

Af sikkerhedsmæssige årsager anbefales det at undgå at integrere legitimationsoplysninger direkte i kode. Hvis du vil beskytte dine legitimationsoplysninger yderligere, bliver alle hemmeligheder, der vises i notesbøger, redigeret. Du kan finde flere oplysninger under Hemmelig redigering.

Sådan monterer du et lakehouse

Eksempelkode til montering af et lakehouse i /<mount_name>:

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

Få adgang til filer under monteringspunktet ved hjælp af notebookutils fs API

Det primære formål med tilslutningshandlingen er at give kunderne adgang til de data, der er gemt på en fjernlagerkonto, med en API til et lokalt filsystem. Du kan også få adgang til dataene ved hjælp af notebookutils fs API med en monteret sti som parameter. Dette stiformat er lidt anderledes.

Antag, at du har monteret Data Lake Storage Gen2-objektbeholderen mycontainer til /test ved hjælp af tilslutnings-API'en. Når du får adgang til dataene med en API til et lokalt filsystem, er stiformatet som følger:

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

Når du vil have adgang til dataene ved hjælp af notebookutils fs API, anbefaler vi, at du bruger getMountPath() til at få den nøjagtige sti:

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

Liste over mapper:

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

Læs filindhold:

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

Opret en mappe:

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

Få adgang til filer under tilslutningspunktet via lokal sti

Du kan nemt læse og skrive filerne på tilslutningspunktet ved hjælp af standardfilsystemet. 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"))

Sådan kontrollerer du eksisterende tilslutningspunkter

Du kan bruge notebookutils.fs.mounts() API til at kontrollere alle eksisterende oplysninger om tilslutningspunkter:

notebookutils.fs.mounts()

Sådan frakobles tilslutningspunktet

Brug følgende kode til at afmontere dit monteringspunkt (/test i dette eksempel):

notebookutils.fs.unmount("/test")

Kendte begrænsninger

Den aktuelle montering er en konfiguration på jobniveau; Vi anbefaler, at du bruger mounts API til at kontrollere, om der findes et mount-punkt eller ikke er tilgængeligt.
Unmount-mekanismen anvendes ikke automatisk. Når kørslen af programmet er fuldført, skal du eksplicit kalde en UNmount API i din kode for at fjerne tilslutningspunktet og frigøre diskplads. Ellers findes tilslutningspunktet stadig i noden, når programkørslen er fuldført.
Det understøttes ikke at oprette en ADLS Gen1-lagerkonto.

Lakehouse forsyningsselskaber

notebookutils.lakehouse leverer hjælpeprogrammer, der er skræddersyet til administration af Lakehouse-elementer. Disse hjælpeprogrammer giver dig mulighed for nemt at oprette, hente, opdatere og slette Lakehouse-artefakter.

Oversigt over metoder

Her er en oversigt over de tilgængelige metoder, der leveres af 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å brug

Hvis du vil bruge disse metoder effektivt, skal du overveje følgende anvendelseseksempler:

Oprettelse af 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})

Sådan får du et lakehouse

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

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

Opdatering af et lakehouse

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

Sletning af et Lakehouse

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

Liste over lakehouses i et arbejdsområde

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

Viser alle tabeller i et lakehouse

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

Starter en handling for en indlæsningstabel i en 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")

Yderligere oplysninger

Du kan finde flere detaljerede oplysninger om hver metode og dens parametre ved at bruge funktionen notebookutils.lakehouse.help("methodName") .

Runtime-værktøjer

Vis oplysninger om sessionskontekst

Med notebookutils.runtime.context kan du hente kontekstoplysningerne for den aktuelle livesession, herunder notesbogens navn, standard lakehouse, arbejdsområdeoplysninger, hvis det er en pipelinekørsel osv.

notebookutils.runtime.context

I følgende tabel beskrives egenskaberne.

Parameter	Explanation
`currentNotebookName`	Navnet på den aktuelle notesbog
`currentNotebookId`	Det entydige id for den aktuelle notesbog
`currentWorkspaceName`	Navnet på det aktuelle arbejdsområde
`currentWorkspaceId`	Id'et for det aktuelle arbejdsområde
`defaultLakehouseName`	Det viste navn på standard lakehouse, hvis det er defineret
`defaultLakehouseId`	Id'et for standardsøhuset, hvis det er defineret
`defaultLakehouseWorkspaceName`	Navnet på arbejdsområdet for standard lakehouse, hvis det er defineret
`defaultLakehouseWorkspaceId`	Arbejdsområde-id'et for standard lakehouse, hvis det er defineret
`currentRunId`	I en referencekørsel er det aktuelle kørsels-id
`parentRunId`	I en referencekørsel med indlejrede kørsler er dette id det overordnede kørsels-id
`rootRunId`	I en referencekørsel med indlejrede kørsler er dette id rodkørsels-id'et
`isForPipeline`	Om kørslen er for en pipeline
`isReferenceRun`	Om den aktuelle kørsel er en referencekørsel
`referenceTreePath`	Træstrukturen for indlejrede referencekørsler, der kun bruges til snapshothierarkiet på overvågnings-L2-siden
`rootNotebookId`	(Kun i referencekørsel) Id'et for rodnotesbogen i en referencekørsel.
`rootNotebookName`	(Kun i referencekørsel) Navnet på rodnotesbogen i en referencekørsel.
`rootWorkspaceId`	(Kun i referencekørsel) Arbejdsområde-id'et for rodnotesbogen i en referencekørsel.
`rootWorkspaceName`	(Kun i referencekørsel) Navnet på arbejdsområdet for rodnotesbogen i en referencekørsel.
`activityId`	Livy-job-id'et for den aktuelle aktivitet
`hcRepId`	REPL-id'et i tilstanden Høj samtidighed
`clusterId`	Identiteten af Synapse Spark-klyngen
`poolName`	Navnet på den Spark-gruppe, der bruges
`environmentId`	Det miljø-id, hvor jobbet kører
`environmentWorkspaceId`	Arbejdsområde-id'et for miljøet
`userId`	Bruger-id'et for den aktuelle bruger
`userName`	Brugernavnet på den aktuelle bruger

Administration af sessioner

Stop en interaktiv session

I stedet for at klikke manuelt på stopknappen er det nogle gange mere praktisk at stoppe en interaktiv session ved at kalde en API i koden. I sådanne tilfælde leverer vi en API-notebookutils.session.stop(), der understøtter stop af den interaktive session via kode, den er tilgængelig for Scala og PySpark.

notebookutils.session.stop()

notebookutils.session.stop() API stopper den aktuelle interaktive session asynkront i baggrunden. Det stopper også Spark-sessionen og frigiver ressourcer, der er optaget af sessionen, så de er tilgængelige for andre sessioner i den samme gruppe.

Genstart Python-fortolkeren

notebookutils.session utility giver dig mulighed for at genstarte Python-fortolkeren.

notebookutils.session.restartPython()

Overvejelser:

I kørselscasen for notesbogreferencen genstarter restartPython() kun Python-fortolkeren for den aktuelle notesbog, der refereres til.
I sjældne tilfælde kan kommandoen mislykkes på grund af Spark-refleksionsmekanismen, og tilføjelse af forsøg kan afhjælpe problemet.

Hjælpeprogrammer til variabelbiblioteker

Note

"Hjælpeprogrammer til variabelbibliotek" i notesbøger vises som prøveversion.

Med variabelbiblioteker kan du undgå hardcoding-værdier i notesbogkoden. Du kan opdatere værdierne i biblioteket i stedet for at ændre koden. Notesbogen refererer til variabelbiblioteket for at hente disse værdier. Denne fremgangsmåde forenkler genbrug af kode på tværs af teams og projekter ved at bruge et centralt administreret bibliotek.

Kør følgende kommandoer for at få en oversigt over de tilgængelige metoder:

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 variablen i variabelbiblioteket

Definer variablerne først, før du bruger notebookutils.variableLibrary.

Hent variabelbiblioteket fra notesbogen

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 brug af variablen.

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å adgang til en enkelt variabel efter reference

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

API'en notebookutils.variableLibrary understøtter kun adgang til variabelbiblioteker i det samme arbejdsområde.
Hentning af variabelbiblioteker på tværs af arbejdsområder understøttes ikke i underordnede notesbøger under en referencekørsel.
Notesbogkoden refererer til de variabler, der er defineret i det aktive værdisæt i variabelbiblioteket.

Kendte problemer

Når du bruger kørselsversion over 1.2 og kører notebookutils.help(), vil de anførte fabricClient, PBIClient API'er understøttes ikke i øjeblikket, være tilgængelige i det yderste. Derudover understøttes API'en til legitimationsoplysninger ikke i Scala-notesbøger i øjeblikket.
Python-notesbogen understøtter ikke stop, restartPython-API'er , når du bruger notebookutils.session værktøj til sessionsadministration.
SPN understøttes i øjeblikket ikke for variable biblioteksværktøjer.

Feedback

Var denne side nyttig?

Last updated on 2025-09-20

Del via

NotebookUtils (tidligere MSSparkUtils) til Fabric

Filsystemværktøjer

Liste filer

Vis filegenskaber

Opret en ny mappe

Kopier fil

Kopifil med effektiv udførelse

Vis filindhold

Flyt fil

Skriv fil

Føj indhold til en fil

Slet fil eller mappe

Monter/afmonter mappe

Hjælpeprogrammer til bærbare pc'er

Reference til en notesbog

Referencen kører flere notesbøger parallelt

Afslut en notesbog

Administrer notesbogartefakter

Oprettelse af en notesbog

Hentning af indhold i en notesbog

Opdaterer en notesbog

Sletning af en notesbog

Liste over notesbøger i et arbejdsområde

UdF-hjælpeprogrammer (User Data Function)

Hent funktioner fra en UDF

Aktivere en funktion

Vis oplysninger om et UDF-element

Vis funktionsoplysninger for en UDF

Værktøjer til legitimationsoplysninger

Hent token

Bliv hemmelig

Filtilslut og fjern forbindelse

Sådan monterer du en ADLS Gen2-konto

Opret forbindelse via et signaturtoken eller en kontonøgle med delt adgang

Sådan monterer du et lakehouse

Få adgang til filer under monteringspunktet ved hjælp af notebookutils fs API

Få adgang til filer under tilslutningspunktet via lokal sti

Sådan kontrollerer du eksisterende tilslutningspunkter

Sådan frakobles tilslutningspunktet

Kendte begrænsninger

Lakehouse forsyningsselskaber

Oversigt over metoder

Eksempler på brug

Oprettelse af et lakehouse

Sådan får du et lakehouse

Opdatering af et lakehouse

Sletning af et Lakehouse

Liste over lakehouses i et arbejdsområde

Viser alle tabeller i et lakehouse

Starter en handling for en indlæsningstabel i en Lakehouse

Yderligere oplysninger

Runtime-værktøjer

Vis oplysninger om sessionskontekst

Administration af sessioner

Stop en interaktiv session

Genstart Python-fortolkeren

Hjælpeprogrammer til variabelbiblioteker

Definer variablen i variabelbiblioteket

Hent variabelbiblioteket fra notesbogen

Få adgang til en enkelt variabel efter reference

Kendte problemer

Relateret indhold

Feedback

Yderligere ressourcer