NotebookUtils připojení a odpojení souboru pro Fabric

NotebookUtils podporuje operace připojení a odpojování souborů prostřednictvím balíčku Microsoft Spark Utilities. Pomocí rozhraní API mount, unmount, getMountPath() a mounts() můžete připojit vzdálené úložiště (ADLS Gen2, Azure Blob Storage, OneLake) ke všem pracovním uzlům (uzel ovladače a pracovní uzly). Po umístění přípojného bodu úložiště použijte místní souborové rozhraní API pro přístup k datům, jako by byla uložena v místním systému souborů.

Operace připojení jsou užitečné zejména v následujících případech:

  • Pracujte s knihovnami, které očekávají místní cesty k souborům.
  • Potřebujete konzistentní sémantiku systému souborů napříč cloudovým úložištěm.
  • Efektivní přístup ke zkratkám OneLake (S3/GCS).
  • Sestavte přenosný kód, který funguje s několika úložišťovými rozhraními.

Referenční informace k rozhraní API

Následující tabulka shrnuje dostupná rozhraní API pro připojení:

Metoda Signature Description
mount mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean Připojí vzdálené úložiště k zadanému přípojovému bodu.
unmount unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean Odpojí a odebere přípojný bod.
mounts mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo] Zobrazí seznam všech existujících přípojných bodů s podrobnostmi.
getMountPath getMountPath(mountPoint: String, scope: String = ""): String Získá cestu místního systému souborů pro připojovací bod.

Metody ověřování

Operace montování podporují několik metod ověřování. Zvolte metodu na základě vašeho typu úložiště a požadavků na zabezpečení.

Ověřování tokenu Microsoft Entra používá identitu spouštěče notebooku, ať už je to uživatel nebo instanční objekt. Nevyžaduje explicitní přihlašovací údaje v příkazu připojení, což z něj dělá nejbezpečnější možnost. Tuto možnost použijte pro montáž v jezeře a skladování Fabric workspace.

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

Návod

Kdykoli je to možné, použijte ověřování tokenu Microsoft Entra. Eliminuje riziko vystavení přihlašovacích údajů a nevyžaduje žádné další nastavení úložiště pracovního prostoru Fabric.

Klíč účtu

Klíč účtu použijte, pokud účet úložiště nepodporuje ověřování Microsoft Entra nebo když přistupujete k externímu úložišti nebo úložišti třetích stran. Ukládejte klíče účtu ve službě notebookutils.credentials.getSecret Azure Key Vault a načtěte je pomocí rozhraní 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 sdíleného přístupového podpisu (SAS)

Použijte token sdíleného přístupového podpisu (SAS) pro časově omezený přístup s oborem oprávnění. Tato možnost je užitečná, když potřebujete udělit dočasný přístup externím stranám. Ukládejte tokeny SAS ve službě 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é

Pro účely zabezpečení se vyhněte vkládání přihlašovacích údajů přímo do kódu. Všechna tajemství zobrazená ve výstupech notebooku se automaticky odstraňují. Další informace najdete v části Tajná redakce.

Připojení účtu ADLS Gen2

Následující příklad ukazuje, jak připojit Azure Data Lake Storage Gen2. Připojení služby Blob Storage a služby Azure File Share funguje podobně.

Tento příklad předpokládá, že máte jeden účet Data Lake Storage Gen2 s názvem storegen2, který má kontejner s názvem mycontainer , který chcete připojit k /test v relaci Sparku poznámkového bloku.

Snímek obrazovky znázorňující, kde vybrat kontejner, který se má připojit

Pokud chcete připojit kontejner s názvem mycontainer, musí nástroj NotebookUtils nejprve zkontrolovat, jestli máte oprávnění pro přístup k kontejneru. Fabric v současné době podporuje tři metody ověřování pro operaci připojení triggeru: token Microsoft Entra (výchozí), accountKey a sasToken.

Z bezpečnostních důvodů ukládejte klíče účtu nebo tokeny SAS ve službě Azure Key Vault (jak ukazuje následující snímek obrazovky). Pak je můžete načíst pomocí notebookutils.credentials.getSecret rozhraní API. Další informace o službě Azure Key Vault najdete v tématu o klíčích účtu spravovaného úložiště služby Azure Key Vault.

Snímek obrazovky znázorňující, kde jsou tajné kódy uložené ve službě Azure Key Vault

Ukázkový kód pro metodu 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ázkový kód pro 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}
)

Parametry připojení

Chování připojení můžete vyladit pomocí následujících volitelných parametrů v mapě extraConfigs :

  • fileCacheTimeout: Objekty blob se ve výchozím nastavení ukládají do místní dočasné složky po dobu 120 sekund. Během této doby blobfuse nekontroluje, jestli je soubor aktuální. Tento parametr můžete nastavit tak, aby změnil výchozí časový limit. Pokud více klientů současně upravuje soubory, aby nedocházelo k nekonzistence mezi místními a vzdálenými soubory, zkraťte dobu mezipaměti nebo ji nastavte na 0, abyste vždy získali nejnovější soubory ze serveru.
  • časový limit: Časový limit operace připojení je ve výchozím nastavení 30 sekund. Tento parametr můžete nastavit tak, aby změnil výchozí časový limit. Pokud je příliš mnoho vykonavatelů nebo když vyprší časový limit montáže, zvyšte hodnotu.

Můžete použít následující parametry:

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

Doporučení konfigurace mezipaměti

Na základě vzoru přístupu zvolte hodnotu časového limitu mezipaměti:

Scénář Doporučené fileCacheTimeout Poznámky
Vysoká zátěž při čtení, jednotlivý klient 120 (výchozí) Dobrá vyváženost výkonu a aktuálnosti.
Moderování přístupu s více klienty 30–60 Snižuje riziko zastaralých dat.
Více klientů, kteří upravují soubory 0 Vždy stahuje nejnovější data ze serveru.
Zřídka se mění soubory 300+ Optimalizuje výkon čtení.

Model nulové mezipaměti

Pokud více klientů současně upravuje soubory, použijte konfiguraci nulové mezipaměti, abyste vždy načetli nejnovější verzi ze serveru:

# 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šte parametr timeout při připojování s mnoha vykonavateli nebo pokud dochází k chybám časového limitu.

Připojení úložiště Lakehouse

Připojení Lakehouse podporuje pouze ověřování tokenů Microsoft Entra. Vzorový kód pro připojení jezera k /<mount_name>:

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

Přístup k souborům pod přípojným bodem pomocí rozhraní API notebookutils fs

Operace připojení použijte, když chcete získat přístup k datům ve vzdáleném úložišti prostřednictvím místního rozhraní API systému souborů. K připojeným datům můžete přistupovat také pomocí notebookutils.fs rozhraní API s připojenou cestou, ale formát cesty se liší.

Předpokládejme, že jste kontejner Data Lake Storage Gen2 připojili mycontainer k /test pomocí rozhraní API pro připojení. Při přístupu k datům pomocí místního rozhraní API systému souborů je formát cesty podobný tomuto:

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

Pokud chcete získat přístup k datům pomocí notebookutils fs rozhraní API, použijte getMountPath() k získání přesné cesty:

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

  • Seznam adresářů

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

  • Přečíst obsah souboru

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

  • Vytvořte adresář.

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

Přístup k souborům pod přípojným bodem prostřednictvím místní cesty

Soubory můžete číst a zapisovat do přípojného bodu pomocí standardního systému souborů. Následující příklad Pythonu ukazuje tento vzor:

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

Kontrola existujících přípojných bodů

notebookutils.fs.mounts() Pomocí rozhraní API zkontrolujte všechny existující informace o přípojné bodě:

notebookutils.fs.mounts()

Návod

Před vytvořením nových přípojných bodů vždy zkontrolujte existující přípojné body mounts(), abyste se vyhnuli konfliktům.

Zkontrolujte, zda před připojením existuje přípojný bod.

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

Odpojte přípojný bod

Pomocí následujícího kódu odpojte přípojný bod (/otestujte v tomto příkladu):

notebookutils.fs.unmount("/test")

Důležité

Mechanismus odpojování se nepoužije automaticky. Po dokončení spuštění aplikace je potřeba odpojit přípojný bod a uvolnit místo na disku, musíte v kódu explicitně volat rozhraní API pro odpojení. Jinak přípojný bod stále existuje v uzlu po dokončení spuštění aplikace.

Pracovní postup připojení-proces-odpojení

Pro spolehlivou správu prostředků zabalte operace připojení do bloku try/finally, aby byl zajištěn úklid i v případě 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ámá omezení

  • Připojovací body jsou konfigurace na úrovni úlohy. mounts Pomocí rozhraní API zkontrolujte, jestli přípojný bod již existuje nebo je k dispozici.
  • K odpojování nedochází automaticky. Po dokončení spuštění aplikace volejte rozhraní API pro odpojení v kódu a uvolněte místo na disku. Jinak přípojný bod zůstane na uzlu po dokončení spuštění aplikace.
  • Připojení účtu úložiště ADLS Gen1 se nepodporuje.

Související obsah

  • Last updated on