NotebookUtils filmontering og afmontering for Fabric

NotebookUtils understøtter filmontering og afmontering via Microsoft Spark Utilities-pakken. Du kan bruge mount, unmount, getMountPath(), og mounts() API'erne til at tilslutte fjernlagring (ADLS Gen2, Azure Blob Storage, OneLake) til alle fungerende noder (drivernode og arbejdernoder). 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.

Monteringsoperationer er særligt nyttige, når du:

• Arbejd med biblioteker, der forventer lokale filstier.
• Der er brug for ensartede filsystemsemantik på tværs af cloud-lagring.
• Få effektivt adgang til OneLake-genveje (S3/GCS).
• Byg bærbar kode, der fungerer med flere lagringsbackends.

API-reference

Følgende tabel opsummerer de tilgængelige mount-API'er:

Metode	Signatur	Beskrivelse
mount	mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Monterer fjernlagring på det angivne monteringspunkt.
unmount	unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Afmonterer og fjerner et monteringspunkt.
mounts	mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo]	Lister alle eksisterende monteringspunkter med detaljer.
getMountPath	getMountPath(mountPoint: String, scope: String = ""): String	Henter den lokale filsystemsti for et monteringspunkt.

Godkendelsesmetoder

Mount-operationer understøtter flere autentificeringsmetoder. Vælg metoden baseret på din lagertype og dine sikkerhedskrav.

Microsoft Entra-token (standard og anbefalet)

Microsoft Entra token-autentificering bruger identiteten på notebook-eksekutoren, enten en bruger eller en tjenesteprincipal. Det kræver ikke eksplicitte legitimationsoplysninger i mount-kaldet, hvilket gør det til den mest sikre løsning. Brug denne mulighed til montering af Lakehouse og opbevaring af stofarbejdsrum.

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

Tips

Brug Microsoft Entra token-autentificering, når det er muligt. Det eliminerer risikoen for legitimationseksponering og kræver ingen ekstra opsætning til opbevaring af Fabric-arbejdsområder.

Kontonøgle

Brug en kontonøgle, når lagringskontoen ikke understøtter Microsoft Entra-godkendelse, eller når du får adgang til ekstern eller tredjeparts lagring. Gem kontonøgler 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}
)

Shared access signature (SAS) token

Brug en shared access signature (SAS)- token til tidsbegrænset, tilladelsesbegrænset adgang. Denne mulighed er nyttig, når du skal give midlertidig adgang til eksterne parter. Gem 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}
)

Vigtigt!

Af sikkerhedsmæssige årsager bør du undgå at indlejre legitimationsoplysninger direkte i koden. Alle hemmeligheder, der vises i notesbogens output, bliver automatisk redigeret. Du kan finde flere oplysninger under Hemmelig redigering.

Opret 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 mounte containeren kaldet mycontainer, skal NotebookUtils først tjekke, om du har tilladelse til at tilgå containeren. I øjeblikket understøtter Fabric tre autentificeringsmetoder for trigger-mount-operationen: Microsoft Entra-token (standard), accountKey og sasToken.

Af sikkerhedsmæssige årsager kan du gemme kontonøgler eller SAS-tokens i Azure Key Vault (som det følgende skærmbillede viser). Du kan derefter hente dem ved at bruge API'et notebookutils.credentials.getSecret . 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 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 til 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}
)

Monteringsparametre

Du kan justere mount-adfærden med følgende valgfrie parametre i kortet extraConfigs :

• fileCacheTimeout: Blobs caches som standard i den lokale temp-mappe i 120 sekunder. I denne periode tjekker blobfuse ikke, om filen er opdateret. Du kan sætte denne parameter til at ændre standard timeout-tidspunktet. Når flere klienter ændrer filer samtidig, for at undgå uoverensstemmelser mellem lokale og eksterne filer, skal cache-tiden forkortes eller sættes til 0, så de altid får de nyeste filer fra serveren.
• timeout: Mount-operationens timeout er som standard 30 sekunder. Du kan sætte denne parameter til at ændre standard timeout-tidspunktet. Når der er for mange eksekutorer, eller når mount går ud på timeout, øg værdien.

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

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

Anbefalinger til cache-konfiguration

Vælg en cache-timeout-værdi baseret på dit adgangsmønster:

scenarie	Anbefalet fileCacheTimeout	Bemærkninger
Læse-tung, enkelt klient	120 (standard)	God balance mellem præstation og friskhed.
Moderat multi-klient adgang	30–60	Reducerer risikoen for forældede data.
Flere klienter, der ændrer filer	0	Henter altid det seneste fra serveren.
Filer ændrer sig sjældent	300+	Optimerer læseydelsen.

Zero-cache-mønster

Når flere klienter ændrer filer samtidig, brug en zero-cache-konfiguration for altid at hente den nyeste version 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}
)

Bemærkning

Øg parameteren, timeout når du monterer med mange eksekutører eller når du oplever timeout-fejl.

Mount a Lakehouse

Lakehouse-montering understøtter kun Microsoft Entra-tokenautentificering. Eksempelkode til montering af et søhus til /<mount_name>:

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

Få adgang til filer under mount-punktet ved at bruge notebookutils fs API'en

Brug mount-operationer, når du vil tilgå data i fjernlagring via et lokalt filsystem-API. Du kan også få adgang til monterede data ved at bruge API'et notebookutils.fs med en monteret sti, men stiformatet er forskelligt.

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 tilgå dataene via API'en notebookutils fs , skal du bruge getMountPath() den for at få den nøjagtige sti:

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

• Lister kataloger.

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

• Læs filens indhold.

  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 læse og skrive filer i et mount-punkt ved at bruge det standard filsystem. Følgende Python-eksempel viser dette mønster:

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

Tjek eksisterende monteringspunkter

Brug API'et notebookutils.fs.mounts() til at tjekke al eksisterende monteringspunktinformation:

notebookutils.fs.mounts()

Tips

Tjek altid eksisterende mounts, før du opretter nye mount-punkter mounts() for at undgå konflikter.

Tjek om der findes en montering, før du monterer

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

Afmonter monteringspunktet

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

notebookutils.fs.unmount("/test")

Vigtigt!

Afmonteringsmekanismen aktiveres 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 eksisterer monteringspunktet stadig i noden efter applikationskørselen er afsluttet.

Arbejdsgang for montering og afmontering af processer

For pålidelig ressourcestyring indkapsles mount-operationer i en try/finally blok for at sikre, at oprydning sker, selv hvis der opstår en fejl:

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

Kendte begrænsninger

• Mounts er job-niveau konfigurationer. Brug API'et mounts til at tjekke, om et monteringspunkt allerede eksisterer eller er tilgængeligt.
• Afmontering sker ikke automatisk. Når applikationen er færdig, skal du kalde et unmount-API i din kode for at frigøre diskplads. Ellers forbliver monteringspunktet på noden efter applikationskørselen er afsluttet.
• Det understøttes ikke at oprette en ADLS Gen1-lagerkonto.

Relateret indhold

• NotebookUtils til stof
• NotebookUtils filsystemværktøjer