NotebookUtils-filmontering og avmontering for Fabric

NotebookUtils støtter filmontering og avmonteringsoperasjoner gjennom Microsoft Spark Utilities-pakken. Du kan bruke mount, unmount, getMountPath(), og mounts() API-er for å koble ekstern lagring (ADLS Gen2, Azure Blob Storage, OneLake) til alle fungerende noder (drivernode 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.

Monteringsoperasjoner er spesielt nyttige når du:

• Jobb med biblioteker som forventer lokale filstier.
• Trenger konsistent filsystem-semantikk på tvers av skylagring.
• Få tilgang til OneLake-snarveier (S3/GCS) effektivt.
• Bygg bærbar kode som fungerer med flere lagringsbackends.

API-referanse

Følgende tabell oppsummerer tilgjengelige monterings-API-er:

Godkjenningsmetoder

Monteringsoperasjoner støtter flere autentiseringsmetoder. Velg metoden basert på lagringstypen og sikkerhetskravene dine.

Microsoft Entra-token (standard og anbefalt)

Microsoft Entra-tokenautentisering bruker identiteten til notatbokens eksekutor, enten en bruker- eller tjenesteleder. Det krever ikke eksplisitte legitimasjoner i mount-kallet, noe som gjør det til det sikreste alternativet. Bruk dette alternativet for montering av Lakehouse og oppbevaring av stoffarbeidsplasser.

# Mount using Microsoft Entra token (no credentials needed)
notebookutils.fs.mount(
    "abfss://mycontainer@mystorageaccount.dfs.core.windows.net",
    "/mydata"
)

Kontonøkkel

Bruk en kontonøkkel når lagringskontoen ikke støtter Microsoft Entra-autentisering, eller når du får tilgang til ekstern eller tredjeparts lagring. Lagre kontonøkler i Azure Key Vault og hent dem med API-et notebookutils.credentials.getSecret .

# Retrieve account key from Azure Key Vault
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"accountKey": accountKey}
)

Delt tilgangssignatur (SAS)-token

Bruk en delt tilgangssignatur (SAS)- token for tidsbegrenset, tillatelsesbegrenset tilgang. Dette alternativet er nyttig når du trenger å gi midlertidig tilgang til eksterne parter. Lagre SAS-tokens i Azure Key Vault.

# Retrieve SAS token from Azure Key Vault
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",
    "/test",
    {"sasToken": sasToken}
)

Lag en ADLS Gen2-konto

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

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

For å montere containeren kalt mycontainer, må NotebookUtils først sjekke om du har tillatelse til å få tilgang til containeren. For øyeblikket støtter Fabric tre autentiseringsmetoder for trigger-mount-operasjonen: Microsoft Entra-token (standard), accountKey og sasToken.

Av sikkerhetsgrunner, lagre kontonøkler eller SAS-tokens i Azure Key Vault (som skjermbildet nedenfor viser). Du kan deretter hente dem ved å bruke API-et notebookutils.credentials.getSecret . 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 the full audience, such as 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 the full audience, such as https://vault.azure.net.
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Festeparametere

Du kan justere monteringsoppførsel med følgende valgfrie parametere i kartet extraConfigs :

• fileCacheTimeout: Blobs er som standard cachet i den lokale temp-mappen i 120 sekunder. I denne perioden sjekker ikke blobfuse om filen er oppdatert. Du kan sette denne parameteren til å endre standard timeout-tid. Når flere klienter endrer filer samtidig, for å unngå inkonsistenser mellom lokale og eksterne filer, forkort cache-tiden eller sett den til 0 for alltid å hente de nyeste filene fra serveren.
• Timeout: Timeout for mount-operasjonen er som standard 30 sekunder. Du kan sette denne parameteren til å endre standard timeout-tid. Når det er for mange eksekutorer eller når mount går ut på tid, øk verdien.

Du kan bruke disse parameterne slik:

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

Anbefalinger for cache-konfigurasjon

Velg en cache-timeout-verdi basert på tilgangsmønsteret ditt:

Null-cache-mønster

Når flere klienter endrer filer samtidig, bruk en null-cache-konfigurasjon for alltid å hente den nyeste versjonen fra serveren:

# For scenarios with multiple clients modifying files
# Use zero cache to always fetch the latest from the server
notebookutils.fs.mount(
    "abfss://shared@account.dfs.core.windows.net",
    "/shared_data",
    {"fileCacheTimeout": 0}
)

Fjell et innsjøhus

Lakehouse-montering støtter kun Microsoft Entra-tokenautentisering. Eksempelkode for montering av et innsjøhus 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 å bruke notebookutils fs API

Bruk mount-operasjoner når du vil få tilgang til data i ekstern lagring via et lokalt filsystem-API. Du kan også få tilgang til montert data ved å bruke API-et notebookutils.fs med en montert sti, men stiformatet er forskjellig.

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

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

Når du vil få tilgang til dataene ved å bruke API-et notebookutils fs , bruk getMountPath() for å få den nøyaktige stien:

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

• List kataloger.

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

• Les innholdet i filen.

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

• Lag en katalog.

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

Få tilgang til filer under monteringspunktet via lokal bane

Du kan lese og skrive filer i et monteringspunkt ved å bruke standard filsystem. Følgende Python-eksempel viser dette mønsteret:

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

Sjekk eksisterende monteringspunkter

Bruk API-et notebookutils.fs.mounts() for å sjekke all eksisterende monteringspunktinfo:

notebookutils.fs.mounts()

Sjekk om det finnes en montering før montering

existing_mounts = notebookutils.fs.mounts()
mount_point = "/mydata"

if any(m.mountPoint == mount_point for m in existing_mounts):
    print(f"Mount point {mount_point} already exists")
else:
    notebookutils.fs.mount(
        "abfss://container@account.dfs.core.windows.net",
        mount_point
    )
    print("Mount created successfully")

Ta av monteringspunktet

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

notebookutils.fs.unmount("/test")

Mount-process-unmount arbeidsflyt

For pålitelig ressursstyring, pakk monteringsoperasjoner inn i en try/finally blokk for å sikre at opprydding skjer selv om det oppstår en feil:

def process_with_mount(source_uri, mount_point):
    """Complete workflow: mount, process, unmount."""
    
    try:
        # Step 1: Check if already mounted
        existing = notebookutils.fs.mounts()
        if any(m.mountPoint == mount_point for m in existing):
            print(f"Already mounted at {mount_point}")
        else:
            notebookutils.fs.mount(source_uri, mount_point)
            print(f"Mounted {source_uri} at {mount_point}")
        
        # Step 2: Process data using local file system
        mount_path = notebookutils.fs.getMountPath(mount_point)
        
        with open(f"{mount_path}/data/input.txt", "r") as f:
            data = f.read()
        
        processed = data.upper()
        
        with open(f"{mount_path}/output/result.txt", "w") as f:
            f.write(processed)
        
        print("Processing complete")
        
    finally:
        # Step 3: Always unmount to release resources
        notebookutils.fs.unmount(mount_point)
        print(f"Unmounted {mount_point}")

process_with_mount(
    "abfss://mycontainer@mystorage.dfs.core.windows.net",
    "/temp_mount"
)

Kjente begrensninger

• Fester er stillinger på jobbnivå. Bruk API-et mounts for å sjekke om et monteringspunkt allerede eksisterer eller er tilgjengelig.
• Avmontering skjer ikke automatisk. Når applikasjonen er ferdig, kall et unmount-API i koden din for å frigjøre diskplass. Ellers forblir monteringspunktet på noden etter at applikasjonskjøringen er ferdig.
• Montering av en ADLS Gen1-lagringskonto støttes ikke.

Relatert innhold

• NotebookUtils for Fabric
• NotebookUtils filsystemverktøy