Προσάρτηση και αποπροσάρτηση αρχείου NotebookUtils για το Fabric

Το NotebookUtils υποστηρίζει λειτουργίες προσάρτησης και αποπροσάρτησης αρχείων μέσω του πακέτου Microsoft Spark Utilities. Μπορείτε να χρησιμοποιήσετε τα mount, unmount, getMountPath()και mounts() API για να συνδέσετε απομακρυσμένο χώρο αποθήκευσης (ADLS Gen2, Azure Blob Storage, OneLake) σε όλους τους κόμβους εργασίας (κόμβος προγράμματος οδήγησης και κόμβοι εργαζομένων). Αφού το σημείο μονταρίσματος χώρου αποθήκευσης είναι στη θέση του, χρησιμοποιήστε το τοπικό αρχείο API για να αποκτήσετε πρόσβαση στα δεδομένα σαν να είναι αποθηκευμένα στο τοπικό σύστημα αρχείων.

Οι λειτουργίες προσάρτησης είναι ιδιαίτερα χρήσιμες όταν:

• Εργαστείτε με βιβλιοθήκες που αναμένουν τοπικές διαδρομές αρχείων.
• Χρειάζεστε συνεπή σημασιολογία συστήματος αρχείων σε όλο το χώρο αποθήκευσης cloud.
• Αποκτήστε αποτελεσματική πρόσβαση στις συντομεύσεις OneLake (S3/GCS).
• Δημιουργήστε φορητό κώδικα που λειτουργεί με πολλαπλά backend αποθήκευσης.

Αναφορά API

Ο παρακάτω πίνακας συνοψίζει τα διαθέσιμα API προσάρτησης:

Μέθοδοι ελέγχου ταυτότητας

Οι λειτουργίες προσάρτησης υποστηρίζουν διάφορες μεθόδους ελέγχου ταυτότητας. Επιλέξτε τη μέθοδο με βάση τον τύπο αποθήκευσης και τις απαιτήσεις ασφαλείας.

Διακριτικό Microsoft Entra (προεπιλεγμένο και προτεινόμενο)

Ο έλεγχος ταυτότητας διακριτικού Microsoft Entra χρησιμοποιεί την ταυτότητα του εκτελεστή του σημειωματαρίου, είτε ενός χρήστη είτε ενός κύριου υπηρεσίας. Δεν απαιτεί ρητά διαπιστευτήρια στην κλήση προσάρτησης, γεγονός που το καθιστά την πιο ασφαλή επιλογή. Χρησιμοποιήστε αυτήν την επιλογή για τοποθέτηση Lakehouse και χώρο αποθήκευσης χώρου εργασίας Fabric.

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

Κλειδί λογαριασμού

Χρησιμοποιήστε ένα κλειδί λογαριασμού όταν ο λογαριασμός χώρου αποθήκευσης δεν υποστηρίζει έλεγχο ταυτότητας Microsoft Entra ή όταν αποκτάτε πρόσβαση σε εξωτερικό χώρο αποθήκευσης ή χώρο αποθήκευσης τρίτων. Αποθηκεύστε κλειδιά λογαριασμού στο Azure Key Vault και ανακτήστε τα με το 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)

Χρησιμοποιήστε ένα διακριτικό υπογραφής κοινόχρηστης πρόσβασης (SAS) για πρόσβαση περιορισμένου χρόνου με εμβέλεια δικαιωμάτων. Αυτή η επιλογή είναι χρήσιμη όταν πρέπει να εκχωρήσετε προσωρινή πρόσβαση σε εξωτερικά μέρη. Αποθηκεύστε διακριτικά SAS στο 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}
)

Προσάρτηση λογαριασμού ADLS Gen2

Το παρακάτω παράδειγμα δείχνει πώς μπορείτε να μοντάρετε το Azure Data Lake Storage Gen2. Η τοποθέτηση του χώρου αποθήκευσης αντικειμένων blob και του κοινόχρηστου στοιχείου αρχείων Azure λειτουργεί παρόμοια.

Αυτό το παράδειγμα προϋποθέτει ότι έχετε έναν λογαριασμό Data Lake Storage Gen2 με το όνομα storegen2, ο οποίος έχει ένα κοντέινερ με το όνομα mycontainer στο οποίο θέλετε να προσαρτήσετε /test στην περίοδο λειτουργίας Spark του σημειωματαρίου σας.

Για να προσαρτήσετε το κοντέινερ που ονομάζεται mycontainer, το NotebookUtils πρέπει πρώτα να ελέγξει εάν έχετε την άδεια πρόσβασης στο κοντέινερ. Προς το παρόν, το Fabric υποστηρίζει τρεις μεθόδους ελέγχου ταυτότητας για τη λειτουργία μονταρίσματος εναύσματος: Διακριτικό Microsoft Entra (προεπιλογή), accountKey και sasToken.

Για λόγους ασφαλείας, αποθηκεύστε τα κλειδιά λογαριασμού ή τα διακριτικά SAS στο Azure Key Vault (όπως δείχνει το παρακάτω στιγμιότυπο οθόνης). Στη συνέχεια, μπορείτε να τα ανακτήσετε χρησιμοποιώντας το notebookutils.credentials.getSecret API. Για περισσότερες πληροφορίες σχετικά με το Azure Key Vault, ανατρέξτε στο θέμα Πληροφορίες για τα κλειδιά λογαριασμού διαχειριζόμενου χώρου αποθήκευσης Azure Key Vault.

Δείγμα κώδικα για τη μέθοδο 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}
)

Δείγμα κώδικα για το 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}
)

Παράμετροι τοποθέτησης

Μπορείτε να ρυθμίσετε τη συμπεριφορά προσάρτησης με τις ακόλουθες προαιρετικές παραμέτρους στο extraConfigs χάρτη:

• fileCacheTimeout: Τα blob αποθηκεύονται προσωρινά στον τοπικό φάκελο temp για 120 δευτερόλεπτα από προεπιλογή. Κατά τη διάρκεια αυτής της περιόδου, το blobfuse δεν ελέγχει εάν το αρχείο είναι ενημερωμένο. Μπορείτε να ορίσετε αυτήν την παράμετρο για να αλλάξετε το προεπιλεγμένο χρονικό όριο. Όταν πολλοί υπολογιστές-πελάτες τροποποιούν αρχεία ταυτόχρονα, για να αποφύγετε ασυνέπειες μεταξύ τοπικών και απομακρυσμένων αρχείων, συντομεύστε το χρόνο προσωρινής αποθήκευσης ή ρυθμίστε τον σε 0 για να λαμβάνετε πάντα τα πιο πρόσφατα αρχεία από το διακομιστή.
• χρονικό όριο: Το χρονικό όριο λειτουργίας προσάρτησης είναι 30 δευτερόλεπτα από προεπιλογή. Μπορείτε να ορίσετε αυτήν την παράμετρο για να αλλάξετε το προεπιλεγμένο χρονικό όριο. Όταν υπάρχουν πάρα πολλοί εκτελεστές ή όταν λήξει το χρονικό όριο προσάρτησης, αυξήστε την τιμή.

Μπορείτε να χρησιμοποιήσετε αυτές τις παραμέτρους ως εξής:

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

Προτάσεις διαμόρφωσης προσωρινής μνήμης

Επιλέξτε μια τιμή χρονικού ορίου προσωρινής αποθήκευσης με βάση το μοτίβο πρόσβασής σας:

Μοτίβο μηδενικής κρυφής μνήμης

Όταν πολλοί υπολογιστές-πελάτες τροποποιούν αρχεία ταυτόχρονα, χρησιμοποιήστε μια ρύθμιση παραμέτρων μηδενικού cache για να λαμβάνετε πάντα την πιο πρόσφατη έκδοση από το διακομιστή:

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

Mount a Lakehouse

Η τοποθέτηση Lakehouse υποστηρίζει μόνο τον έλεγχο ταυτότητας διακριτικού Microsoft Entra. Δείγμα κώδικα για την προσάρτηση ενός Lakehouse στο /<mount_name>:

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

Αποκτήστε πρόσβαση σε αρχεία κάτω από το σημείο προσάρτησης χρησιμοποιώντας το notebookutils fs API

Χρησιμοποιήστε λειτουργίες προσάρτησης όταν θέλετε να αποκτήσετε πρόσβαση σε δεδομένα σε απομακρυσμένο χώρο αποθήκευσης μέσω ενός API τοπικού συστήματος αρχείων. Μπορείτε επίσης να αποκτήσετε πρόσβαση σε προσαρτημένα δεδομένα χρησιμοποιώντας το notebookutils.fs API με προσαρτημένη διαδρομή, αλλά η μορφή διαδρομής διαφέρει.

Ας υποθέσουμε ότι έχετε μοντάρει το κοντέινερ αποθήκευσης δεδομένων Gen2 mycontainer / test χρησιμοποιώντας το API μονταρίσματος. Όταν αποκτάτε πρόσβαση στα δεδομένα με ένα API τοπικού συστήματος αρχείων, η μορφή διαδρομής είναι ως εξής:

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

Όταν θέλετε να αποκτήσετε πρόσβαση στα δεδομένα χρησιμοποιώντας το API, χρησιμοποιήστε notebookutils fs το getMountPath() για να λάβετε την ακριβή διαδρομή:

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

• Λίστα καταλόγων.

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

• Διαβάστε το περιεχόμενο του αρχείου.

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

• Δημιουργήστε έναν κατάλογο.

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

Αρχεία πρόσβασης κάτω από το σημείο μονταρίσματος μέσω τοπικής διαδρομής

Μπορείτε να διαβάσετε και να γράψετε αρχεία σε ένα σημείο προσάρτησης χρησιμοποιώντας το τυπικό σύστημα αρχείων. Το ακόλουθο παράδειγμα Python δείχνει αυτό το μοτίβο:

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

Ελέγξτε τα υπάρχοντα σημεία προσάρτησης

Χρησιμοποιήστε το notebookutils.fs.mounts() API για να ελέγξετε όλες τις υπάρχουσες πληροφορίες σημείου προσάρτησης:

notebookutils.fs.mounts()

Ελέγξτε εάν υπάρχει βάση πριν την τοποθέτηση

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

Αποπροσάρτηση του σημείου προσάρτησης

Χρησιμοποιήστε τον ακόλουθο κώδικα για να αποπροσαρτήσετε το σημείο προσάρτησης (/test σε αυτό το παράδειγμα):

notebookutils.fs.unmount("/test")

Ροή εργασιών προσάρτησης-διεργασίας-αποπροσάρτησης

Για αξιόπιστη διαχείριση πόρων, αναδιπλώστε τις λειτουργίες προσάρτησης σε ένα try/finally μπλοκ για να διασφαλίσετε ότι η εκκαθάριση θα πραγματοποιηθεί ακόμα και αν παρουσιαστεί σφάλμα:

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

Γνωστοί περιορισμοί

• Οι μονταρισμοί είναι διαμορφώσεις σε επίπεδο εργασίας. Χρησιμοποιήστε το mounts API για να ελέγξετε εάν ένα σημείο προσάρτησης υπάρχει ήδη ή είναι διαθέσιμο.
• Η αποπροσάρτηση δεν γίνεται αυτόματα. Όταν ολοκληρωθεί η εκτέλεση της εφαρμογής, καλέστε ένα API αποπροσάρτησης στον κώδικά σας για να απελευθερώσετε χώρο στο δίσκο. Διαφορετικά, το σημείο προσάρτησης παραμένει στον κόμβο μετά την ολοκλήρωση της εκτέλεσης της εφαρμογής.
• Η τοποθέτηση ενός λογαριασμού χώρου αποθήκευσης ADLS Gen1 δεν υποστηρίζεται.

Σχετικό περιεχόμενο

• NotebookUtils για ύφασμα
• Βοηθητικά προγράμματα συστήματος αρχείων NotebookUtils