NotebookUtils (tidligere MSSparkUtils) for Fabric

Artikkel
01/13/2025

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.

Merk

MsSparkUtils er offisielt endret til NotebookUtils. Den eksisterende koden forblir bakoverkompatibel og vil ikke forårsake bruddendringer. Det anbefales på det sterkeste å oppgradere til notatblokkverktøy 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 arbeid 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()

Utdata

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 med filsystemet på samme måte som Spark API-er. Ta notebookutils.fs.mkdirs() og Fabric lakehouse bruk for eksempel:

Bruk	Relativ bane fra HDFS-rot	Absolutt bane for ABFS-filsystem	Absolutt bane for lokalt filsystem i drivernode
Ikke-standard lakehouse	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 lakehouse	Katalog 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>")

Listefiler

Hvis du vil vise innholdet i en katalog, bruker du notebookutils.fs.ls('Katalogbanen'). 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.

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.

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.

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

Merk

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.

Merk

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.

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

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

Merk

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,5s ~ 1 mellom regelmessige skrivere. 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.

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

Monter/demonter katalog

Finn mer informasjon om detaljert bruk i Filmontering og demontering.

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

Ytelse:


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.

Merk

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

Eksempel:

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

Stoffnotatblokk støtter også referanse til notatblokker på tvers av flere arbeidsområder ved å angi arbeidsområdets ID.

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.

Merk

Referansenotatblokken på tvers av arbeidsområder støttes av kjøretidsversjon 1.2 og nyere.
Hvis du bruker filene under Notatblokkressurs, kan du bruke notebookutils.nbResPath den i notatblokken det refereres til, for å sikre at den peker til den samme mappen som den interaktive kjøringen.

Referanse kjøre flere notatblokker parallelt

Viktig

Denne funksjonen er i forhåndsvisning.

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)

Merk

Parallellitetsgraden for kjøring av flere notatblokker er begrenset til den totale tilgjengelige databehandlingsressursen for en Spark-økt.
Den øvre grensen for notatblokkaktiviteter eller samtidige notatblokker er 50. Hvis du overskrider denne grensen, kan det føre til stabilitets- og ytelsesproblemer på grunn av høy databehandlingsressursbruk. 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 timeoutInSeconds og timeoutPerCellInSeconds felt 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, kaster Fabric-notatblokken et unntak, hopper over etterfø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. Eksempel: Notatblokk1 har tre celler og kaller en exit()-funksjon i den andre cellen. Notatblokk2 har fem celler og kaller kjøring (notatblokk1) i den tredje cellen. Når du kjører Notatblokk2, stopper Notatblokk1 i 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")

Merk

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

Eksempel:

Eksempel på 1 notatblokk med følgende to celler:

Celle 1 definerer en inndataparameter med standardverdien satt til 10.
Celle 2 avslutter notatblokken med inndata som avslutningsverdi.

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

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

Ytelse:

Notebook is executed successfully with exit value 10

Du kan kjøre eksempel1 i en annen notatblokk og angi inndataverdien som 20:

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

Ytelse:

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

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

Ytelse:

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 et gitt målgruppe og navn (valgfritt). Listen nedenfor viser de tilgjengelige målgruppenøklene:

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

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

notebookutils.credentials.getToken('audience Key')

Bli hemmelig ved hjelp av brukerlegitimasjon

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 monterings-, demonterings-, getMountPath()- og mounts()-API-ene til å knytte ekstern lagring (ADLS Gen2) til alle fungerende noder (drivernoder og arbeidernoder). 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 fungerer på samme måte.

Dette eksemplet forutsetter at du har én Data Lake Storage Gen2-konto med navnet Storegen2, og kontoen har én beholder med navnet mycontainer som du vil montere til /test i spark-økten for notatblokken.

Hvis du vil montere beholderen kalt mycontainer, må notatblokkverktøy først kontrollere 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). Deretter kan du hente dem ved hjelp av notebookutils.credentials.getSecret API. 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}
)

Monteringsparametere:

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

Merk

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 monterte Data Lake Storage Gen2-beholderen mycontainer til /test ved hjelp av API-en for montering. 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 API-en for notebookutils fs, anbefaler vi at du bruker getMountPath() for å få den nøyaktige banen:

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

Listekataloger:

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 til å demontere monteringspunktet (/test i dette eksemplet):

notebookutils.fs.unmount("/test")

Kjente begrensninger

Gjeldende montering er en jobbnivåkonfigurasjon. Vi anbefaler at du bruker monterings-API-en til å kontrollere 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

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

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.

Kjøretidsverktø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

Øktbehandling

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

Merk

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.

Kjent problem

Når du bruker runtime-versjon over 1.2 og kjører notebookutils.help(), støttes ikke de oppførte fabricClient- og PBIClient-API-ene for øyeblikket. I tillegg støttes ikke legitimasjons-API-en i Scala-notatblokker for øyeblikket.
Python-notatblokken støtter ikke stoppe, startePython på nytt API-er når du bruker notebookutils.session-verktøyet for øktbehandling.

Del via

NotebookUtils (tidligere MSSparkUtils) for Fabric

Filsystemverktøy

Listefiler

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/demonter katalog

Notatblokkverktø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

Legitimasjonsverktøy

Hent token

Bli hemmelig ved hjelp av brukerlegitimasjon

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

Kjøretidsverktøy

Vis kontekstinformasjon for økten

Øktbehandling

Stoppe en interaktiv økt

Start Python-tolken på nytt

Kjent problem

Relatert innhold

Tilbakemeldinger

Flere ressurser