Introduksjon av Fabric MSSparkUtils
Microsoft Spark Utilities (MSSparkUtils) er en innebygd pakke som hjelper deg med å utføre vanlige oppgaver på en enkel måte. Du kan brukeMSSparkUtils til å arbeide med filsystemer, for å få miljøvariabler, kjede notatblokker sammen og til å arbeide med hemmeligheter. MSSparkUtils er tilgjengelige i PySpark (Python) Scala, SparkR-notatblokker og Microsoft Fabric-rørledninger.
Viktig
Microsoft Fabric er for øyeblikket i FORHÅNDSVERSJON. Denne informasjonen er knyttet til et forhåndsutgitt produkt som kan endres vesentlig før det utgis. Microsoft gir ingen garantier, uttrykt eller underforstått, med hensyn til informasjonen som er oppgitt her.
Verktøy for filsystem
mssparkutils.fs tilbyr verktøy for å arbeide med ulike filsystemer, inkludert Azure Data Lake Storage Gen2 (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:
from notebookutils import mssparkutils
mssparkutils.fs.help()
Utdata
mssparkutils.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
mv(from: String, to: String, recurse: 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 mssparkutils.fs.help("methodName") for more info about a method.
mssparkutils fungerer med filsystemet på samme måte som Spark API-er. Ta mssparkuitls.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 |
|---|---|---|---|
| Nondefault lakehouse | Støttes ikke | mssparkutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/<> new_dir>") | mssparkutils.fs.mkdirs("file:/<new_dir>") |
| Standard lakehouse | Katalog under «Filer» eller «Tabeller»: mssparkutils.fs.mkdirs("Files/<new_dir>") | mssparkutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/<> new_dir>") | mssparkutils.fs.mkdirs("file:/<new_dir>") |
Listefiler
Før opp innholdet i en katalog, bruk mssparkutils.fs.ls(«Din katalogbane»), for eksempel:
mssparkutils.fs.ls("Files/tmp") # works with the default lakehouse files using relative path
mssparkutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>") # based on ABFS file system
mssparkutils.fs.ls("file:/tmp") # based on local file system of driver node
Vis filegenskaper
Returnerer filegenskaper, inkludert filnavn, filbane, filstørrelse og om det er en katalog og en fil.
files = mssparkutils.fs.ls('Your directory path')
for file in files:
print(file.name, file.isDir, file.isFile, file.path, file.size)
Opprett ny katalog
Oppretter den angitte katalogen hvis den ikke finnes, og eventuelle nødvendige overordnede mapper.
mssparkutils.fs.mkdirs('new directory name')
mssparkutils.fs. mkdirs("Files/<new_dir>") # works with the default lakehouse files using relative path
mssparkutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") # based on ABFS file system
mssparkutils.fs.ls("file:/<new_dir>") # based on local file system of driver node
Kopier fil
Kopierer en fil eller katalog. Støtter kopiering på tvers av filsystemer.
mssparkutils.fs.cp('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
Returnerer opptil de første maxBytes-byte for den angitte filen som en streng kodet i UTF-8.
mssparkutils.fs.head('file path', maxBytes to read)
Flytt fil
Flytter en fil eller katalog. Støtter flytting på tvers av filsystemer.
mssparkutils.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
Skrive fil
Skriver den angitte strengen ut til en fil, kodet i UTF-8. Skriver den angitte strengen ut til en fil, kodet i UTF-8.
mssparkutils.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 i en fil
Tilføyer den angitte strengen til en fil, kodet i UTF-8.
mssparkutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it does not exist
Slett fil eller katalog
Fjerner en fil eller katalog.
mssparkutils.fs.rm('file path', True) # Set the last parameter as True to remove all files and directories recursively
Monter/demonter katalog
Du finner detaljert bruk i Filmontering og demontering.
Notatblokkverktøy
Bruk MSSparkUtils Notebook Utilities 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:
mssparkutils.notebook.help()
Utgang:
exit(value: String): void -> This method lets you exit a notebook with a value.
run(path: String, timeoutSeconds: int, arguments: Map): String -> This method runs a notebook and returns its exit value.
Referere til en notatblokk
Referer til en notatblokk og returnerer avslutningsverdien. Du kan kjøre nestefunksjonskall i en notatblokk interaktivt eller i et datasamlebånd. Notatblokken som refereres til, kjører i Spark-utvalget som notatblokken kaller opp denne funksjonen.
mssparkutils.notebook.run("notebook name", <timeoutSeconds>, <parameterMap>)
Eksempel:
mssparkutils.notebook.run("Sample1", 90, {"input": 20 })
Du kan åpne øyeblikksbildekoblingen for referansekjøring i celleutdataene, øyeblikksbildet fanger opp resultatene av kodekjøringen og lar deg enkelt feilsøke en referansekjøring.
Obs!
For øyeblikket støtter Fabric-notatblokken bare referansenotatblokker i et arbeidsområde.
Avslutte en notatblokk
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 kjøring av delspvalensceller og holder Spark-økten i live.
- Når du orkestrerer en notatblokk i datasamlebånd som kaller en exit()- funksjon, returneres notatblokkaktiviteten med en avslutningsverdi, fullfører datasamlebåndkjøringen og stopper Spark-økten.
- Når du kaller en exit()- funksjon i en notatblokk som det refereres til, vil Fabric Spark stoppe videre kjøring av den refererte notatblokken, og fortsette å kjøre neste celler i hovednotatblokken som kaller opp run()- funksjonen. Eksempel: Notatblokk1 har tre celler og kaller opp en exit()- funksjon i den andre cellen. Notebook2 har fem celler og kall kjøres(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.
mssparkutils.notebook.exit("value string")
Eksempel:
Eksempel1 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 = mssparkutils.notebook.run("Sample1")
print (exitVal)
Utgang:
Notebook executed successfully with exit value 10
Du kan kjøre eksempel1 i en annen notatblokk og angi inndataverdien som 20:
exitVal = mssparkutils.notebook.run("Sample1", 90, {"input": 20 })
print (exitVal)
Utgang:
Notebook executed successfully with exit value 20
Legitimasjonsverktøy
Du kan bruke MSSparkUtils Credentials Utilities til å få tilgangstokener og administrere hemmeligheter i Azure Key Vault.
Kjør følgende kommando for å få en oversikt over de tilgjengelige metodene:
mssparkutils.credentials.help()
Utgang:
getToken(audience, name): returns AAD token for a given audience, name (optional)
getSecret(akvName, secret): returns AKV secret for a given akvName, secret key
Hent token
Returnerer Azure AD token for en gitt målgruppe, navn (valgfritt), Listen nedenfor viser gjeldende tilgjengelige målgruppenøkler:
- 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:
mssparkutils.credentials.getToken('audience Key')
Få hemmelighet ved hjelp av brukerlegitimasjon
Returnerer Azure Key Vault hemmelighet for et gitt Azure Key Vault navn, hemmelig navn og koblet tjenestenavn ved hjelp av brukerlegitimasjon.
mssparkutils.credentials.getSecret('azure key vault name','secret name')
Filmontering og demontering
Microsoft Fabric støtter monteringsscenarioer i Microsoft Spark Utilities-pakken. Du kan bruke montering, demontering, getMountPath() og mounts() API-er til å knytte ekstern lagring (Azure Data Lake Storage Gen2) til alle fungerende noder (drivernoder og arbeidernoder). Når lagringsmonteringspunktet er på plass, bruker du API-en for den lokale filen til å få tilgang til data som om den er lagret i det lokale filsystemet.
Slik monterer du en ADLS Gen2-konto
Denne delen illustrerer hvordan du monterer Azure Data Lake Storage Gen2 trinn for trinn som et eksempel. Montering av Blob Storage fungerer på samme måte.
Eksemplet forutsetter at du har én Data Lake Storage Gen2 konto kalt storegen2. Kontoen har én beholder med navnet mycontainer som du vil montere på /test i spark-økten for notatblokken.
Hvis du vil montere beholderen kalt mycontainer, må mssparkutils først kontrollere om du har tillatelse til å få tilgang til beholderen. Microsoft Fabric støtter for øyeblikket to godkjenningsmetoder for utløsermonteringsoperasjonen: accountKey og sastoken.
Montere via signaturtoken eller kontonøkkel for delt tilgang
Mssparkutils 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 eksempel skjermbilde viser). Deretter kan du hente dem ved hjelp av mssparkutils.credentials.getSecret API. Hvis du vil ha informasjon om bruken av Azure Key Vault, kan du se Om Azure Key Vault administrerte lagringskontonøkler.
Her er eksempelkoden for bruk av accountKey-metoden:
from notebookutils import mssparkutils
# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
accountKey = mssparkutils.credentials.getSecret("<vaultURI>", "<secretName>")
mssparkutils.fs.mount(
"abfss://mycontainer@<accountname>.dfs.core.windows.net",
"/test",
{"accountKey":accountKey}
)
For sastoken kan du referere til følgende eksempelkode:
from notebookutils import mssparkutils
# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
sasToken = mssparkutils.credentials.getSecret("<vaultURI>", "<secretName>")
mssparkutils.fs.mount(
"abfss://mycontainer@<accountname>.dfs.core.windows.net",
"/test",
{"sasToken":sasToken}
)
Obs!
Av sikkerhetsårsaker anbefales det ikke å lagre legitimasjon i kode. Hvis du vil beskytte legitimasjonen din ytterligere, vil vi fjerne hemmeligheten din i notatblokkutdata. Hvis du vil ha mer informasjon, kan du sjekke Hemmelig skjuling.
Slik monterer du et innsjøhus
Her er eksempelkoden for montering av et lakehouse til /test.
from notebookutils import mssparkutils
mssparkutils.fs.mount(
"abfss://<workspace_id>@msit-onelake.dfs.fabric.microsoft.com/<lakehouse_id>",
"/test"
)
Få tilgang til filer under monteringspunktet ved hjelp av mssparktuils fs API
Hovedformålet med monteringsoperasjonen er å gi kunder tilgang til dataene som er lagret i en ekstern lagringskonto ved hjelp av en lokal filsystem-API. Du kan også få tilgang til dataene ved hjelp av mssparkutils fs API med en montert bane som parameter. Baneformatet som brukes her, er litt annerledes.
Anta at du monterte den Data Lake Storage Gen2 beholderen mycontainer til /test ved hjelp av monterings-API-en. Når du får tilgang til dataene ved hjelp av en lokal filsystem-API, er baneformatet slik:
/synfs/notebook/{sessionId}/test/{filename}
Når du vil ha tilgang til dataene ved hjelp av mssparkutils fs API, anbefaler vi at du bruker en getMountPath() for å få den nøyaktige banen:
path = mssparkutils.fs.getMountPath("/test")
Listekataloger:
mssparkutils.fs.ls(f"file://{mssparkutils.fs.getMountPath('/test')}")Les filinnhold:
mssparkutils.fs.head(f"file://{mssparkutils.fs.getMountPath('/test')}/myFile.txt")Opprette en katalog:
mssparkutils.fs.mkdirs(f"file://{mssparkutils.fs.getMountPath('/test')}/newdir")
Få tilgang til filer under monteringspunktet via lokal bane
Du kan enkelt lese og skrive filene i monteringspunkt ved hjelp av standard filsystemmåte, bruke Python som et eksempel:
#File read
with open(mssparkutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
print(f.read())
#File write
with open(mssparkutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
print(f.write("dummy data"))
Slik kontrollerer du eksisterende monteringspunkter
Du kan bruke mssparkutils.fs.mounts() API til å kontrollere all eksisterende informasjon om monteringspunkt:
mssparkutils.fs.mounts()
Slik demonterer du monteringspunktet
Bruk følgende kode til å demontere monteringspunktet (/test i dette eksemplet):
mssparkutils.fs.unmount("/test")
Kjente begrensninger
- Den gjeldende monteringen er en jobbnivåkonfigurasjon, vi komprimerer på nytt for å bruke mounts API for å kontrollere om monteringspunktet finnes eller ikke er tilgjengelig.
- Demonteringsmekanismen er ikke automatisk. Når programkjøringen er ferdig, må du eksplisitt kalle opp en demonterings-API i koden for å demontere monteringspunktet for å frigjøre diskplassen. Ellers vil monteringspunktet fremdeles finnes i noden etter at applikasjonskjøringen er ferdig.
- Montering av en ADLS Gen1-lagringskonto støttes ikke.