NotebookUtils-Dateieinhängen und -aushängen für Fabric

NotebookUtils unterstützt Einbinde- und Aushängeoperationen für Dateien über das Microsoft Spark Utilities-Paket. Sie können die mount, unmount, getMountPath() und mounts() APIs verwenden, um Remotespeicher (ADLS Gen2, Azure Blob Storage, OneLake) an alle Arbeitsknoten (Masterknoten und Workerknoten) anzuhängen. Wenn der Bereitstellungspunkt für den Speicher vorhanden ist, können Sie die lokale Datei-API verwenden, um auf Daten zuzugreifen, als ob sie im lokalen Dateisystem gespeichert wären.

Montagevorgänge sind besonders nützlich, wenn Sie:

• Arbeiten Sie mit Bibliotheken, die lokale Dateipfade erwarten.
• Benötigen Sie konsistente Dateisystemsemantik im gesamten Cloudspeicher.
• Greifen Sie effizient auf OneLake-Tastenkombinationen (S3/GCS) zu.
• Erstellen Sie portablen Code, der mit mehreren Speicher-Back-Ends funktioniert.

API-Referenz

In der folgenden Tabelle sind die verfügbaren Mount-APIs zusammengefasst.

Authentifizierungsmethoden

Einbindevorgänge unterstützen mehrere Authentifizierungsmethoden. Wählen Sie die Methode basierend auf Ihrem Speichertyp und den Sicherheitsanforderungen aus.

Microsoft Entra-Token (Standard und empfohlen)

Die Microsoft Entra-Tokenauthentifizierung verwendet die Identität des Notizbuchausführers, entweder eines Benutzers oder eines Dienstprinzipals. Für den Bereitstellungsaufruf sind keine expliziten Anmeldeinformationen erforderlich, wodurch es die sicherste Option ist. Verwenden Sie diese Option für Lakehouse-Montage und Fabric-Arbeitsbereichsspeicher.

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

Kontoschlüssel

Verwenden Sie einen Kontoschlüssel, wenn das Speicherkonto die Microsoft Entra-Authentifizierung nicht unterstützt oder wenn Sie auf externen oder Drittanbieterspeicher zugreifen. Speichern Sie Kontoschlüssel in Azure Key Vault, und rufen Sie sie mit der notebookutils.credentials.getSecret API ab.

# 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 (Shared Access Signature)

Verwenden Sie ein SAS-Token (Shared Access Signature) für zeitlich begrenzten Zugriff mit Berechtigungsbereich. Diese Option ist nützlich, wenn Sie temporären Zugriff auf externe Parteien gewähren müssen. Speichern Sie SAS-Token in 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}
)

Bereitstellen eines ADLS Gen2-Kontos

Das folgende Beispiel veranschaulicht, wie Sie Azure Data Lake Storage Gen2 einbinden. Die Einbindung von Blob Storage und Azure File Share funktioniert ähnlich.

In diesem Beispiel wird angenommen, dass Sie über ein Data Lake Storage Gen2-Konto mit dem Namen storegen2 verfügen, das einen Container mit dem Namen mycontainer enthält, den Sie in Ihrer Notebook-Spark-Sitzung an den Pfad /test einbinden möchten.

Um den Container mit dem Namen "mycontainer" zu mounten, muss NotebookUtils zuerst überprüfen, ob Sie über die Berechtigung zum Zugriff auf den Container verfügen. Derzeit unterstützt Fabric drei Authentifizierungsmethoden für den Trigger-Bereitstellungsvorgang: Microsoft Entra-Token (Standard), accountKey und sasToken.

Aus Sicherheitsgründen speichern Sie Kontoschlüssel oder SAS-Token in Azure Key Vault (wie im folgenden Screenshot gezeigt). Sie können sie dann mithilfe der notebookutils.credentials.getSecret-API abrufen. Weitere Informationen zu Azure Key Vault finden Sie unter Informationen zu mit Azure Key Vault verwalteten Speicherkontoschlüsseln.

Beispielcode für die accountKey-Methode:

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

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

Mountparameter

Sie können das Bereitstellungsverhalten mit den folgenden optionalen Parametern in der extraConfigs Map einstellen:

• fileCacheTimeout: Blobs werden standardmäßig 120 Sekunden im lokalen temporären Ordner zwischengespeichert. Während dieser Zeit überprüft Blobfuse nicht, ob die Datei auf dem neuesten Stand ist. Sie können diesen Parameter festlegen, um die Standardtimeoutzeit zu ändern. Wenn mehrere Clients Dateien gleichzeitig ändern, um Inkonsistenzen zwischen lokalen und Remotedateien zu vermeiden, kürzen Sie die Cachezeit, oder legen Sie sie auf 0 fest, um immer die neuesten Dateien vom Server abzurufen.
• Timeout: Das Timeout für den Einbindungsvorgang ist standardmäßig 30 Sekunden. Sie können diesen Parameter festlegen, um die Standardtimeoutzeit zu ändern. Wenn zu viele Executoren vorhanden sind oder wenn die Bereitstellung zeitlich überschreitet, erhöhen Sie den Wert.

Sie können diese Parameter wie folgt verwenden:

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

Empfehlungen für die Cachekonfiguration

Wählen Sie einen Cachetimeoutwert basierend auf Ihrem Zugriffsmuster aus:

Zero-Cache-Muster

Wenn mehrere Clients Dateien gleichzeitig ändern, verwenden Sie eine Zero-Cache-Konfiguration, um immer die neueste Version vom Server abzurufen:

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

Einrichten eines Lakehouse

Lakehouse-Montage unterstützt nur die Microsoft Entra-Tokenauthentifizierung. Beispielcode für die Einbindung eines Lakehouse unter /<mount_name>:

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

Zugreifen auf Dateien unter dem Bereitstellungspunkt mithilfe der notebookutils fs-API

Verwenden Sie Bereitstellungsvorgänge, wenn Sie über eine lokale Dateisystem-API auf Daten im Remotespeicher zugreifen möchten. Sie können auch auf bereitgestellte Daten zugreifen, indem Sie die notebookutils.fs API mit einem bereitgestellten Pfad verwenden, aber das Pfadformat unterscheidet sich.

Angenommen, Sie haben den Data Lake Storage Gen2-Container mycontainer mithilfe der Bereitstellungs-API unter /test eingebunden. Wenn Sie mithilfe der lokalen Dateisystem-API auf die Daten zugreifen, sieht das Pfadformat wie folgt aus:

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

Wenn Sie mithilfe der notebookutils fs API auf die Daten zugreifen möchten, verwenden Sie getMountPath(), um den genauen Pfad abzurufen:

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

• Verzeichnisse auflisten.

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

• Dateiinhalt lesen.

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

• Erstellen Sie ein Verzeichnis.

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

Zugreifen auf Dateien unter dem Bereitstellungspunkt über einen lokalen Pfad

Sie können Dateien in einem Bereitstellungspunkt lesen und schreiben, indem Sie das Standarddateisystem verwenden. Das folgende Python-Beispiel zeigt dieses Muster:

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

Überprüfen vorhandener Bereitstellungspunkte

Verwenden Sie die notebookutils.fs.mounts() API, um alle vorhandenen Bereitstellungspunktinformationen zu überprüfen:

notebookutils.fs.mounts()

Überprüfen, ob eine Einbindung existiert, bevor sie eingebunden wird.

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

Aufheben des Bereitstellungspunkts

Verwenden Sie den folgenden Code, um den Einhängepunkt auszuhängen (/test in diesem Beispiel):

notebookutils.fs.unmount("/test")

Mount-Prozess-Unmount-Workflow

Um eine zuverlässige Ressourcenverwaltung zu gewährleisten, schließen Sie Montagevorgänge in einen try/finally Block ein, um sicherzustellen, dass die Bereinigung auch dann erfolgt, wenn ein Fehler auftritt:

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

Bekannte Einschränkungen

• Mounts sind Konfigurationen auf Jobebene. Verwenden Sie die mounts API, um zu überprüfen, ob bereits ein Bereitstellungspunkt vorhanden oder verfügbar ist.
• Das Aushängen erfolgt nicht automatisch. Wenn der Anwendungslauf beendet ist, rufen Sie eine Unmount-API in Ihrem Code auf, um Speicherplatz freizugeben. Andernfalls verbleibt der Bereitstellungspunkt auf dem Knoten, nachdem der Ausführungslauf der Anwendung endet.
• Das Einbinden eines ADLS Gen1-Speicherkontos wird nicht unterstützt.

Verwandte Inhalte

• NotebookUtils für Fabric
• NotebookUtils-Dateisystemprogramme