Doku için NotebookUtils (eski MSSparkUtils)

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.

Not

• MsSparkUtils resmi olarak NotebookUtils olarak yeniden adlandırıldı. Mevcut kod geriye dönük olarak uyumlu kalır ve hataya 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 desteklenecektir.

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ünden göreli yol	ABFS dosya sistemi için mutlak yol	Sürücü düğümündeki 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>")

Dosyaları listeleme

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

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

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

Performanslı kopyalama dosyası

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

Not

notebookutils.fs.fastcp() , OneLake'teki dosyaların bölgeler arasında kopyalanmasını desteklemez. Bu durumda, bunun yerine kullanabilirsiniz notebookutils.fs.cp() .

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

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 bağlama/çıkarma

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

Not defteri 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.

Not

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

Not defterine başvurma

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 veya işlem hattında bir not defterinde çalıştırabilirsiniz. Başvuruda bulunan 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 })

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

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

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

Not

• Çalışma alanları arası başvuru not defteri, çalışma zamanı sürüm 1.2 ve üzeri tarafından desteklenir.
• Not Defteri Kaynağı altındaki dosyaları kullanıyorsanız, notebookutils.nbResPath etkileşimli çalıştırmayla aynı klasöre işaret etmelerini sağlamak için başvuruda bulunılan not defterinde kullanın.

Başvuru birden çok not defterini paralel olarak çalıştırma

Ö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 oturumunda çok iş parçacıklı bir uygulama mekanizması kullanıyor ve bu da işlem kaynaklarının başvuru not defteri çalıştırmaları tarafından paylaşıldığı anlamına gelir.

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

• Her birinin bitip bitmeden birden çok not defterini aynı anda yürütür.

• 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örevlerinizin hatalarını rahatça ayıklayın/izleyin.

• 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 kullanarak notebookutils.notebook.runMultiple()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)

Not

• 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 alt not defterindeki her hücre için varsayılan zaman aşımı 90 saniyedir. DAG parametresindeki timeoutInSeconds ve timeoutPerCellInSeconds alanlarını ayarlayarak zaman aşımını değiştirebilirsiniz.

Not defterinden çıkma

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

• Bir not defterinden exit() işlevini etkileşimli olarak çağırdığınızda, Doku not defteri bir özel durum oluşturur, sonraki hücreleri çalıştırmayı atlar ve Spark oturumunu canlı tutar.

• Exit() işlevini çağıran bir işlem hattında bir not defterini düzenlerseniz, not defteri etkinliği bir çıkış değeriyle döner, işlem hattı çalıştırması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")

Not

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

Ö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 giriş içeren 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 yapıtlarını yönetme

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

Not Defterinin içeriğini alma

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

Not Defterini Güncelleştirme

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

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

Kimlik bilgileri 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

Belirteç alma

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 DB Kaynağı: "kusto"

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

notebookutils.credentials.getToken('audience Key')

Kullanıcı kimlik bilgilerini kullanarak gizli dizi alma

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

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

Dosya bağlama ve çıkarma

Doku, Microsoft Spark Yardımcı Programları paketinde aşağıdaki bağlama senaryolarını destekler. Tüm çalışan düğümlere (sürücü düğümü ve çalışan düğümleri) 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 örnekte Azure Data Lake Storage 2. Nesil nasıl bağlanacakları gösterilmektedir. Blob Depolama'yı bağlama benzer şekilde çalışır.

Bu örnekte storegen2 adlı bir Data Lake Storage 2. Nesil hesabınız olduğu ve hesabın not defteri Spark oturumunuza /test etmek istediğiniz mycontainer adlı bir kapsayıcısı olduğu varsayılır.

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 Doku, tetikleyici 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 bağlama

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 bkz . Azure Key Vault yönetilen depolama hesabı anahtarları hakkında.

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 zaman aşımına uğradıysa 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}
)

Not

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 diziler yeniden işleme alınır. Daha fazla bilgi için bkz . Gizli dizi yeniden eylem.

Göl evi nasıl monte edilir?

/<mount_name'a> bir göl evi 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. Ayrıca, parametre olarak bağlı bir yol ile notebookutils fs API'sini kullanarak da verilere erişebilirsiniz. Bu yol biçimi biraz farklı.

bağlama API'sini kullanarak mycontainer Data Lake Storage 2. Nesil kapsayıcısını /test'e bağladığınız varsayılır. 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 bir iş düzeyi yapılandırmasıdır; Bağlama noktası olup olmadığını denetlemek için bağlamalar API'sini kullanmanızı öneririz.

• Çı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 bulunmaya devam eder.

• ADLS 1. Nesil depolama hesabı bağlama desteklenmez.

Lakehouse yardımcı programları

notebookutils.lakehouse Lakehouse öğelerini yönetmek için özel olarak 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ış

Aşağıda tarafından notebookutils.lakehousesağlanan kullanılabilir yöntemlere genel bir bakış 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:

Göl Evi Oluşturma

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

Göl Evi Alma

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

Lakehouse silme

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'da yük tablosu işlemi 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 işlevini kullanın notebookutils.lakehouse.help("methodName") .

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

Oturum bağlam bilgilerini gösterme

ile notebookutils.runtime.context geçerli canlı oturumun bağlam bilgilerini (not defteri adı, varsayılan göl evi, çalışma alanı bilgileri, işlem hattı çalıştırması ise vb.) alabilirsiniz.

notebookutils.runtime.context

Bilinen sorun

1.2'nin üzerindeki çalışma zamanı sürümünü kullanırken ve çalıştırırken notebookutils.help()listelenen fabricClient, PBIClient API'leri şimdilik desteklenmediğinden, daha sonra kullanılabilir. Ayrıca, Kimlik Bilgileri API'si şimdilik Scala not defterlerinde desteklenmemektedir.

İlgili içerik

• Doku için Microsoft Spark Yardımcı Programları (MSSparkUtils)
• Microsoft Fabric not defterlerini geliştirme, yürütme ve yönetme
• API'lerle Doku'da not defterlerini yönetme ve yürütme