NotebookUtils-filmontering och avmontering för Fabric

NotebookUtils stöder filmontering och avmonteringsåtgärder via Microsoft Spark Utilities-paketet. Du kan använda API:erna mount, unmount, getMountPath()och mounts() för att ansluta fjärrlagring (ADLS Gen2, Azure Blob Storage, OneLake) till alla arbetsnoder (drivrutinsnoder och arbetsnoder). När lagringsmonteringspunkten är på plats använder du det lokala fil-API:et för att komma åt data som om de lagras i det lokala filsystemet.

Monteringsåtgärder är särskilt användbara när du:

• Arbeta med bibliotek som förväntar sig lokala filsökvägar.
• Behöver konsekvent filsystemssemantik i molnlagring.
• Få effektivt åtkomst till OneLake-genvägar (S3/GCS).
• Skapa portabel kod som fungerar med flera lagringsserverdelar.

API-referens

I följande tabell sammanfattas tillgängliga monterings-API:er:

Autentiseringsmetoder

Monteringsåtgärder stöder flera autentiseringsmetoder. Välj metoden baserat på din lagringstyp och dina säkerhetskrav.

Microsoft Entra-token (standard och rekommenderas)

Microsoft Entra-tokenautentisering använder identiteten för utföraren av notebook, antingen en användare eller tjänsthuvudman. Det kräver inte explicita autentiseringsuppgifter i monteringsanropet, vilket gör det till det säkraste alternativet. Använd det här alternativet för montering av Lakehouse och lagring i Fabric-arbetsytan.

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

Kontonyckel

Använd en kontonyckel när lagringskontot inte stöder Microsoft Entra-autentisering eller när du har åtkomst till extern lagring eller lagring från tredje part. Lagra kontonycklar i Azure Key Vault och hämta 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}
)

SAS-token (Signatur för delad åtkomst)

Använd en SAS-token (signatur för delad åtkomst) för tidsbegränsad åtkomst med behörighetsomfång. Det här alternativet är användbart när du behöver bevilja tillfällig åtkomst till externa parter. Lagra SAS-token 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}
)

Montera ett ADLS Gen2-konto

I följande exempel visas hur du monterar Azure Data Lake Storage Gen2. Montering av Blob Storage och Azure File Share fungerar på liknande sätt.

Det här exemplet förutsätter att du har ett Data Lake Storage Gen2-konto med namnet storegen2, som har en container med namnet mycontainer som du vill montera på /test i din notebook spark-session.

För att montera containern mycontainer måste NotebookUtils först kontrollera om du har behörighet att komma åt containern. För närvarande stöder Fabric tre autentiseringsmetoder för utlösarmonteringsåtgärden: Microsoft Entra-token (standard), accountKey och sasToken.

Av säkerhetsskäl lagrar du kontonycklar eller SAS-token i Azure Key Vault (som följande skärmbild visar). Du kan sedan hämta dem med hjälp av API:et notebookutils.credentials.getSecret . Mer information om Azure Key Vault finns i Om Azure Key Vault-hanterade lagringskontonycklar.

Exempelkod för metoden accountKey :

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

Exempelkod för 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}
)

Monteringsparametrar

Du kan justera monteringsbeteendet med följande valfria parametrar på kartan extraConfigs :

• fileCacheTimeout: Blobar cachelagras i den lokala temp-mappen i 120 sekunder som standard. Under den här tiden kontrollerar blobfuse inte om filen är uppdaterad. Du kan ange den här parametern för att ändra standard timeout-tiden. När flera klienter ändrar filer samtidigt, för att undvika inkonsekvenser mellan lokala filer och fjärrfiler, förkortar du cachetiden eller ställer in den på 0 för att alltid hämta de senaste filerna från servern.
• timeout: Tidsgränsen för monteringsåtgärden är som standard 30 sekunder. Du kan ange den här parametern för att ändra standard timeout-tiden. När det finns för många exekutorer eller när monteringstiden överskrider tidsgränsen, bör du öka värdet.

Du kan använda följande parametrar:

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

Rekommendationer för cachekonfiguration

Välj ett timeout-värde för cache baserat på ditt åtkomstmönster:

Nollcachemönster

När flera klienter ändrar filer samtidigt använder du en nollcachekonfiguration för att alltid hämta den senaste versionen från servern:

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

Montera ett sjöhus

Lakehouse-montering stöder endast Microsoft Entra-tokenautentisering. Exempelkod för att montera ett Lakehouse till /<mount_name>:

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

Komma åt filer under monteringspunkten med hjälp av notebookutils fs-API:et

Använd monteringsåtgärder när du vill komma åt data i fjärrlagring via ett lokalt filsystem-API. Du kan också komma åt monterade data med hjälp av API:et notebookutils.fs med en monterad sökväg, men sökvägsformatet skiljer sig åt.

Anta att du monterade Data Lake Storage Gen2-containern mycontainer till /test med hjälp av monterings-API:et. När du kommer åt data med ett lokalt filsystems-API är sökvägsformatet så här:

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

När du vill komma åt data med hjälp av API:et notebookutils fs använder du getMountPath() för att få rätt sökväg:

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

• Lista kataloger.

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

• Läs filinnehåll.

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

• Skapa en katalog.

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

Komma åt filer under monteringspunkten via lokal sökväg

Du kan läsa och skriva filer i en monteringspunkt med hjälp av standardfilsystemet. Följande Python-exempel visar det här mönstret:

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

Kontrollera befintliga monteringspunkter

Använd API:et notebookutils.fs.mounts() för att kontrollera all befintlig monteringspunktsinformation:

notebookutils.fs.mounts()

Kontrollera om en monteringspunkt finns innan 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")

Avmontera monteringspunkten

Använd följande kod för att demontera monteringspunkten (/testa i det här exemplet):

notebookutils.fs.unmount("/test")

Montera-avmontera-process arbetsflöde

För tillförlitlig resurshantering allokerar du monteringsoperationer i en try/finally block för att säkerställa att städningen genomförs även om ett fel inträffar.

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

Kända begränsningar

• Monteringspunkter är konfigurationer på jobbnivå. Använd API:et mounts för att kontrollera om en monteringspunkt redan finns eller är tillgänglig.
• Avmontering sker inte automatiskt. När programkörningen är klar anropar du ett avmonterings-API i koden för att frigöra diskutrymme. Annars finns monteringspunkten kvar på noden när programkörningen har slutförts.
• Det går inte att montera ett ADLS Gen1-lagringskonto.

Relaterat innehåll

• NotebookUtils för Fabric
• NotebookUtils-filsystemverktyg