NotebookUtils na montáž a odmontovanie súborov pre Fabric

NotebookUtils podporuje operácie primontovania a odpojovania súborov prostredníctvom balíka Microsoft Spark Utilities. Môžete použiť mount, unmount, getMountPath(), a mounts() API na pripojenie vzdialeného úložiska (ADLS Gen2, Azure Blob Storage, OneLake) ku všetkým funkčným uzlom (driver node a worker node). Po uložení bodu pripojenia ukladacieho priestoru použite rozhranie API lokálneho súboru na prístup k údajom, akoby boli uložené v lokálnom systéme súborov.

Montážne operácie sú obzvlášť užitočné, keď:

• Pracuj s knižnicami, ktoré očakávajú lokálne cesty k súborom.
• Potrebujem konzistentnú sémantiku súborových systémov naprieč cloudovým úložiskom.
• Efektívne pristupujte k skratkám OneLake (S3/GCS).
• Vytvorte prenosný kód, ktorý funguje s viacerými úložiskovými backendmi.

Referenčné informácie o rozhraní API

Nasledujúca tabuľka zhrňuje dostupné API mount:

Method	Podpis	Description
mount	mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Umiestňuje vzdialené úložisko na určené miesto montáže.
unmount	unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Odmontuje a odstráni montážny bod.
mounts	mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo]	Uvádza všetky existujúce montážne body s detailmi.
getMountPath	getMountPath(mountPoint: String, scope: String = ""): String	Získa lokálnu cestu súborového systému pre mount point.

Autentifikačné metódy

Operácie montáže podporujú niekoľko metód autentifikácie. Vyberte si metódu podľa typu úložiska a bezpečnostných požiadaviek.

Microsoft Entra token (predvolený a odporúčaný)

Autentifikácia tokenov Microsoft Entra používa identitu vykonávateľa zápisníka, či už používateľa alebo princípa služby. Nevyžaduje explicitné prihlasovacie údaje pri mountovom volaní, čo z neho robí najbezpečnejšiu možnosť. Použite túto možnosť na upevnenie chaty pri jazere a skladovanie pracovného priestoru Fabric.

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

Prepitné

Používajte autentifikáciu tokenov Microsoft Entra, kedykoľvek je to možné. Eliminuje riziko vystavenia prihlasovacích údajov a nevyžaduje žiadne ďalšie nastavenie pre ukladanie pracovného priestoru Fabric.

Kľúč konta

Používajte kľúč účtu, keď úložný účet nepodporuje autentifikáciu Microsoft Entra, alebo keď pristupujete k externému či tretiemu úložisku. Ukladajte kľúče k účtom v Azure Key Vault a získavajte ich pomocou notebookutils.credentials.getSecret API.

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

Token so zdieľaným prístupovým podpisom (SAS)

Použite token so zdieľaným prístupovým podpisom (SAS) pre časovo obmedzený prístup s obmedzeným prístupom. Táto možnosť je užitočná, keď potrebujete udeliť dočasný prístup externým stranám. Ukladať SAS tokeny v 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}
)

Dôležité

Pre bezpečnostné účely sa vyhnite vkladaniu prihlasovacích údajov priamo do kódu. Akékoľvek tajomstvá zobrazené vo výstupoch zápisníka sú automaticky redigované. Ďalšie informácie nájdete v téme Tajné redigovanie.

Založte si účet ADLS Gen2

V nasledujúcom príklade je znázornené, ako pripojiť Azure Data Lake Storage Gen2. Pripojenie Blob Storage a Azure File Share funguje podobne.

V tomto príklade sa predpokladá, že máte jedno konto Data Lake Storage Gen2 s názvom storegen2, ktoré má kontajner s názvom mycontainer , ktorý chcete pripojiť k /test v relácii Spark poznámkového bloku.

Na pripojenie kontajnera s názvom mycontainer musí NotebookUtils najprv skontrolovať, či máte povolenie na prístup ku kontajneru. V súčasnosti Fabric podporuje tri autentifikačné metódy pre operáciu trigger mount: Microsoft Entra token (predvolený), accountKey a sasToken.

Z bezpečnostných dôvodov ukladajte kľúče účtu alebo SAS tokeny v Azure Key Vault (ako ukazuje nasledujúci screenshot). Potom ich môžete získať pomocou notebookutils.credentials.getSecret API. Ďalšie informácie o službe Azure Key Vault nájdete v téme Informácie o kľúčoch konta spravovaného úložiska Azure Key Vault.

Vzorový kód pre metódu 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}
)

Ukážkový kód pre 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}
)

Montážne parametre

Správanie montáže extraConfigs môžete naladiť pomocou nasledujúcich voliteľných parametrov v mape:

• fileCacheTimeout: Bloby sú predvolene uložené v lokálnom dočasnom priečinku 120 sekúnd. Počas tohto času blobfuse nekontroluje, či je súbor aktuálny. Tento parameter si môžete nastaviť na zmenu predvoleného času časového limitu. Keď viacerí klienti menia súbory súčasne, aby sa predišlo nezrovnalostiam medzi lokálnymi a vzdialenými súbormi, skratte čas cache alebo ho nastavte na 0, aby ste vždy získali najnovšie súbory zo servera.
• Timeout: Timeout operácie mount je predvolene 30 sekúnd. Tento parameter si môžete nastaviť na zmenu predvoleného času časového limitu. Keď je vykonávateľov príliš veľa alebo keď vyprší čas na upevnenie, zvýšte hodnotu.

Nasledujúce parametre môžete použiť:

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

Odporúčania pre konfiguráciu cache

Vyberte si hodnotu timeoutu cache podľa vášho prístupového vzoru:

Scenár	Odporúčané fileCacheTimeout	Poznámky
Čítanie náročné, jeden klient	120 (predvolené)	Dobrý pomer medzi výkonom a sviežosťou.
Mierny prístup s viacerými klientmi	30–60	Znižuje riziko zastaraných dát.
Viacerí klienti upravujúci súbory	0	Vždy získava najnovšie informácie zo servera.
Súbory sa zriedka menia	300+	Optimalizuje výkon čítania.

Vzor nulovej cache

Keď viacerí klienti menia súbory súčasne, použite konfiguráciu bez cache, aby ste vždy načítali najnovšiu verziu zo servera:

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

Poznámka

Zvyšujte timeout parameter pri montáži s viacerými executormi alebo pri chybách časového limitu.

Mount a Lakehouse

Lakehouse montáž podporuje iba autentifikáciu tokenov Microsoft Entra. Vzorový kód pre montáž jazera do /<mount_name>:

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

Pristupujte k súborom pod bodom pripojenia pomocou notebookutils fs API

Používajte mountové operácie, keď chcete pristupovať k dátam na vzdialenom úložisku cez lokálne API súborového systému. Môžete tiež pristupovať k pripojeným dátam pomocou notebookutils.fs API s pripojenou cestou, ale formát cesty sa líši.

Predpokladajme, že ste pripojili kontajner Data Lake Storage Gen2 mycontainer do /test pomocou rozhrania API pripojenia. Keď pristupujete k údajom pomocou rozhrania API lokálneho systému súborov, formát cesty je takýto:

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

Keď chcete pristupovať k dátam pomocou notebookutils fs API, použite getMountPath() presnú cestu:

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

• Zoznamové adresáre.

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

• Čítajte obsah súboru.

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

• Vytvorte adresár.

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

Prístup k súborom pod bodom pripojenia cez lokálnu cestu

Súbory môžete čítať a zapisovať do mount pointu pomocou štandardného súborového systému. Nasledujúci príklad v Pythone ukazuje tento vzorec:

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

Skontrolujte existujúce montážne body

Použite notebookutils.fs.mounts() API na kontrolu všetkých existujúcich informácií o bode montáže:

notebookutils.fs.mounts()

Prepitné

Vždy skontrolujte existujúce mounty pred vytvorením nových mountpointov mounts() , aby ste predišli konfliktom.

Pred montážou si over, či držiak existuje

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

Odmontujte montážny bod

Použite nasledujúci kód na odmontovanie montážneho bodu (/test v tomto príklade):

notebookutils.fs.unmount("/test")

Dôležité

Mechanizmus na odmontovanie sa automaticky neaplikuje. Po dokončení spustenia aplikácie musíte explicitne zavolať rozhranie API na zrušenie pripojenia a uvoľniť miesto na disku. Inak bod pripojenia zostáva v uzle aj po skončení spustenia aplikácie.

Pracovný postup mount-process-unmount

Pre spoľahlivé riadenie zdrojov zabalte operácie na montáž do bloku try/finally , aby ste zabezpečili, že čistenie prebehne aj v prípade chyby:

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

Známe obmedzenia

• Montáže sú konfigurácie na úrovni práce. Použite mounts API na overenie, či už existuje alebo je dostupný montážny bod.
• Odkopávanie sa nedeje automaticky. Keď spustenie aplikácie skončí, zavolajte v kóde API na odmontovanie, aby ste uvoľnili miesto na disku. V opačnom prípade zostáva montážny bod na uzle aj po skončení spustenia aplikácie.
• Montáž konta úložiska ADLS Gen1 nie je podporovaná.

Súvisiaci obsah

• NotebookUtils pre Fabric
• Nástroje súborového systému NotebookUtils