NotebookUtils-bestand koppelen en ontkoppelen voor Fabric

NotebookUtils ondersteunt bewerkingen voor het koppelen en ontkoppelen van bestanden via het Microsoft Spark Utilities-pakket. U kunt de mount, unmounten getMountPath()mounts() API's gebruiken om externe opslag (ADLS Gen2, Azure Blob Storage, OneLake) te koppelen aan alle werkende knooppunten (stuurprogrammaknooppunt en werkknooppunten). Nadat het opslagkoppelingspunt is ingesteld, gebruikt u de API voor het lokale bestand om toegang te krijgen tot gegevens alsof deze zijn opgeslagen in het lokale bestandssysteem.

Koppelbewerkingen zijn met name handig wanneer u:

• Werk met bibliotheken die lokale bestandspaden verwachten.
• Consistente semantiek van bestandssysteem in cloudopslag nodig.
• Krijg efficiënt toegang tot OneLake-snelkoppelingen (S3/GCS).
• Bouw draagbare code die werkt met meerdere back-ends voor opslag.

API-referentie

De volgende tabel bevat een overzicht van de beschikbare koppelings-API's:

Verificatiemethoden

Koppelingsbewerkingen ondersteunen verschillende verificatiemethoden. Kies de methode op basis van uw opslagtype en beveiligingsvereisten.

Microsoft Entra-token (standaard en aanbevolen)

Microsoft Entra-tokenverificatie maakt gebruik van de identiteit van de notebookexecutor, ofwel een gebruiker of service-principal. Er zijn geen expliciete referenties vereist in de koppelingsoproep, waardoor deze de veiligste optie is. Gebruik deze optie voor Lakehouse-montage en opslag in de Fabric-werkruimte.

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

Sleutel voor account

Gebruik een accountsleutel wanneer het opslagaccount geen ondersteuning biedt voor Microsoft Entra-verificatie, of wanneer u toegang hebt tot externe opslag of opslag van derden. Sla accountsleutels op in Azure Key Vault en haal deze op met de 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}
)

Sas-token (Shared Access Signature)

Gebruik een SAS-token (Shared Access Signature) voor tijdgebonden toegangsbereik. Deze optie is handig wanneer u tijdelijke toegang moet verlenen aan externe partijen. SAS-tokens opslaan 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}
)

Een ADLS Gen2-account koppelen

In het volgende voorbeeld ziet u hoe u Azure Data Lake Storage Gen2 koppelt. Het koppelen van Blob Storage en Azure-bestandsshare werkt op dezelfde manier.

In dit voorbeeld wordt ervan uitgegaan dat u één Data Lake Storage Gen2-account hebt met de naam storegen2, met een container met de naam mycontainer die u wilt koppelen aan /test in uw Spark-sessie van uw notebook.

Als u de container met de naam mycontainer wilt koppelen, moet NotebookUtils eerst controleren of u gemachtigd bent om toegang te krijgen tot de container. Momenteel ondersteunt Fabric drie verificatiemethoden voor de triggerkoppelingsbewerking: Microsoft Entra-token (standaard), accountKey en sasToken.

Sla om veiligheidsredenen accountsleutels of SAS-tokens op in Azure Key Vault (zoals in de volgende schermopname wordt weergegeven). U kunt ze vervolgens ophalen met behulp van de notebookutils.credentials.getSecret API. Voor meer informatie over Azure Key Vault, zie Over door Azure Key Vault beheerde opslagaccount-sleutels.

Voorbeeldcode voor de 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}
)

Voorbeeldcode voor 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}
)

Parameters koppelen

U kunt het koppelgedrag afstemmen met de volgende optionele parameters in de extraConfigs map.

• fileCacheTimeout: Blobs worden standaard gedurende 120 seconden in de lokale tijdelijke map opgeslagen. Gedurende deze tijd controleert blobfuse niet of het bestand up-to-date is. U kunt deze parameter instellen om de standaardtime-outtijd te wijzigen. Wanneer meerdere clients tegelijkertijd bestanden wijzigen, om inconsistenties tussen lokale en externe bestanden te voorkomen, verkort u de cachetijd of stelt u deze in op 0 om altijd de meest recente bestanden van de server op te halen.
• time-out: de time-out voor de koppelbewerking is standaard 30 seconden. U kunt deze parameter instellen om de standaardtime-outtijd te wijzigen. Als er te veel uitvoerders zijn of wanneer er een time-out optreedt tijdens het koppelen, verhoogt u de waarde.

U kunt deze parameters als volgt gebruiken:

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

Aanbevelingen voor cacheconfiguratie

Kies een time-outwaarde voor de cache op basis van uw toegangspatroon:

Patroon zonder cache

Wanneer meerdere clients tegelijkertijd bestanden wijzigen, gebruikt u een configuratie zonder cache om altijd de nieuwste versie van de server op te halen:

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

Een Lakehouse mounten

Lakehouse-koppeling ondersteunt alleen Verificatie van Microsoft Entra-tokens. Voorbeeldcode voor het koppelen van een Lakehouse aan /<mount_name>:

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

Toegang tot bestanden onder het koppelpunt met behulp van de notebookutils fs-API

Gebruik koppelingsbewerkingen wanneer u toegang wilt krijgen tot gegevens in externe opslag via een lokale bestandssysteem-API. U kunt ook toegang krijgen tot gekoppelde gegevens met behulp van de notebookutils.fs API met een gekoppeld pad, maar de padindeling verschilt.

Stel dat u de Data Lake Storage Gen2-container mycontainer hebt gekoppeld aan /test met behulp van de mount-API. Wanneer u toegang krijgt tot de gegevens met een API voor een lokaal bestandssysteem, ziet de padindeling er als volgt uit:

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

Wanneer u toegang wilt krijgen tot de gegevens met behulp van de notebookutils fs API, gebruik getMountPath() om het nauwkeurige pad op te halen.

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

• Mappen weergeven.

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

• Bestandsinhoud lezen.

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

• Maak een map.

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

Toegang tot bestanden bij het koppelpunt via een lokaal pad

U kunt bestanden in een koppelpunt lezen en schrijven met behulp van het standaardbestandssysteem. In het volgende Python-voorbeeld ziet u dit patroon:

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

Bestaande koppelpunten controleren

Gebruik de notebookutils.fs.mounts() API om alle bestaande koppelingspuntgegevens te controleren:

notebookutils.fs.mounts()

Controleer of er een mount bestaat voordat u monteert

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

Het koppelpunt ontkoppelen

Gebruik de volgende code om het koppelpunt los te koppelen (/test in dit voorbeeld):

notebookutils.fs.unmount("/test")

Mounten-proces-unmounten werkstroom

Voor betrouwbaar resourcebeheer verpakken koppelbewerkingen in een try/finally blok om ervoor te zorgen dat opschoning plaatsvindt, zelfs als er een fout optreedt:

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

Bekende beperkingen

• Mounts zijn configuraties op werkplekniveau. Gebruik de mounts API om te controleren of er al een koppelpunt bestaat of beschikbaar is.
• Ontkoppelen gebeurt niet automatisch. Wanneer de uitvoering van de toepassing is voltooid, roept u een ontkoppelde API in uw code aan om schijfruimte vrij te geven. Anders blijft het koppelpunt op het knooppunt staan nadat de uitvoering van de toepassing is voltooid.
• Het koppelen van een ADLS Gen1-opslagaccount wordt niet ondersteund.

Verwante inhoud

• NotebookUtils voor Fabric
• Hulpprogramma's voor notebookUtils-bestandssysteem