NotebookUtils dosyası bağlama ve Doku için çıkarma

NotebookUtils, Microsoft Spark Yardımcı Programları paketi aracılığıyla dosya bağlama ve çıkarma işlemlerini destekler. Uzak depolama (ADLS 2. Nesil, Azure Blob Depolama, OneLake) tüm çalışma düğümlerine (sürücü düğümü ve çalışan düğümler) eklemek için mount, unmount, getMountPath() ve mounts() API'lerini kullanabilirsiniz. Depolama bağlama noktası gerçekleştikten sonra yerel dosya API'sini kullanarak verilere yerel dosya sisteminde depolanmış gibi erişin.

Bağlama işlemleri özellikle aşağıdaki durumlarda kullanışlıdır:

• Yerel dosya yollarını bekleyen kitaplıklarla çalışın.
• Bulut depolamada tutarlı dosya sistemi semantiği gerekiyor.
• OneLake kısayollarına (S3/GCS) verimli bir şekilde erişin.
• Birden çok depolama arka ucuyla çalışan taşınabilir kod oluşturun.

API referansı

Aşağıdaki tabloda kullanılabilir bağlama API'leri özetlemektedir:

Yöntem	Signature	Açıklama
mount	mount(source: String, mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Uzak depolamayı belirtilen bağlama noktasına bağlar.
unmount	unmount(mountPoint: String, extraConfigs: Map[String, Any] = None): Boolean	Bağlamayı kaldırır ve bağlama noktasını çıkarır.
mounts	mounts(extraOptions: Map[String, Any] = None): Array[MountPointInfo]	Tüm mevcut bağlama noktalarını ayrıntılarıyla listeler.
getMountPath	getMountPath(mountPoint: String, scope: String = ""): String	Bağlama noktası için yerel dosya sistemi yolunu alır.

Kimlik doğrulama yöntemleri

Bağlama işlemleri çeşitli kimlik doğrulama yöntemlerini destekler. Depolama türünüz ve güvenlik gereksinimlerinize göre yöntemini seçin.

Microsoft Entra belirteci (varsayılan ve önerilen)

Microsoft Entra belirteci kimlik doğrulaması, not defteri yürütücüsünün kimliğini (kullanıcı veya hizmet sorumlusu) kullanır. Bağlama çağrısında açık kimlik bilgileri gerektirmez ve bu da onu en güvenli seçenek haline getirir. Lakehouse bağlama ve Fabric çalışma alanı için depolama amacıyla bu seçeneği kullanın.

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

Tavsiye

Mümkün olduğunda Microsoft Entra kimlik doğrulaması belirtecini kullanın. Kimlik bilgilerinin ortaya çıkma riskini ortadan kaldırır ve Fabric çalışma alanı depolaması için ek kurulum gerektirmez.

Hesap anahtarı

Depolama hesabı Microsoft Entra kimlik doğrulamasını desteklemediğinde ya da dış veya üçüncü taraf depolamaya erişirken hesap anahtarı kullanın. Hesap anahtarlarını Azure Key Vault'ta depolayın ve notebookutils.credentials.getSecret API'si aracılığıyla alın.

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

Paylaşılan erişim imzası (SAS) belirteci

Zaman sınırlı, yetki sınırlandırılmış erişim için paylaşılan erişim imzası (SAS) belirteci kullanın. Bu seçenek, dış taraflara geçici erişim vermeniz gerektiğinde kullanışlıdır. SAS belirteçlerini Azure Key Vault'ta depolayın.

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

Önemli

Güvenlik amacıyla kimlik bilgilerini doğrudan koda eklemekten kaçının. Not defteri çıktılarında görüntülenen herhangi bir gizli bilgi otomatik olarak kapatılır. Daha fazla bilgi için bkz Gizli düzenleme.

ADLS 2. Nesil hesabını bağlama

Aşağıdaki örnek, Azure Data Lake Storage 2. Nesil'nin nasıl bağlanacağını göstermektedir. Blob Depolama birimi ekleme ve Azure Dosya Paylaşımı'nı bağlama aynı şekilde çalışır.

Bu örnek, storegen2adında bir Data Lake Storage 2. Nesil hesabınızın ve not defteri Spark oturumunuzda /test konumuna eklemek istediğiniz mycontainer adlı bir kapsayıcınızın olduğunu varsayar.

mycontainer adlı kapsayıcıyı bağlamak için NotebookUtils'in önce kapsayıcıya erişme izniniz olup olmadığını denetlemesi gerekir. Şu anda Fabric, tetikleyici bağlama işlemi için üç kimlik doğrulama yöntemini destekler: Microsoft Entra jetonu (varsayılan), accountKey ve sasToken.

Güvenlik nedeniyle, hesap anahtarlarını veya SAS belirteçlerini Azure Key Vault'ta depolayın (aşağıdaki ekran görüntüsünde gösterildiği gibi). Daha sonra API'yi notebookutils.credentials.getSecret kullanarak bunları alabilirsiniz. Azure Key Vault hakkında daha fazla bilgi için Azure Key Vault yönetilen depolama hesabı anahtarları hakkında bölümüne bakın.

accountKey yöntemi için örnek kod:

# 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 için örnek kod:

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

Bağlama parametreleri

Bağlama davranışını, extraConfigs haritasında aşağıdaki isteğe bağlı parametrelerle ayarlayabilirsiniz.

• fileCacheTimeout: Bloblar varsayılan olarak 120 saniye boyunca yerel geçici klasörde önbelleğe alınır. Bu süre boyunca blobfuse dosyanın güncel olup olmadığını denetlemez. Varsayılan zaman aşımı süresini değiştirmek için bu parametreyi ayarlayabilirsiniz. Birden çok istemci dosyaları aynı anda değiştirdiğinde, yerel ve uzak dosyalar arasındaki tutarsızlıkları önlemek için önbellek süresini kısaltın veya her zaman sunucudan en son dosyaları almak için 0 olarak ayarlayın.
• zaman aşımı: Bağlama işlemi zaman aşımı varsayılan olarak 30 saniyedir. Varsayılan zaman aşımı süresini değiştirmek için bu parametreyi ayarlayabilirsiniz. Yürütücüler çok fazla olduğunda veya bağlama işlemi zaman aşımına uğradığında, değeri artırın.

Aşağıdaki gibi parametreleri kullanabilirsiniz:

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

Önbellek yapılandırma önerileri

Erişim deseninize göre bir önbellek zaman aşımı değeri seçin:

Scenario	Önerilen fileCacheTimeout	Notlar
Okuma ağırlıklı, tek istemci	120 (varsayılan)	İyi performans ve tazelik dengesi.
Çok istemcili erişimi denetleme	30–60	Eski veri riskini azaltır.
Dosyaları değiştiren birden çok istemci	0	Her zaman en son sürümü sunucudan getirir.
Dosyalar nadiren değişir	300+	Okuma performansını iyileştirir.

Sıfır önbellek şablonu

Birden çok istemci dosyaları aynı anda değiştirdiğinde, her zaman sunucudan en son sürümü getirmek için sıfır önbellekli bir yapılandırma kullanın:

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

Uyarı

timeout parametresini çok sayıda yürütücüyle monte ederken veya zaman aşımı hatalarıyla karşılaştığınızda artırın.

Lakehouse'u Monte Et

Lakehouse bağlaması yalnızca Microsoft Entra token kimlik doğrulamasını destekler. Bir Lakehouse'ı /<mount_name'a> bağlamak için örnek kod:

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

Notebookutils fs API'sini kullanarak bağlama noktası altındaki dosyalara erişme

Yerel dosya sistemi API'sini kullanarak uzak depolamadaki verilere erişmek istediğinizde bağlama işlemlerini kullanın. API'yi, bağlı bir yol ile notebookutils.fs kullanarak da bağlı verilere erişebilirsiniz, ancak yolun biçimi farklıdır.

Mount API'sini kullanarak Data Lake Storage 2. Nesil kapsayıcısı mycontainer'ı /test'e bağladığınızı varsayın. Verilere yerel dosya sistemi API'siyle eriştiğiniz zaman yol biçimi şöyledir:

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

API'yi kullanarak notebookutils fs verilere erişmek istediğinizde, doğru yolu elde etmek için kullanın getMountPath() :

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

• Dizinleri listeleyin.

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

• Dosya içeriğini okuyun.

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

• Bir dizin oluşturun.

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

Bağlama noktası altındaki dosyalara yerel yol üzerinden erişme

Standart dosya sistemini kullanarak bağlama noktasındaki dosyaları okuyabilir ve yazabilirsiniz. Aşağıdaki Python örneği bu düzeni gösterir:

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

Mevcut bağlama noktalarını denetleme

notebookutils.fs.mounts() Tüm mevcut bağlama noktası bilgilerini denetlemek için API'yi kullanın:

notebookutils.fs.mounts()

Tavsiye

Çakışmaları önlemek için yeni bağlama noktaları oluşturmadan önce her zaman mounts() kullanarak mevcut bağlantıları denetleyin.

Montajı gerçekleştirmeden önce bir montajın mevcut olup olmadığını kontrol edin.

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

Bağlama noktasını çıkarma

Bağlama noktanızı (/test bu örnekte) sökmek için aşağıdaki kodu kullanın:

notebookutils.fs.unmount("/test")

Önemli

Çıkarma mekanizması otomatik olarak uygulanmaz. Uygulama çalıştırması tamamlandığında bağlama noktasını sökmek ve disk alanını serbest bırakmak için kodunuzda bir çıkarma API'sini açıkça çağırmanız gerekir. Aksi takdirde, uygulama çalıştırması tamamlandıktan sonra bağlama noktası düğümde hala var olur.

Bağlama işlemi-çıkarma iş akışı

Güvenilir kaynak yönetimi için, bir hata oluştuğunda bile temizlemenin gerçekleşmesini sağlamak için bağlama işlemlerini bir try/finally blokta sarmalayın:

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

Bilinen sınırlamalar

• Bağlama noktaları, iş düzeyi yapılandırmalarıdır. Bir bağlama noktasının mounts zaten var olup olmadığını veya kullanılabilir olup olmadığını denetlemek için API'yi kullanın.
• Çıkarma otomatik olarak gerçekleşmez. Uygulama çalıştırması tamamlandığında, disk alanını serbest bırakmak için kodunuzda bir çıkarma API'sini çağırın. Aksi takdirde, uygulama çalıştırması tamamlandıktan sonra bağlama noktası düğümde kalır.
• ADLS 1. Nesil depolama hesabı bağlama desteklenmez.

İlgili içerik

• Fabric için NotebookUtils
• NotebookUtils dosya sistemi yardımcı programları