Fabric için NotebookUtils (eski MSSparkUtils)

2025-05-27

Not Defteri Yardımcı Programları (NotebookUtils), Doku Not Defteri'nde yaygın görevleri kolayca gerçekleştirmenize yardımcı olan yerleşik bir pakettir. NotebookUtils'i dosya sistemleriyle çalışmak, ortam değişkenlerini almak, not defterlerini birbirine zincirleme ve gizli dizilerle çalışmak için kullanabilirsiniz. NotebookUtils paketi PySpark (Python) Scala, SparkR not defterleri ve Doku işlem hatlarında kullanılabilir.

Uyarı

MsSparkUtils resmi olarak NotebookUtilsolarak yeniden adlandırıldı. Mevcut kod geriye dönük uyumlu kalır ve herhangi bir uyumsuzluğa neden olmaz. Sürekli destek ve yeni özelliklere erişim sağlamak için notebookutils'e yükseltmenizi kesinlikle öneririz. mssparkutils ad alanı gelecekte kullanımdan kaldırılacaktır.
NotebookUtils, Spark 3.4 (Runtime v1.2) ve üzeri ile çalışacak şekilde tasarlanmıştır. Tüm yeni özellikler ve güncelleştirmeler, ileride notebookutils ad alanıyla özel olarak desteklenir.

Dosya sistemi yardımcı programları

notebookutils.fs, Azure Data Lake Storage (ADLS) 2. Nesil ve Azure Blob Depolama dahil olmak üzere çeşitli dosya sistemleriyle çalışmaya yönelik yardımcı programlar sağlar. Azure Data Lake Storage 2. Nesil ve Azure Blob Depolama erişimini uygun şekilde yapılandırdığınızdan emin olun.

Kullanılabilir yöntemlere genel bakış için aşağıdaki komutları çalıştırın:

notebookutils.fs.help()

Çıktı

notebookutils.fs provides utilities for working with various FileSystems.

Below is overview about the available methods:

cp(from: String, to: String, recurse: Boolean = false): Boolean -> Copies a file or directory, possibly across FileSystems
fastcp(from: String, to: String, recurse: Boolean = true): Boolean -> [Preview] Copies a file or directory via azcopy, possibly across FileSystems
mv(from: String, to: String, createPath: Boolean = false, overwrite: Boolean = false): Boolean -> Moves a file or directory, possibly across FileSystems
ls(dir: String): Array -> Lists the contents of a directory
mkdirs(dir: String): Boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
put(file: String, contents: String, overwrite: Boolean = false): Boolean -> Writes the given String out to a file, encoded in UTF-8
head(file: String, maxBytes: int = 1024 * 100): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
append(file: String, content: String, createFileIfNotExists: Boolean): Boolean -> Append the content to a file
rm(dir: String, recurse: Boolean = false): Boolean -> Removes a file or directory
exists(file: String): Boolean -> Check if a file or directory exists
mount(source: String, mountPoint: String, extraConfigs: Map[String, Any]): Boolean -> Mounts the given remote storage directory at the given mount point
unmount(mountPoint: String): Boolean -> Deletes a mount point
mounts(): Array[MountPointInfo] -> Show information about what is mounted
getMountPath(mountPoint: String, scope: String = ""): String -> Gets the local path of the mount point

Use notebookutils.fs.help("methodName") for more info about a method.

NotebookUtils, dosya sistemiyle Spark API'leriyle aynı şekilde çalışır. Notebookutils.fs.mkdirs() ve Fabric lakehouse kullanımını ele alın, örneğin:

Kullanım	HDFS kök dizininden göreli yol	ABFS dosya sistemi için mutlak yol	Sürücü düğümünde yer alan yerel dosya sistemi için mutlak yol
Varsayılan olmayan göl evi	Desteklenmez	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Varsayılan göl evi	'Dosyalar' veya 'Tablolar' altındaki dizin: notebookutils.fs.mkdirs("Dosyalar/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")

Uyarı

Varsayılan Lakehouse için, dosya yolları Not Defterinize 120 saniyelik varsayılan dosya önbelleği zaman aşımı ile bağlanır. Bu, dosyaların Lakehouse'dan kaldırılsalar bile Not Defteri'nin yerel geçici klasöründe 120 saniye boyunca önbelleğe alındığı anlamına gelir. Zaman aşımı kuralını değiştirmek istiyorsanız, varsayılan Lakehouse dosya yollarını çıkartarak, farklı bir fileCacheTimeout değeriyle yeniden monte edebilirsiniz.
Varsayılan olmayan Lakehouse yapılandırmaları için Lakehouse yollarının montajı sırasında uygun fileCacheTimeout parametresini ayarlayabilirsiniz. Zaman aşımının 0 olarak ayarlanması, en son dosyanın Lakehouse sunucusundan getirildiğinden emin olur.

Dosyaları listeleme

Bir dizinin içeriğini listelemek için notebookutils.fs.ls('Dizin yolunuz') kullanın. Örneğin:

notebookutils.fs.ls("Files/tmp") # The relatvie path may work with different base path, details in below 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # The absolute path, like: ABFS file system
notebookutils.fs.ls("file:/tmp")  # The full path of the local file system of driver node

notebookutils.fs.ls() API'si, not defterinin türüne bağlı olarak göreli yol kullanırken farklı davranır.

Spark defteri: Göreceli yol, varsayılan Lakehouse'un ABFSS yoluna göre ayarlanmıştır. Örneğin, notebookutils.fs.ls("Files") varsayılan Lakehouse'da Files dizinine işaret eder.

Örneğin:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
Python not defteri: Göreli yol, yerel dosya sisteminin çalışma dizinine göredir ve varsayılan olarak /home/trusted-service-user/work şeklindedir. Bu nedenle, varsayılan Lakehouse'daki notebookutils.fs.ls("/lakehouse/default/Files") dizinine erişmek için göreli yol Files yerine tam yolu kullanmanız gerekir.

Örneğin:
```
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
```

Dosya özelliklerini görüntüleme

Bu yöntem, dosya adı, dosya yolu, dosya boyutu ve bunun bir dizin ve dosya olup olmadığı gibi dosya özelliklerini döndürür.

files = notebookutils.fs.ls('Your directory path')
for file in files:
    print(file.name, file.isDir, file.isFile, file.path, file.size)

Yeni dizin oluşturma

Bu yöntem, mevcut değilse verilen dizini oluşturur ve gerekli üst dizinleri oluşturur.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # based on ABFS file system 
notebookutils.fs.ls("file:/<new_dir>")  # based on local file system of driver node

Dosyayı kopyalama

Bu yöntem bir dosya veya dizin kopyalar ve dosya sistemleri arasında kopyalama etkinliğini destekler.

notebookutils.fs.cp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Uyarı

OneLake kısayolunun sınırlamaları nedeniyle, S3/GCS türü kısayolundan veri kopyalamak için kullanmanız gerektiğinde, abfss yolu yerine bağlı yol kullanmanız önerilir.

Verimli kopyalama dosyası

Bu yöntem, özellikle büyük veri hacimleriyle ilgilenirken dosyaları kopyalama veya taşıma konusunda daha verimli bir yaklaşım sunar. Fabric üzerinde gelişmiş performans için, geleneksel fastcp yöntemi yerine cp kullanılması tavsiye edilir.

Uyarı

notebookutils.fs.fastcp() , OneLake'teki dosyaların bölgeler arasında kopyalanmasını desteklemez. Bu durumda, bunun yerine kullanabilirsiniz notebookutils.fs.cp() .
OneLake kısayolunun sınırlamaları nedeniyle, S3/GCS türü kısayolundan veri kopyalamak için kullanmanız gerektiğinde, abfss yolu yerine bağlı yol kullanmanız önerilir.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Dosya içeriğini önizleme

Bu yöntem, verilen dosyanın ilk 'maxBytes' baytlarına kadar UTF-8'de kodlanmış bir Dize olarak döndürür.

notebookutils.fs.head('file path', maxBytes to read)

Dosyayı taşıma

Bu yöntem bir dosyayı veya dizini taşır ve dosya sistemleri arasında taşımayı destekler.

notebookutils.fs.mv('source file or directory', 'destination directory', True) # Set the last parameter as True to firstly create the parent directory if it does not exist
notebookutils.fs.mv('source file or directory', 'destination directory', True, True) # Set the third parameter to True to firstly create the parent directory if it does not exist. Set the last parameter to True to overwrite the updates.

Dosya yazma

Bu yöntem, verilen dizeyi UTF-8 ile kodlanmış bir dosyaya yazar.

notebookutils.fs.put("file path", "content to write", True) # Set the last parameter as True to overwrite the file if it existed already

Dosyaya içerik ekleme

Bu yöntem, verilen dizeyi UTF-8 ile kodlanmış bir dosyaya ekler.

notebookutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it does not exist

Uyarı

notebookutils.fs.append() ve notebookutils.fs.put() atomiklik garantilerinin olmaması nedeniyle aynı dosyaya eşzamanlı yazmayı desteklemez.
Aynı dosyaya yazmak için notebookutils.fs.append API'sini bir for döngüsünde kullanırken, yinelenen yazma işlemleri arasına yaklaşık 0,5 sn ~ 1 sn civarında bir sleep deyimi eklemenizi öneririz. Bu önerinin nedeni, notebookutils.fs.append API'sinin iç flush işleminin zaman uyumsuz olmasıdır, bu nedenle kısa bir gecikme veri bütünlüğünü sağlamaya yardımcı olur.

Dosya veya dizin silme

Bu yöntem bir dosyayı veya dizini kaldırır.

notebookutils.fs.rm('file path', True) # Set the last parameter as True to remove all files and directories recursively

Dizini monte etme/çıkartma

Dosya bağlama ve çıkarma bölümünde ayrıntılı kullanım hakkında daha fazla bilgi bulabilirsiniz.

Dizüstü bilgisayar yardımcı programları

Not defterini çalıştırmak veya not defterinden bir değerle çıkmak için Not Defteri Yardımcı Programları'nı kullanın. Kullanılabilir yöntemlere genel bir bakış elde etmek için aşağıdaki komutu çalıştırın:

notebookutils.notebook.help()

Çıktı:


The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value.
run(path: String, timeoutSeconds: int, arguments: Map, workspace: String): String -> This method runs a notebook and returns its exit value.
runMultiple(DAG: Any): Map[String, MsNotebookRunResult] -> [Preview] Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> [Preview] This method check if the DAG is correctly defined.

[Preview] Below methods are only support Fabric Notebook.
create(name: String, description: String = "", content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = ""): Artifact -> Create a new Notebook.
get(name: String, workspaceId: String = ""): Artifact -> Get a Notebook by name or id.
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact -> Update a Artifact by name.
delete(name: String, workspaceId: String = ""): Boolean -> Delete a Notebook by name.
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact] -> List all Notebooks in the workspace.
updateDefinition(name: String, content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = "") -> Update the definition of a Notebook.

Use notebookutils.notebook.help("methodName") for more info about a method.

Uyarı

Not defteri yardımcı programları Apache Spark iş tanımları (SJD) için geçerli değildir.

Bir deftere başvur.

Bu yöntem bir not defterine başvurur ve çıkış değerini döndürür. İç içe işlev çağrılarını, etkileşimli olarak bir not defterinde veya bir işlem hattında çalıştırabilirsiniz. Atıfta bulunulan not defteri, bu işlevi çağıran not defterinin Spark havuzunda çalışır.

notebookutils.notebook.run("notebook name", <timeoutSeconds>, <parameterMap>, <workspaceId>)

Örneğin:

notebookutils.notebook.run("Sample1", 90, {"input": 20 })

Fabric not defteri, birden çok çalışma alanında not defterlerine çalışma alanı kimliğini belirterek başvurmayı da destekler.

notebookutils.notebook.run("Sample1", 90, {"input": 20 }, "fe0a6e2a-a909-4aa3-a698-0a651de790aa")

Referans çalıştırmasının anlık görüntü bağlantısını hücre çıktısında açabilirsiniz. Anlık görüntü, kod çalıştırma sonuçlarını yakalar ve bir referans çalıştırmasının hatalarını kolayca ayıklamanıza olanak tanır.

Uyarı

Çalışma alanları arasında referans alınan not defteri, 1.2 ve daha üstü çalışma zamanı sürümleriyle desteklenir.
Not Defteri Kaynağı içerisinde bulunan dosyaları kullanıyorsanız, etkileşimli çalıştırma ile aynı klasöre işaret ettiklerinden emin olmak için başvurulan not defterinde notebookutils.nbResPath kullanın.

Birden çok not defterini paralel olarak çalıştırma işlemi

Önemli

Bu özellik önizleme aşamasındadır.

yöntemi notebookutils.notebook.runMultiple() , birden çok not defterini paralel veya önceden tanımlanmış bir topolojik yapıyla çalıştırmanıza olanak tanır. API, Spark oturumu içinde çok iş parçacıklı bir uygulama mekanizması kullanıyor, bu da başvuru not defterinin çalıştırılmasının işlem kaynaklarını paylaştığı anlamına gelir.

ile notebookutils.notebook.runMultiple()şunları yapabilirsiniz:

Her birinin bitmesini beklemeden birden çok not defterlerini aynı anda çalıştırın.
Basit bir JSON biçimi kullanarak not defterleriniz için bağımlılıkları ve yürütme sırasını belirtin.
Spark işlem kaynaklarının kullanımını iyileştirin ve Doku projelerinizin maliyetini azaltın.
Çıktıdaki her not defteri çalıştırma kaydının anlık görüntülerini görüntüleyin ve not defteri görevlerinizi rahatça izleyin/ayıklayın.
Her yönetici etkinliğinin çıkış değerini alın ve bunları aşağı akış görevlerinde kullanın.

Örneği ve ayrıntılı kullanımı bulmak için notebookutils.notebook.help("runMultiple") komutunu çalıştırmayı da deneyebilirsiniz.

Aşağıda, bu yöntemi kullanarak not defterlerinin listesini paralel olarak çalıştırmanın basit bir örneği verilmiştir:


notebookutils.notebook.runMultiple(["NotebookSimple", "NotebookSimple2"])

Kök not defterinin yürütme sonucu aşağıdaki gibidir:

Aşağıda, notebookutils.notebook.runMultiple()kullanarak topolojik yapıya sahip not defterlerini çalıştırma örneği verilmiştir. Bir kod deneyimi aracılığıyla not defterlerini kolayca düzenlemek için bu yöntemi kullanın.

# run multiple notebooks with parameters
DAG = {
    "activities": [
        {
            "name": "NotebookSimple", # activity name, must be unique
            "path": "NotebookSimple", # notebook path
            "timeoutPerCellInSeconds": 90, # max timeout for each cell, default to 90 seconds
            "args": {"p1": "changed value", "p2": 100}, # notebook parameters
        },
        {
            "name": "NotebookSimple2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 2", "p2": 200}
        },
        {
            "name": "NotebookSimple2.2",
            "path": "NotebookSimple2",
            "timeoutPerCellInSeconds": 120,
            "args": {"p1": "changed value 3", "p2": 300},
            "retry": 1,
            "retryIntervalInSeconds": 10,
            "dependencies": ["NotebookSimple"] # list of activity names that this activity depends on
        }
    ],
    "timeoutInSeconds": 43200, # max timeout for the entire DAG, default to 12 hours
    "concurrency": 50 # max number of notebooks to run concurrently, default to 50
}
notebookutils.notebook.runMultiple(DAG, {"displayDAGViaGraphviz": False})

Kök not defterinin yürütme sonucu aşağıdaki gibidir:

Ayrıca DAG'nin doğru tanımlandığını denetlemek için bir yöntem de sağlıyoruz.

notebookutils.notebook.validateDAG(DAG)

Uyarı

Birden çok not defteri çalıştırmasının paralellik derecesi, Spark oturumunun toplam kullanılabilir işlem kaynağıyla sınırlıdır.
Not defteri etkinlikleri veya eşzamanlı not defterleri için üst sınır 50'dir. Bu sınırın aşılması, yüksek işlem kaynağı kullanımı nedeniyle kararlılık ve performans sorunlarına yol açabilir. Sorun oluşursa, DAG parametresindeki eşzamanlılık alanını ayarlayarak not defterlerini birden çok runMultiple çağrıya ayırmayı veya eşzamanlılığı azaltmayı göz önünde bulundurun.
Tüm DAG için varsayılan zaman aşımı 12 saattir ve çocuk not defterindeki her hücre için varsayılan zaman aşımı 90 saniyedir. DAG parametresindeki timeoutInSeconds ve zaman aşımıPerCellInSeconds alanlarını ayarlayarak zaman aşımını değiştirebilirsiniz.

Not defterinden çıkış yap

Bu yöntem, belirtilen bir değerle bir defteri kapatır. İç içe işlev çağrılarını, etkileşimli olarak bir not defterinde veya bir işlem hattında çalıştırabilirsiniz.

Bir not defterinden exit() işlevini etkileşimli olarak çağırdığınızda, Fabric notebook bir özel durum fırlatır, sonraki hücreleri çalıştırmayı atlar ve Spark oturumunu canlı tutar.
Exit() işlevini çağıran bir işlem hattında not defterini yönetirken, not defteri işlemi bir çıkış değeriyle geri döner. Bu işlem hattı çalışmasını tamamlar ve Spark oturumunu durdurur.
Başvuruda bulunan bir not defterinde exit() işlevini çağırdığınızda, Fabric Spark başvuruda bulunan not defterinin daha fazla yürütülmesini durdurur ve ana not defterinde run() işlevini çağıran sonraki hücreleri çalıştırmaya devam eder. Örneğin: Notebook1 üç hücreye sahiptir ve ikinci hücrede exit () işlevini çağırır. Notebook2'nin beş hücresi vardır ve üçüncü hücrede run(notebook1) çağrıları vardır. Notebook2'yi çalıştırdığınızda, exit() işlevine basıldığında Notebook1 ikinci hücrede durur. Not Defteri2, dördüncü hücresini ve beşinci hücresini çalıştırmaya devam eder.

notebookutils.notebook.exit("value string")

Uyarı

exit() işlevi, geçerli hücre çıkışının üzerine yazar. Diğer kod deyimlerinin çıkışını kaybetmemek için ayrı bir hücrede notebookutils.notebook.exit() çağırın.

Örneğin:

Aşağıdaki iki hücreye sahip Örnek1 not defteri:

Hücre 1, varsayılan değeri 10 olarak ayarlanmış bir giriş parametresi tanımlar.
2. hücre, çıkış değeri olarak input ile not defterinden çıkar.

Sample1'i varsayılan değerlerle başka bir not defterinde çalıştırabilirsiniz:

exitVal = notebookutils.notebook.run("Sample1")
print (exitVal)

Çıktı:

Notebook is executed successfully with exit value 10

Sample1'i başka bir not defterinde çalıştırabilir ve giriş değerini 20 olarak ayarlayabilirsiniz:

exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20 })
print (exitVal)

Çıktı:

Notebook is executed successfully with exit value 20

Not defteri objelerini yönet

notebookutils.notebook , Not Defteri öğelerini program aracılığıyla yönetmek için özel yardımcı programlar sağlar. Bu API'ler Not Defteri öğelerini kolayca oluşturmanıza, almanıza, güncelleştirmenize ve silmenize yardımcı olabilir.

Bu yöntemleri etkili bir şekilde kullanmak için aşağıdaki kullanım örneklerini göz önünde bulundurun:

Not defteri oluşturma

with open("/path/to/notebook.ipynb", "r") as f:
    content = f.read()

artifact = notebookutils.notebook.create("artifact_name", "description", "content", "default_lakehouse_name", "default_lakehouse_workspace_id", "optional_workspace_id")

Bir Defterin İçeriğini Almak

artifact = notebookutils.notebook.get("artifact_name", "optional_workspace_id")

Dizüstü Bilgisayarı Güncelleme

updated_artifact = notebookutils.notebook.update("old_name", "new_name", "optional_description", "optional_workspace_id")

updated_artifact_definition = notebookutils.notebook.updateDefinition("artifact_name",  "content", "default_lakehouse_name", "default_Lakehouse_Workspace_name", "optional_workspace_id")

Bir Defter Silme

is_deleted = notebookutils.notebook.delete("artifact_name", "optional_workspace_id")

Çalışma alanında Not Defterlerini Listeleme

artifacts_list = notebookutils.notebook.list("optional_workspace_id")

Kullanıcı Veri İşlevi (UDF) yardımcı programları

notebookutils.udf , Not Defteri kodunu Kullanıcı Veri İşlevleri (UDF) ile tümleştirmek için tasarlanmış yardımcı programlar sağlar. Bu yardımcı programlar, işlevlere aynı çalışma alanı içindeki veya farklı çalışma alanlarındaki bir UDF öğesinden erişmenizi sağlar. Daha sonra gerektiğinde UDF öğesi içindeki işlevleri çağırabilirsiniz.

Kullanılabilir yöntemlere genel bir bakış aşağıdadır:

# Get functions
myFunctions = notebookutils.udf.getFunctions('UDFItemName') # Get functions from UDF within the same workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId') # Get functions from UDF across different workspace

# Additional helper method to return all functions, their respective parameters, and types.
display(myFunctions.functionDetails)
display(myFunctions.itemDetails)

# Invoke the function
myFunctions.functionName('value1', 'value2')
myFunctions.functionName(parameter1='value1', parameter2='value2'...) # Another way to invoke the function

UDF'den fonksiyonları al

myFunctions = notebookutils.udf.getFunctions('UDFItemName')
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

var myFunctions = notebookutils.udf.getFunctions("UDFItemName")
var myFunctions = notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

myFunctions <- notebookutils.udf.getFunctions("UDFItemName")
myFunctions <- notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

İşlevi çağırma

myFunctions.functionName('value1', 'value2'...)

val res = myFunctions.functionName('value1', 'value2'...)

myFunctions$functionName('value1', 'value2'...)

UDF öğesinin ayrıntılarını görüntüleme

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

UDF için işlev ayrıntılarını görüntüleme

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Kimlik yardımcı programları

Azure Key Vault'ta erişim belirteçleri almak ve gizli dizileri yönetmek için Kimlik Bilgileri Yardımcı Programlarını kullanabilirsiniz.

Kullanılabilir yöntemlere genel bir bakış elde etmek için aşağıdaki komutu çalıştırın:

notebookutils.credentials.help()

Çıktı:

Help on module notebookutils.credentials in notebookutils:

NAME
    notebookutils.credentials - Utility for credentials operations in Fabric

FUNCTIONS
    getSecret(akvName, secret) -> str
        Gets a secret from the given Azure Key Vault.
        :param akvName: The name of the Azure Key Vault.
        :param secret: The name of the secret.
        :return: The secret value.
    
    getToken(audience) -> str
        Gets a token for the given audience.
        :param audience: The audience for the token.
        :return: The token.
    
    help(method_name=None)
        Provides help for the notebookutils.credentials module or the specified method.
        
        Examples:
        notebookutils.credentials.help()
        notebookutils.credentials.help("getToken")
        :param method_name: The name of the method to get help with.

DATA
    creds = <notebookutils.notebookutils.handlers.CredsHandler.CredsHandler...

FILE
    /home/trusted-service-user/cluster-env/trident_env/lib/python3.10/site-packages/notebookutils/credentials.py

Jeton almak

getToken, belirli bir hedef kitle ve ad için bir Microsoft Entra belirteci döndürür (isteğe bağlı). Aşağıdaki listede şu anda kullanılabilir olan hedef kitle anahtarları gösterilmektedir:

Depolama Hedef Kitlesi Kaynağı: "depolama"
Power BI Kaynağı: "pbi"
Azure Key Vault Kaynağı: "keyvault"
Synapse RTA KQL Veritabanı Kaynağı: "kusto"

Belirteci almak için aşağıdaki komutu çalıştırın:

notebookutils.credentials.getToken('audience Key')

Kullanıcı kimlik bilgilerini kullanarak gizliyi al

getSecret, kullanıcı kimlik bilgilerini kullanarak belirli bir Azure Key Vault uç noktası ve gizli bilgi adı için bir Azure Key Vault gizli bilgisi döndürür.

notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')

Disk bağlama ve çıkarma

Microsoft Spark Yardımcı Programları paketinde Fabric, aşağıdaki bağlantı senaryolarını destekler. Tüm çalışan düğümlere (sürücü düğümü ve çalışan düğümler) uzak depolama (ADLS 2. Nesil) eklemek için bağlama, çıkarma, 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.

ADLS 2. Nesil hesabını bağlama

Aşağıdaki örnek, Azure Data Lake Storage 2. Nesil'in nasıl bağlanacağını göstermektedir. Blob Depolama'yı monte etmek benzer şekilde çalışır.

Bu örnek, storegen2adında bir Data Lake Storage Gen2 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 öncelikle notebookutils'in kapsayıcıya erişim izniniz olup olmadığını denetlemesi gerekir. Şu anda Fabric, tetikleme bağlama işlemi için iki kimlik doğrulama yöntemini destekler: accountKey ve sastoken.

Paylaşılan erişim imzası belirteci veya hesap anahtarı aracılığıyla ekleme

NotebookUtils, hedefi bağlamak için bir hesap anahtarının veya Paylaşılan erişim imzası (SAS) belirtecinin parametre olarak açıkça geçirilmesini destekler.

Güvenlik nedeniyle, hesap anahtarlarını veya SAS belirteçlerini Azure Key Vault'ta depolamanızı öneririz (aşağıdaki ekran görüntüsünde gösterildiği gibi). Daha sonra notebookutils.credentials.getSecret API'sini 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 full audience here like 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 full audience here like 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:

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. parametresi varsayılan zaman aşımı süresini değiştirecek şekilde ayarlanabilir. 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ısaltmanızı, hatta 0 olarak değiştirmenizi ve her zaman sunucudan en son dosyaları almanızı öneririz.
zaman aşımı: Bağlama işlemi zaman aşımı varsayılan olarak 120 saniyedir. parametresi varsayılan zaman aşımı süresini değiştirecek şekilde ayarlanabilir. Çok fazla yürütücü olduğunda veya bağlama süresi dolduğunda değeri artırmanızı öneririz.

Aşağıdaki gibi parametreleri kullanabilirsiniz:

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

Uyarı

Güvenlik amacıyla kimlik bilgilerinin doğrudan koda eklendiğinden kaçınılması tavsiye edilir. Kimlik bilgilerinizi daha fazla korumak için, not defteri çıkışlarında görüntülenen tüm gizli bilgiler gizlenir. Daha fazla bilgi için bkz Gizli düzenleme.

Göl evi nasıl monte edilir?

Bir lakehouse'u /<mount_name> konumuna 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

Bağlama işleminin temel amacı, müşterilerin yerel bir dosya sistemi API'siyle uzak depolama hesabında depolanan verilere erişmesine izin vermektir. Bağlı bir yolu parametre olarak kullanarak notebookutils fs API'si ile verilere de erişebilirsiniz. Bu yol formatı biraz farklı.

tr-TR: Mount API'sini kullanarak Data Lake Storage Gen2 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}

Notebookutils fs API'sini kullanarak verilere erişmek istediğinizde, doğru yolu elde etmek için getMountPath() kullanmanızı öneririz:

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

Liste dizinleri:

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

Dosya içeriğini okuma:

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

Dizin oluşturma:

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ı kolayca okuyabilir ve yazabilirsiniz. Python örneği aşağıda verilmişti:

#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

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

notebookutils.fs.mounts()

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

Bilinen sınırlamalar

Geçerli bağlama noktası bir iş düzeyi yapılandırmasıdır; bir bağlama noktası var olup olmadığını veya mevcut değil mi kontrol etmek için bağlamalar API'sini kullanmanızı öneririz.
Sökme 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 bulunmaya devam eder.
Birinci Nesil ADLS depolama hesabı bağlama desteklenmez.

Lakehouse yardımcı programları

notebookutils.lakehouse, Lakehouse öğelerini yönetmek için uyarlanmış yardımcı programlar sağlar. Bu yardımcı programlar, Lakehouse yapıtlarını zahmetsizce oluşturmanızı, edinmenizi, güncelleştirmenizi ve silmenizi sağlar.

Yöntemlere genel bakış

notebookutils.lakehousetarafından sağlanan kullanılabilir yöntemlere genel bir bakış aşağıda verilmiştir:

# Create a new Lakehouse artifact
create(name: String, description: String = "", definition: ItemDefinition = null, workspaceId: String = ""): Artifact

# Retrieve a Lakehouse artifact
get(name: String, workspaceId: String = ""): Artifact

# Get a Lakehouse artifact with properties
getWithProperties(name: String, workspaceId: String = ""): Artifact

# Update an existing Lakehouse artifact
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact

# Delete a Lakehouse artifact
delete(name: String, workspaceId: String = ""): Boolean 

# List all Lakehouse artifacts
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact]

# List all tables in a Lakehouse artifact
listTables(lakehouse: String, workspaceId: String = "", maxResults: Int = 1000): Array[Table] 

# Starts a load table operation in a Lakehouse artifact
loadTable(loadOption: collection.Map[String, Any], table: String, lakehouse: String, workspaceId: String = ""): Array[Table]

Kullanım örnekleri

Bu yöntemleri etkili bir şekilde kullanmak için aşağıdaki kullanım örneklerini göz önünde bulundurun:

Lakehouse Oluşturma

artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", "optional_workspace_id")

Göl Evi Edinmek

artifact = notebookutils.lakehouse.get("artifact_name", "optional_workspace_id")

artifact = notebookutils.lakehouse.getWithProperties("artifact_name", "optional_workspace_id")

Bir Lakehouse'un güncelleştirilmesi

updated_artifact = notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")

Bir Lakehouse'un silinmesi

is_deleted = notebookutils.lakehouse.delete("artifact_name", "optional_workspace_id")

Çalışma alanında Lakehouse'ları listeleme

artifacts_list = notebookutils.lakehouse.list("optional_workspace_id")

Lakehouse'daki tüm tabloları listeleme

artifacts_tables_list = notebookutils.lakehouse.listTables("artifact_name", "optional_workspace_id")

Lakehouse'ta yük tablosu işlemini başlatma

notebookutils.lakehouse.loadTable(
    {
        "relativePath": "Files/myFile.csv",
        "pathType": "File",
        "mode": "Overwrite",
        "recursive": False,
        "formatOptions": {
            "format": "Csv",
            "header": True,
            "delimiter": ","
        }
    }, "table_name", "artifact_name", "optional_workspace_id")

Ek bilgi

Her yöntem ve parametreleri hakkında daha ayrıntılı bilgi için notebookutils.lakehouse.help("methodName") işlevini kullanın.

Çalışma zamanı yardımcı programları

Oturum bağlam bilgilerini gösterme

notebookutils.runtime.context ile geçerli canlı oturumun bağlam bilgilerini, not defteri ismi, varsayılan Lakehouse, çalışma alanı bilgisi, işlem hattı çalıştırması olup olmadığı gibi bilgileri alabilirsiniz.

notebookutils.runtime.context

Aşağıdaki tabloda özellikler özetlenmiştir.

Parametre	Açıklama
`currentNotebookName`	Geçerli not defterinin adı
`currentNotebookId`	Geçerli not defterinin benzersiz kimliği
`currentWorkspaceName`	Geçerli çalışma alanının adı
`currentWorkspaceId`	Geçerli çalışma alanının ID'si
`defaultLakehouseName`	Tanımlanmışsa varsayılan lakehouse'un görünen adı
`defaultLakehouseId`	Varsayılan lakehouse'un kimliği, tanımlandıysa
`defaultLakehouseWorkspaceName`	Varsayılan lakehouse'un, eğer tanımlanmışsa, çalışma alanı adı
`defaultLakehouseWorkspaceId`	Tanımlanmışsa, varsayılan lakehouse'un çalışma alanı kimliği
`currentRunId`	Referans çalıştırmasında geçerli çalıştırma kimliği
`parentRunId`	İç içe çalıştırmalar içeren bir başvuru çalıştırmasında, bu, ana çalıştırma kimliğidir.
`rootRunId`	İç içe çalıştırmaları olan bir başvuru çalıştırmasında bu, kök çalıştırma kimliğidir
`isForPipeline`	Çalıştırmanın işlem hattı için olup olmadığı
`isReferenceRun`	Geçerli çalıştırmanın bir referans çalıştırması olup olmadığı
`referenceTreePath`	İzleme L2 sayfasındaki anlık görüntü hiyerarşisi için yalnızca iç içe referans yürütmelerinin ağaç yapısı kullanılır.
`rootNotebookId`	(Yalnızca başvuru çalıştırmasında) Başvuru çalıştırmasında kök not defterinin kimliği.
`rootNotebookName`	(Yalnızca başvuru çalıştırmasında) Kök not defterinin adı.
`rootWorkspaceId`	(Yalnızca başvuru çalıştırmasında) Başvuru çalıştırmasında kök not defterinin çalışma alanı kimliği.
`rootWorkspaceName`	(Yalnızca başvuru çalıştırmasında) Başvuru çalıştırmasında kök not defterinin çalışma alanı adı.
`activityId`	Mevcut aktiviteye ilişkin Livy iş ID'si
`hcRepId`	Yüksek Eşzamanlılık Modunda REPL Kimliği
`clusterId`	Synapse Spark kümesinin kimliği
`poolName`	Kullanılan Spark havuzunun adı
`environmentId`	İşin çalıştığı ortam kimliği
`environmentWorkspaceId`	Ortamın çalışma alanı kimliği
`userId`	Geçerli kullanıcının kullanıcı kimliği
`userName`	Geçerli kullanıcının kullanıcı adı

Oturum yönetimi

Etkileşimli oturumu durdurma

Durdur düğmesine el ile tıklamak yerine, bazen kodda bir API çağırarak etkileşimli oturumu durdurmak daha uygundur. Bu gibi durumlarda kod aracılığıyla etkileşimli oturumun durdurulmasını desteklemek için bir API notebookutils.session.stop() sağlıyoruz. Scala ve PySpark için kullanılabilir.

notebookutils.session.stop()

notebookutils.session.stop() API, geçerli etkileşimli oturumu asenkron olarak arka planda durdurur. Ayrıca Spark oturumunu durdurur ve oturum tarafından kullanılan kaynakları serbest bırakır, böylece aynı havuzdaki diğer oturumlar için kullanılabilir.

Python yorumlayıcısını yeniden başlatma

notebookutils.session yardımcı programı, Python yorumlayıcısını yeniden başlatmak için bir yol sağlar.

notebookutils.session.restartPython()

Uyarı

Not defteri başvuru olayında, restartPython() yalnızca bağlantı verilen geçerli not defterinin Python yorumlayıcısını yeniden başlatır.
Nadir durumlarda, Spark yansıma mekanizması nedeniyle komut başarısız olabilir ve yeniden deneme eklemek sorunu hafifletebilir.

Bilinen sorun

1.2'nin üzerindeki çalışma zamanı sürümünü kullanıp notebookutils.help() çalıştırırken, listelenen fabricClient ve PBIClient API'leri şu anda desteklenmemektedir, ancak gelecekte kullanılabilir olacaktır. Ayrıca, Kimlik Bilgileri API'si şimdilik Scala not defterlerinde desteklenmemektedir.
Python not defteri, oturum yönetimi için notebookutils.session yardımcı programı kullanılırken durdurma, restartPython API'lerini desteklemez.

Aracılığıyla paylaş

Fabric için NotebookUtils (eski MSSparkUtils)

Dosya sistemi yardımcı programları

Dosyaları listeleme

Dosya özelliklerini görüntüleme

Yeni dizin oluşturma

Dosyayı kopyalama

Verimli kopyalama dosyası

Dosya içeriğini önizleme

Dosyayı taşıma

Dosya yazma

Dosyaya içerik ekleme

Dosya veya dizin silme

Dizini monte etme/çıkartma

Dizüstü bilgisayar yardımcı programları

Bir deftere başvur.

Birden çok not defterini paralel olarak çalıştırma işlemi

Not defterinden çıkış yap

Not defteri objelerini yönet

Not defteri oluşturma

Bir Defterin İçeriğini Almak

Dizüstü Bilgisayarı Güncelleme

Bir Defter Silme

Çalışma alanında Not Defterlerini Listeleme

Kullanıcı Veri İşlevi (UDF) yardımcı programları

UDF'den fonksiyonları al

İşlevi çağırma

UDF öğesinin ayrıntılarını görüntüleme

UDF için işlev ayrıntılarını görüntüleme

Kimlik yardımcı programları

Jeton almak

Kullanıcı kimlik bilgilerini kullanarak gizliyi al

Disk bağlama ve çıkarma

ADLS 2. Nesil hesabını bağlama

Paylaşılan erişim imzası belirteci veya hesap anahtarı aracılığıyla ekleme

Göl evi nasıl monte edilir?

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

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

Mevcut bağlama noktalarını denetleme

Bağlama noktasını çıkarma

Bilinen sınırlamalar

Lakehouse yardımcı programları

Yöntemlere genel bakış

Kullanım örnekleri

Lakehouse Oluşturma

Göl Evi Edinmek

Bir Lakehouse'un güncelleştirilmesi

Bir Lakehouse'un silinmesi

Çalışma alanında Lakehouse'ları listeleme

Lakehouse'daki tüm tabloları listeleme

Lakehouse'ta yük tablosu işlemini başlatma

Ek bilgi

Çalışma zamanı yardımcı programları

Oturum bağlam bilgilerini gösterme

Oturum yönetimi

Etkileşimli oturumu durdurma

Python yorumlayıcısını yeniden başlatma

Bilinen sorun

İlgili içerik

Geri Bildirim

Ek kaynaklar