NotebookUtils fájl csatlakoztatása és leválasztása a Fabrichez

A NotebookUtils a Microsoft Spark Utilities csomagon keresztül támogatja a fájlok csatlakoztatását és leválasztási műveleteit. A mount, unmount, getMountPath()és mounts() API-k segítségével távoli tárolást (ADLS Gen2, Azure Blob Storage, OneLake) csatolhat az összes munkacsomóponthoz (illesztőprogram-csomópont és feldolgozó csomópont). A tárolási csatlakoztatási pont létrehozása után a helyi fájl API-val úgy érheti el az adatokat, mintha a helyi fájlrendszerben tárolva lenne.

A csatlakoztatási műveletek különösen akkor hasznosak, ha:

Helyi fájlelérési utakat elváró könyvtárakkal dolgozhat.
Konzisztens fájlrendszer-szemantikára van szükség a felhőbeli tárolókban.
A OneLake-billentyűparancsok (S3/GCS) hatékony elérése.
Több tárolási háttérrendszerrel működő hordozható kód létrehozása.

API-referencia

Az alábbi táblázat az elérhető csatlakoztatási API-kat foglalja össze:

Módszer	Signature	Leírás
`mount`	`mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean`	Távoli tároló csatlakoztatása a megadott csatlakoztatási ponton.
`unmount`	`unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean`	Leválasztja és eltávolítja a csatlakoztatási pontot.
`mounts`	`mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo]`	Az összes meglévő csatlakoztatási pont részletes listája.
`getMountPath`	`getMountPath(mountPoint: String, scope: String = ""): String`	A csatlakozási pont helyi fájlrendszerének elérési útját kéri le.

Hitelesítési módszerek

A csatlakoztatási műveletek számos hitelesítési módszert támogatnak. Válassza ki a metódust a tárolási típus és a biztonsági követelmények alapján.

Microsoft Entra-jogkivonat (alapértelmezett és ajánlott)

A Microsoft Entra token-hitelesítés a jegyzetfüzet-végrehajtó identitását használja, akár felhasználó, akár szolgáltatásneve. Nem igényel explicit hitelesítő adatokat a csatlakoztatási hívásban, ami a legbiztonságosabb lehetőséget teszi. Használja ezt az opciót a Lakehouse csatlakoztatásához és a Fabric munkaterület tárolásához.

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

Jótanács

Amikor csak lehetséges, használja a Microsoft Entra-jogkivonat-hitelesítést. Kiküszöböli a hitelesítő adatok expozíciójának kockázatát, és nem igényel további beállítást a Fabric-munkaterület tárolóihoz.

Fiókkulcs

Akkor használjon fiókkulcsot, ha a tárfiók nem támogatja a Microsoft Entra-hitelesítést, vagy ha külső vagy harmadik fél által biztosított tárolóhoz fér hozzá. Tárolja a fiókkulcsokat az Azure Key Vaultban, és kérje le őket az notebookutils.credentials.getSecret API-val.

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

Közös hozzáférési aláírás (SAS) jogkivonat

Használjon közös hozzáférésű jogosultságkód (SAS) jogkivonatot az időkorlátos, engedélyhatókörű hozzáféréshez. Ez a lehetőség akkor hasznos, ha ideiglenes hozzáférést kell adnia külső feleknek. SAS-jogkivonatokat tárol az Azure Key Vaultban.

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

Fontos

Biztonsági okokból ne ágyazza be a hitelesítő adatokat közvetlenül a kódba. A jegyzetfüzet kimeneteiben megjelenített titkokat automatikusan ki lesznek takarva. További információ: Titkos szerkesztés.

ADLS Gen2-fiók csatlakoztatása

Az alábbi példa az Azure Data Lake Storage Gen2 csatlakoztatását mutatja be. A Blob Storage és az Azure File Share csatlakoztatása hasonlóan működik.

Ez a példa feltételezi, hogy rendelkezik egy storegen2 nevű Data Lake Storage Gen2-fiókkal, amelyben egy mycontainer nevű tároló található, amelyet csatlakoztatni szeretne a jegyzetfüzet Spark-munkamenetében a /test.

A mycontainer nevű tároló csatlakoztatásához a NotebookUtilsnek először ellenőriznie kell, hogy rendelkezik-e engedéllyel a tároló eléréséhez. A Fabric jelenleg három hitelesítési módszert támogat az eseményindító csatlakoztatási műveletéhez: Microsoft Entra token (alapértelmezett), accountKey és sasToken.

Biztonsági okokból tárolja a fiókkulcsokat vagy SAS-jogkivonatokat az Azure Key Vaultban (ahogy az alábbi képernyőképen látható). Ezután lekérheti őket az notebookutils.credentials.getSecret API használatával. Az Azure Key Vaultról további információt az Azure Key Vault által felügyelt tárfiókkulcsokról szóló cikkben talál.

Mintakód az accountKey metódushoz:

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

Mintakód a sasTokenhez:

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

Csatlakoztatási paraméterek

A csatlakoztatási viselkedést a következő választható paraméterekkel hangolhatja a extraConfigs térképen:

fileCacheTimeout: A blobok alapértelmezés szerint 120 másodpercig gyorsítótárazva vannak a helyi ideiglenes mappában. Ez idő alatt a blobfuse nem ellenőrzi, hogy a fájl naprakész-e. Ezt a paramétert beállíthatja az alapértelmezett időtúllépési idő módosítására. Ha több ügyfél egyszerre módosítja a fájlokat, a helyi és a távoli fájlok közötti ellentmondások elkerülése érdekében lerövidíti a gyorsítótár idejét, vagy állítsa 0 értékre, hogy mindig a legújabb fájlokat szerezze be a kiszolgálóról.
időtúllépés: A csatlakoztatási művelet időkorlátja alapértelmezés szerint 30 másodperc. Ezt a paramétert beállíthatja az alapértelmezett időtúllépési idő módosítására. Ha túl sok kapacitás van, vagy ha a csatolási művelet túllépi az időkorlátot, növelje az értéket.

A következő paramétereket használhatja:

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

Gyorsítótár-konfigurációs javaslatok

A hozzáférési minta alapján válasszon egy gyorsítótár-időtúllépési értéket:

Scenario	Ajánlott `fileCacheTimeout`	Jegyzetek
Olvasás-intenzív, egy kliens	`120` (alapértelmezett)	Jó egyensúly a teljesítmény és a frissesség között.
Többügyfél-hozzáférés moderálása	`30`–`60`	Csökkenti az elavult adatok kockázatát.
Több ügyfél módosítja a fájlokat	`0`	Mindig lekéri a legújabbat a kiszolgálóról.
A fájlok ritkán változnak	`300`+	Optimalizálja az olvasási teljesítményt.

Nulla gyorsítótár-minta

Ha több ügyfél egyszerre módosítja a fájlokat, a gyorsítótár nélküli konfigurációval mindig lekérje a legújabb verziót a kiszolgálóról:

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

Megjegyzés:

Növelje a timeout paramétert, ha több végrehajtóval való csatolásról van szó, vagy ha időtúllépési hibákat tapasztal.

Lakehouse beépítése

A Lakehouse csatlakoztatása csak a Microsoft Entra-jogkivonatok hitelesítését támogatja. Mintakód egy Lakehouse csatlakoztatásához /<mount_name>:

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

Fájlok elérése a csatlakoztatási pont alatt a notebookutils fs API használatával

Csatlakoztatási műveleteket akkor használjon, ha távoli tárolóban lévő adatokat szeretne elérni egy helyi fájlrendszer API-jában. A csatlakoztatott adatokat a csatlakoztatott elérési út használatával az API-val notebookutils.fs is elérheti, de az elérési út formátuma eltér.

Tegyük fel, hogy csatlakoztatta a Data Lake Storage Gen2 konténert a /test elérési úthoz a mount API használatával. Amikor egy helyi fájlrendszer API-val éri el az adatokat, az elérési út formátuma a következő:

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

Ha az notebookutils fs API-val szeretné elérni az adatokat, használja a getMountPath() pontos elérési útját.

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

Címtárak listázása.

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

Fájltartalom olvasása.

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

Hozzon létre egy könyvtárat.

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

A csatlakoztatási pont alatti fájlok elérése helyi elérési úton

A szabványos fájlrendszerrel a csatlakoztatási pontokon is olvashat és írhat fájlokat. A következő Python-példa ezt a mintát mutatja be:

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

Meglévő csatlakoztatási pontok ellenőrzése

Az API használatával ellenőrizze az notebookutils.fs.mounts() összes meglévő csatlakoztatási pont adatait:

notebookutils.fs.mounts()

Jótanács

Az ütközések elkerülése érdekében mindig ellenőrizze a meglévő csatlakoztatási mounts() pontokat, mielőtt új csatlakoztatási pontokat hoz létre.

Csatlakoztatás előtt ellenőrizze, hogy létezik-e csatlakoztatás

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

A csatlakoztatási pont leválasztása

A csatlakoztatási pont leválasztásához használja az alábbi kódot (/tesztelje ebben a példában):

notebookutils.fs.unmount("/test")

Fontos

A leválasztó mechanizmus nem lesz automatikusan alkalmazva. Ha az alkalmazás futtatása befejeződött, a csatlakoztatási pont leválasztásához és a lemezterület felszabadításához explicit módon meg kell hívnia egy leválasztott API-t a kódban. Ellenkező esetben a csatlakoztatási pont az alkalmazás futtatása után is létezik a csomópontban.

Csatolás-feldolgozás-leválasztás munkafolyamat

A megbízható erőforrás-kezelés érdekében csomagolja be a csatlakoztatási műveleteket egy try/finally blokkba, hogy a törlés akkor is megtörténjen, ha hiba történik:

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

Ismert korlátozások

A csatlakoztatások feladatszintű konfigurációk. mounts Az API használatával ellenőrizze, hogy létezik-e már csatlakoztatási pont, vagy elérhető-e.
A leválasztás nem történik meg automatikusan. Amikor az alkalmazás futása befejeződik, hívjon meg egy unmount API-t a kódban a lemezterület felszabadításához. Ellenkező esetben a csatlakoztatási pont az alkalmazás futtatása után is a csomóponton marad.
Az ADLS Gen1-tárfiók csatlakoztatása nem támogatott.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2026-04-02