NotebookUtils (tidligere MSSparkUtils) til Fabric

Artikel
12/13/2024

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.

Bemærk

MsSparkUtils er officielt omdøbt til NotebookUtils. Den eksisterende kode forbliver bagudkompatibel og medfører ingen afbrydelsesændringer. Det anbefales på det kraftigste 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 hjælpeprogrammer til 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 -> [Preview] 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 brug af notebookutils.fs.mkdirs() og Fabric lakehouse for eksempel:

Brug	Relativ sti fra HDFS-rod	Absolut sti til ABFS-filsystem	Absolut sti til lokalt filsystem i drivernoden
Ikke-standard lakehouse	Ikke understøttet	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Standard lakehouse	Mappe 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("file:/<new_dir>")

Vis filer

Hvis du vil angive indholdet af en mappe, skal du bruge notebookutils.fs.ls('Din mappesti'). Eksempler:

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.

Eksempler:
```
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.

Eksempler:
```
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

Kopiér fil

Denne metode kopierer en fil eller mappe og understøtter kopieringsaktivitet på tværs af filsystemer.

notebookutils.fs.cp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

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.

Bemærk

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.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

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

Bemærk

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,5s~1s mellem de tilbagevendende skrivninger. Det 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.

notebookutils.fs.rm('file path', True) # Set the last parameter as True to remove all files and directories recursively

Tilslut/ophæv tilslutning af mappe

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

Hjælpeprogrammer til notesbøger

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

Udgang:


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] -> [Preview] Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> [Preview] This method check if the DAG is correctly defined.

[Preview] 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.

Bemærk

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

Eksempler:

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

Stofnotesbog understøtter også henvisninger til 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.

Bemærk

Referencenotesbogen på tværs af arbejdsområder understøttes af runtime version 1.2 og nyere.
Hvis du bruger filerne under Notesbogressource, skal du bruge notebookutils.nbResPath i den notesbog, der refereres til, for at sikre, at den peger på den samme mappe som den interaktive kørsel.

Referencen kører flere notesbøger parallelt

Vigtigt

Denne funktion er en prøveversion.

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:

Følgende 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)

Bemærk

Parallelitetsgraden for kørsel af flere notesbøger er begrænset til den samlede tilgængelige beregningsressource for en Spark-session.
Den øvre grænse for notesbogaktiviteter eller samtidige notesbøger er 50. Overskridelse af denne grænse kan medføre problemer med stabilitet og ydeevne på grund af et højt forbrug af beregningsressourcer. Hvis der opstår problemer, kan du overveje at adskille notesbøger i flere runMultiple kald eller reducere samtidigheden ved at justere feltet samtidighed i DAG-parameteren.
Standardtimeout for hele DAG er 12 timer, og standardtimeouten for hver celle i den underordnede notesbog er 90 sekunder. Du kan ændre timeout ved at angive felterne timeoutInSeconds og timeoutPerCellInSeconds i DAG-parameteren.

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 efterfølgende celler over og holder Spark-sessionen i live.
Når du orkestrer en notesbog i en pipeline, der kalder en exit() -funktion, returnerer notesbogaktiviteten med en afslutningsværdi, 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 yderligere udførelse af den notesbog, der refereres til, og fortsætter med at køre de næste celler i hovednotesbogen, der kalder funktionen run(). Eksempel: Notebook1 har tre celler og kalder en exit() -funktion i den anden celle. Notebook2 har fem celler og kald run(notebook1) i den tredje celle. Når du kører Notesbog2, stopper Notebook1 ved den anden celle, når du rammer exit () -funktionen. Notebook2 fortsætter med at køre den fjerde celle og femte celle.

notebookutils.notebook.exit("value string")

Bemærk

Funktionen exit() overskriver det aktuelle celleoutput for at undgå at miste outputtet fra andre kodesætninger. Kald notebookutils.notebook.exit() i en separat celle.

Eksempler:

Eksempel1-notesbog med følgende to celler:

Celle 1 definerer en inputparameter , hvor standardværdien er angivet til 10.
Celle 2 afslutter notesbogen med input som afslutningsværdi.

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

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

Udgang:

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)

Udgang:

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

Hjælpeprogrammer 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()

Udgang:

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

Hent hemmelighed ved hjælp af brugerlegitimationsoplysninger

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 til tilslutning, afmontering, getMountPath() og mounts() til at knytte ADLS Gen2 (Remote Storage) 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 fungerer på samme måde.

I dette eksempel antages det, at du har én Data Lake Storage Gen2-konto med navnet storegen2, og at kontoen har én objektbeholder med navnet mycontainer , som du vil indsætte i /teste i din Spark-notesbogsession.

Hvis du vil montere objektbeholderen med navnet mycontainer, skal notebookutils først kontrollere, om du har tilladelse til at få adgang til objektbeholderen. Fabric understøtter i øjeblikket to godkendelsesmetoder for udløsertilsluttelseshandlingen: 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 API'en notebookutils.credentials.getSecret . Du kan få flere oplysninger om Azure Key Vault under Om administrerede lagerkontonøgler i Azure Key Vault.

Eksempelkode for metoden accountKey :

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

Tilslutningsparametre:

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 standardtimeouttiden. 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 standardtimeouttiden. 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}
)

Bemærk

Af sikkerhedsmæssige årsager anbefales det at undgå at integrere legitimationsoplysninger direkte i kode. Hvis du vil beskytte dine legitimationsoplysninger yderligere, vil alle hemmeligheder, der vises i notesbogoutput, blive redigeret. Du kan få mere at vide 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 tilslutningspunktet ved hjælp af API'en til notebookutils

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 API'en til notebookutils fs med en tilsluttet sti som en parameter. Dette stiformat er lidt anderledes.

Antag, at du har tilsluttet Data Lake Storage Gen2-objektbeholderen mycontainer til /test ved hjælp af mount-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'en, anbefaler vi, at du bruger getMountPath() til at få den nøjagtige sti:

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

Listemapper:

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 tilslutningspunkt:

notebookutils.fs.mounts()

Sådan frakobles tilslutningspunktet

Brug følgende kode til at fjerne tilslutningspunktet (/test i dette eksempel):

notebookutils.fs.unmount("/test")

Kendte begrænsninger

Den aktuelle tilslutning er en konfiguration på jobniveau. Vi anbefaler, at du bruger mounts-API'en til at kontrollere, om der findes et tilslutningspunkt, eller om det 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-hjælpeprogrammer

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

Nedenfor finder du 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

# 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å anvendelse

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

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

Flere oplysninger

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

Runtime-hjælpeprogrammer

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

Sessionsstyring

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, stopper den 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()

Bemærk

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.

Kendt problem

Når du bruger runtime-versionen over 1.2 og kører notebookutils.help(), understøttes de angivne fabricClient- og PBIClient-API'er ikke i øjeblikket. Api'en til legitimationsoplysninger understøttes heller ikke i Scala-notesbøger på nuværende tidspunkt.
Python-notesbogen understøtter ikke stop, genstartePython API'er, når du bruger værktøjet notebookutils.session til sessionsstyring.

Del via

NotebookUtils (tidligere MSSparkUtils) til Fabric

Filsystemværktøjer

Vis filer

Vis filegenskaber

Opret en ny mappe

Kopiér fil

Kopifil med effektiv udførelse

Vis filindhold

Flyt fil

Skriv fil

Føj indhold til en fil

Slet fil eller mappe

Tilslut/ophæv tilslutning af mappe

Hjælpeprogrammer til notesbøger

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

Hjælpeprogrammer til legitimationsoplysninger

Hent token

Hent hemmelighed ved hjælp af brugerlegitimationsoplysninger

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 tilslutningspunktet ved hjælp af API'en til notebookutils

Få adgang til filer under tilslutningspunktet via lokal sti

Sådan kontrollerer du eksisterende tilslutningspunkter

Sådan frakobles tilslutningspunktet

Kendte begrænsninger

Lakehouse-hjælpeprogrammer

Oversigt over metoder

Eksempler på anvendelse

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

Flere oplysninger

Runtime-hjælpeprogrammer

Vis oplysninger om sessionskontekst

Sessionsstyring

Stop en interaktiv session

Genstart Python-fortolkeren

Kendt problem

Relateret indhold

Feedback

Yderligere ressourcer