NotebookUtils (dříve MSSparkUtils) pro Prostředky infrastruktury

Článek
01/13/2025

Notebook Utilities (NotebookUtils) je integrovaný balíček, který vám pomůže snadno provádět běžné úlohy v poznámkovém bloku Fabric. NotebookUtils můžete použít k práci se systémy souborů, k získání proměnných prostředí, ke zřetězení poznámkových bloků a práci s tajnými kódy. Balíček NotebookUtils je k dispozici v kanálech PySpark (Python), Scala, SparkR a Fabric.

Poznámka:

MsSparkUtils je oficiálně přejmenována na NotebookUtils. Stávající kód zůstane zpětně kompatibilní a nezpůsobí žádné zásadní změny. Důrazně doporučujeme upgradovat na nástroje poznámkových bloků, abyste zajistili nepřetržitou podporu a přístup k novým funkcím. Obor názvů mssparkutils bude v budoucnu vyřazen.
NotebookUtils je navržený tak, aby fungoval se Sparkem 3.4(Runtime v1.2) a novějším. Všechny nové funkce a aktualizace jsou nadále výhradně podporovány s namespace notebookutils.

Nástroje systému souborů

notebookutils.fs poskytuje nástroje pro práci s různými systémy souborů, včetně Azure Data Lake Storage (ADLS) Gen2 a Azure Blob Storage. Ujistěte se, že správně nakonfigurujete přístup ke službě Azure Data Lake Storage Gen2 a Azure Blob Storage .

Pro přehled dostupných metod spusťte následující příkazy:

notebookutils.fs.help()

Výstup

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 pracuje se systémem souborů stejným způsobem jako rozhraní API Sparku. Použití notebookutils.fs.mkdirs() a Fabric Lakehouse, například:

Využití	Relativní cesta z kořenového adresáře HDFS	Absolutní cesta pro systém souborů ABFS	Absolutní cesta k místnímu systému souborů v uzlu ovladače
Non-default lakehouse	Nepodporováno	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Výchozí jezero	Adresář v části Soubory nebo Tabulky: notebookutils.fs.mkdirs("Soubory/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")

Zobrazení souborů

Pokud chcete zobrazit seznam obsahu adresáře, použijte notebookutils.fs.ls(Cesta k vašemu adresáři). Příklad:

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

Rozhraní API notebookutils.fs.ls() se při použití relativní cesty chová odlišně podle typu poznámkového bloku.

v poznámkovém bloku Sparku: Relativní cesta je relativní vzhledem k výchozí cestě ABFSS lakehouse. Například notebookutils.fs.ls("Files") odkazuje na adresář Files ve výchozím Lakehouse.

Příklad:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
V poznámkovém bloku Pythonu: Relativní cesta je vztažena k pracovnímu adresáři místního systému souborů, který je ve výchozím nastavení /home/trusted-service-user/work. Proto byste měli použít úplnou cestu místo relativní cesty notebookutils.fs.ls("/lakehouse/default/Files") pro přístup k adresáři Files ve výchozím Lakehouse.

Příklad:
```
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
```

Zobrazení vlastností souboru

Tato metoda vrátí vlastnosti souboru, včetně názvu souboru, cesty k souboru, velikosti souboru a toho, jestli se jedná o adresář a soubor.

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

Vytvoření nového adresáře

Tato metoda vytvoří daný adresář, pokud neexistuje, a vytvoří všechny nezbytné nadřazené adresáře.

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

Kopírování souboru

Tato metoda zkopíruje soubor nebo adresář a podporuje aktivitu kopírování napříč systémy souborů.

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

Poznámka:

Vzhledem k omezením zástupce OneLake , pokud potřebujete použít notebookutils.fs.cp() ke kopírování dat ze zástupce typu S3/GCS, doporučujeme místo cesty abfss použít připojenou (mountovanou) cestu.

Výkonný soubor kopírování

Tato metoda nabízí efektivnější přístup ke kopírování nebo přesouvání souborů, zejména při práci s velkými objemy dat. Pro zvýšení výkonu prostředků infrastruktury je vhodné použít fastcp jako náhradu za tradiční cp metodu.

Poznámka:

notebookutils.fs.fastcp() nepodporuje kopírování souborů ve OneLake napříč oblastmi. V takovém případě můžete místo toho použít notebookutils.fs.cp() .
Vzhledem k omezením zástupce OneLake , pokud potřebujete použít notebookutils.fs.fastcp() ke kopírování dat ze zástupce typu S3/GCS, doporučujeme místo cesty abfss použít připojenou (mountovanou) cestu.

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

Náhled obsahu souboru

Tato metoda vrátí až první bajty maxBytes daného souboru jako String kódovaný v UTF-8.

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

Přesun souboru

Tato metoda přesune soubor nebo adresář a podporuje přesuny mezi systémy souborů.

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.

Zápis souboru

Tato metoda zapíše daný řetězec do souboru zakódovaného v UTF-8.

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

Připojení obsahu k souboru

Tato metoda připojí daný řetězec k souboru zakódovanému v UTF-8.

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

Poznámka:

notebookutils.fs.append() a notebookutils.fs.put() nepodporuje souběžné zápisy do stejného souboru kvůli nedostatku záruk atomicity.
Při použití rozhraní API notebookutils.fs.append ve smyčce for k zápisu do stejného souboru doporučujeme přidat příkaz sleep přibližně 0,5s ~ 1s mezi opakovanými zápisy. Toto doporučení je proto, že interní operace notebookutils.fs.append rozhraní API flush je asynchronní, takže krátká prodleva pomáhá zajistit integritu dat.

Odstranění souboru nebo adresáře

Tato metoda odebere soubor nebo adresář.

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

Připojení nebo odpojení adresáře

Další informace o podrobném využití najdete v připojení k souboru a odpojení.

Nástroje poznámkového bloku

Pomocí nástrojů poznámkového bloku spusťte poznámkový blok nebo ukončete poznámkový blok s hodnotou. Spuštěním následujícího příkazu získejte přehled dostupných metod:

notebookutils.notebook.help()

Výstup:


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.

Poznámka:

Nástroje poznámkového bloku se nevztahují na definice úloh Apache Sparku (SJD).

Odkaz na poznámkový blok

Tato metoda odkazuje na poznámkový blok a vrátí jeho výstupní hodnotu. Volání vnořené funkce můžete v poznámkovém bloku spouštět interaktivně nebo v kanálu. Odkazovaný poznámkový blok běží ve fondu Sparku poznámkového bloku, který tuto funkci volá.

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

Příklad:

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

Poznámkový blok Prostředků infrastruktury také podporuje odkazování na poznámkové bloky napříč několika pracovními prostory zadáním ID pracovního prostoru.

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

Odkaz na snímek odkazu můžete otevřít ve výstupu buňky. Snímek zachycuje výsledky spuštění kódu a umožňuje snadné ladění referenčního spuštění.

Poznámka:

Referenční poznámkový blok mezi pracovními prostory podporuje modul runtime verze 1.2 a vyšší.
Pokud používáte soubory v části Prostředek poznámkového bloku, použijte notebookutils.nbResPath v odkazovaném poznámkovém bloku, abyste měli jistotu, že odkazuje na stejnou složku jako interaktivní spuštění.

Paralelní spouštění více poznámkových bloků

Důležité

Tato funkce je ve verzi Preview.

Tato metoda notebookutils.notebook.runMultiple() umožňuje paralelně spouštět více poznámkových bloků nebo s předdefinovanou topologickou strukturou. Rozhraní API používá mechanismus vícevláknové implementace v rámci relace Sparku, což znamená, že referenční poznámkové sešity sdílejí výpočetní prostředky.

Pomocí notebookutils.notebook.runMultiple():

Spusťte několik poznámkových bloků současně, aniž byste museli čekat na dokončení každého z nich.
Pomocí jednoduchého formátu JSON určete závislosti a pořadí provádění poznámkových bloků.
Optimalizujte využití výpočetních prostředků Sparku a snižte náklady na vaše projekty Fabric.
Prohlédněte si snímky každého záznamu spuštění poznámkového bloku ve výstupu a pohodlně laďte/monitorujte úlohy poznámkového bloku.
Získejte výstupní hodnotu jednotlivých aktivit vedení a použijte je v podřízených úkolech.

Můžete se také pokusit spustit notebookutils.notebook.help("runMultiple") a vyhledat příklad a podrobné využití.

Tady je jednoduchý příklad paralelního spuštění seznamu poznámkových bloků pomocí této metody:


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

Výsledek spuštění z kořenového poznámkového bloku je následující:

Tady je příklad spouštění poznámkových bloků s topologickou strukturou pomocí notebookutils.notebook.runMultiple(). Pomocí této metody můžete snadno orchestrovat poznámkové bloky prostřednictvím prostředí kódu.

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

Výsledek spuštění z kořenového poznámkového bloku je následující:

Poskytujeme také metodu, která zkontroluje, jestli je daG správně definovaná.

notebookutils.notebook.validateDAG(DAG)

Poznámka:

Stupeň paralelismu spuštění více poznámkových bloků je omezený na celkový dostupný výpočetní prostředek relace Sparku.
Horní limit pro aktivity poznámkového bloku nebo souběžné poznámkové bloky je 50. Překročení tohoto limitu může vést k problémům se stabilitou a výkonem kvůli vysokému využití výpočetních prostředků. Pokud dojde k problémům, zvažte oddělení poznámkových bloků do několika runMultiple volání nebo snížení souběžnosti úpravou pole souběžnosti v parametru DAG.
Výchozí časový limit pro celý DAG je 12 hodin a výchozí časový limit pro každou buňku v podřízeném poznámkovém bloku je 90 sekund. Můžete změnit časový limit nastavením polí timeoutInSeconds a timeoutPerCellInSeconds v parametru DAG.

Ukončení poznámkového bloku

Tato metoda ukončí poznámkový blok s hodnotou. Volání vnořené funkce můžete v poznámkovém bloku spouštět interaktivně nebo v kanálu.

Když z poznámkového bloku interaktivně zavoláte funkci exit(), poznámkový blok Fabric vyvolá výjimku, přeskočí následné buňky a udržuje relaci Sparku naživu.
Když orchestrujete poznámkový blok v pipeline, která volá funkci exit(), úloha poznámkového bloku se vrátí s návratovou hodnotou. Tím se dokončí běh pipeline a ukončí se Spark relace.
Při volání funkce exit() v poznámkovém bloku, na který se odkazuje, zastaví Spark další spuštění odkazovaného poznámkového bloku a bude dál spouštět další buňky v hlavním poznámkovém bloku, které volají funkci run(). Například: Notebook1 obsahuje tři buňky a volá funkci exit() ve druhé buňce. Poznámkový blok2 obsahuje pět buněk a volání run(notebook1) ve třetí buňce. Při spuštění poznámkového bloku 2 se poznámkový blok 1 zastaví na druhé buňce při stisknutí funkce exit(). Poznámkový blok 2 bude dál spouštět svou čtvrtou buňku a pátou buňku.

notebookutils.notebook.exit("value string")

Poznámka:

Funkce exit() přepíše aktuální výstup buňky. Pokud se chcete vyhnout ztrátě výstupu jiných příkazů kódu, zavolejte notebookutils.notebook.exit() v samostatné buňce.

Příklad:

Ukázkový 1 poznámkový blok s následujícími dvěma buňkami:

Buňka 1 definuje vstupní parametr s výchozí hodnotou nastavenou na 10.
Buňka 2 ukončí poznámkový blok se vstupem jako výstupní hodnotou.

Ukázku 1 můžete spustit v jiném poznámkovém bloku s výchozími hodnotami:

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

Výstup:

Notebook is executed successfully with exit value 10

Ukázku 1 můžete spustit v jiném poznámkovém bloku a nastavit vstupní hodnotu na 20:

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

Výstup:

Notebook is executed successfully with exit value 20

Správa artefaktů poznámkového bloku

notebookutils.notebook poskytuje specializované nástroje pro správu položek poznámkového bloku prostřednictvím kódu programu. Tato rozhraní API vám můžou pomoct snadno vytvářet, získávat, aktualizovat a odstraňovat položky poznámkového bloku.

Pokud chcete tyto metody efektivně využít, zvažte následující příklady použití:

Vytvoření poznámkového bloku

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

Získání obsahu poznámkového bloku

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

Aktualizace poznámkového bloku

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

Odstranění poznámkového bloku

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

Výpis poznámkových bloků v pracovním prostoru

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

Nástroje pro přihlašovací údaje

Pomocí nástrojů pro přihlašovací údaje můžete získat přístupové tokeny a spravovat tajné kódy ve službě Azure Key Vault.

Spuštěním následujícího příkazu získejte přehled dostupných metod:

notebookutils.credentials.help()

Výstup:

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

Získání tokenu

getToken vrátí token Microsoft Entra pro danou cílovou skupinu a název (volitelné). V následujícím seznamu jsou uvedeny aktuálně dostupné klíče cílové skupiny:

Prostředek cílové skupiny úložiště: "storage"
Prostředek Power BI: pbi
Prostředek služby Azure Key Vault: "keyvault"
Prostředek Synapse RTA KQL DB: Kusto

Spuštěním následujícího příkazu získejte token:

notebookutils.credentials.getToken('audience Key')

Získání tajného kódu pomocí přihlašovacích údajů uživatele

getSecret vrátí tajný klíč služby Azure Key Vault pro daný koncový bod služby Azure Key Vault a název tajného kódu pomocí přihlašovacích údajů uživatele.

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

Připojení a odpojení souboru

Prostředky infrastruktury podporují následující scénáře připojení v balíčku Microsoft Spark Utilities. K připojení vzdáleného úložiště (ADLS Gen2) můžete použít rozhraní API pro připojení připojení, odpojení, getMountPath() a připojení (ADLS Gen2) ke všem pracovním uzlům (uzel ovladače a pracovní uzly). Po umístění přípojného bodu úložiště použijte místní souborové rozhraní API pro přístup k datům, jako by byla uložena v místním systému souborů.

Připojení účtu ADLS Gen2

Následující příklad ukazuje, jak připojit Azure Data Lake Storage Gen2. Připojení služby Blob Storage funguje podobně.

Tento příklad předpokládá, že máte jeden účet Data Lake Storage Gen2 s názvem storegen2 a účet má jeden kontejner s názvem mycontainer , který chcete připojit k /test do relace Sparku poznámkového bloku.

Pokud chcete připojit kontejner s názvem mycontainer, musí nástroje notebookutils nejprve zkontrolovat, jestli máte oprávnění pro přístup k kontejneru. Prostředky infrastruktury v současné době podporují dvě metody ověřování pro operaci připojení triggeru: accountKey a sastoken.

Připojení prostřednictvím tokenu sdíleného přístupového podpisu nebo klíče účtu

NotebookUtils podporuje explicitní předání klíče účtu nebo tokenu sdíleného přístupového podpisu (SAS) jako parametru pro připojení cíle.

Z bezpečnostních důvodů doporučujeme ukládat klíče účtu nebo tokeny SAS ve službě Azure Key Vault (jak ukazuje následující snímek obrazovky). Pak je můžete načíst pomocí rozhraní notebookutils.credentials.getSecret API. Další informace o službě Azure Key Vault najdete v tématu o klíčích účtu spravovaného úložiště služby Azure Key Vault.

Ukázkový kód pro metodu accountKey :

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

Ukázkový kód pro sastoken:

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

Parametry připojení:

fileCacheTimeout: Objekty blob se ve výchozím nastavení ukládají do místní dočasné složky po dobu 120 sekund. Během této doby blobfuse nekontroluje, jestli je soubor aktuální nebo ne. Parametr může být nastaven tak, aby změnil výchozí časový limit. Pokud několik klientů současně upravuje soubory, aby nedocházelo k nekonzistence mezi místními a vzdálenými soubory, doporučujeme zkrátit dobu mezipaměti nebo dokonce změnit na 0 a vždy získat nejnovější soubory ze serveru.
časový limit: Časový limit operace připojení je ve výchozím nastavení 120 sekund. Parametr může být nastaven tak, aby změnil výchozí časový limit. Pokud dojde k příliš velkému počtu exekutorů nebo když vyprší časový limit připojení, doporučujeme zvýšit hodnotu.

Můžete použít následující parametry:

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

Poznámka:

Pro účely zabezpečení se doporučuje vyhnout vkládání přihlašovacích údajů přímo do kódu. Pro ochranu vašich přihlašovacích údajů jsou všechny tajnosti zobrazené ve výstupech poznámkového bloku redigovány. Další informace najdete v tématu Redaction tajného kódu.

Jak připojit jezerní dům

Vzorový kód pro připojení jezera k /<mount_name>:

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

Přístup k souborům pod přípojným bodem pomocí rozhraní API notebookutils fs

Hlavním účelem operace připojení je umožnit zákazníkům přístup k datům uloženým ve vzdáleném účtu úložiště pomocí místního rozhraní API systému souborů. K datům můžete přistupovat také pomocí rozhraní API služby notebookutils fs s připojenou cestou jako parametrem. Tento formát cesty se trochu liší.

Předpokládejme, že jste kontejner Data Lake Storage Gen2 připojili mycontainer k /test pomocí rozhraní API pro připojení. Při přístupu k datům pomocí místního rozhraní API systému souborů je formát cesty podobný tomuto:

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

Pokud chcete získat přístup k datům pomocí rozhraní API služby notebookutils fs, doporučujeme použít getMountPath(), abyste získali přesnou cestu:

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

Seznam adresářů:

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

Čtení obsahu souboru:

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

Vytvořte adresář:

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

Přístup k souborům pod přípojným bodem prostřednictvím místní cesty

Soubory můžete snadno číst a zapisovat do přípojného bodu pomocí standardního systému souborů. Tady je příklad Pythonu:

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

Postup kontroly stávajících přípojných bodů

Ke kontrole všech existujících informací o přípojných bodech můžete použít rozhraní API notebookutils.fs.mounts( ):

notebookutils.fs.mounts()

Jak odpojit přípojný bod

Pomocí následujícího kódu odpojte přípojný bod (/otestujte v tomto příkladu):

notebookutils.fs.unmount("/test")

Známá omezení

Aktuální připojení je konfigurace na úrovni úlohy; Doporučujeme použít rozhraní API pro připojení ke kontrole, jestli přípojný bod existuje nebo není k dispozici.
Mechanismus odpojování se nepoužije automaticky. Po dokončení spuštění aplikace je potřeba odpojit přípojný bod a uvolnit místo na disku, musíte v kódu explicitně volat rozhraní API pro odpojení. V opačném případě bude přípojný bod stále existovat v uzlu po dokončení spuštění aplikace.
Připojení účtu úložiště ADLS Gen1 se nepodporuje.

Nástroje lakehouse

notebookutils.lakehouse poskytuje nástroje přizpůsobené pro správu položek Lakehouse. Tyto nástroje umožňují snadno vytvářet, získávat, aktualizovat a odstraňovat artefakty Lakehouse.

Přehled metod

Tady je přehled dostupných metod poskytovaných notebookutils.lakehouse:

# 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]

Příklady použití

Pokud chcete tyto metody efektivně využít, zvažte následující příklady použití:

Vytvoření lakehouse

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

Získání lakehouse

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

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

Aktualizace lakehouse

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

Odstranění lakehouse

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

Výpis lakehouses v pracovním prostoru

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

Výpis všech tabulek v Lakehouse

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

Spuštění operace načtení tabulky v Lakehouse

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

Další informace

Podrobnější informace o jednotlivých metodách a jejích parametrech najdete v této notebookutils.lakehouse.help("methodName") funkci.

Nástroje modulu runtime

Zobrazení informací o kontextu relace

Díky notebookutils.runtime.context tomu můžete získat kontextové informace o aktuální živé relaci, včetně názvu poznámkového bloku, výchozího objektu lakehouse, informací o pracovním prostoru, pokud se jedná o spuštění kanálu atd.

notebookutils.runtime.context

Správa relací

Zastavení interaktivní relace

Místo ručního kliknutí na tlačítko Zastavit je někdy vhodnější zastavit interaktivní relaci voláním rozhraní API v kódu. V takových případech poskytujeme rozhraní API notebookutils.session.stop(), které podporuje zastavení interaktivní relace prostřednictvím kódu, je k dispozici pro Scala a PySpark.

notebookutils.session.stop()

notebookutils.session.stop() API asynchronně zastaví aktuální interaktivní relaci na pozadí. Zastaví také Spark relaci a uvolní prostředky, které relace obsazuje, takže jsou k dispozici pro jiné relace ve stejném fondu.

Restartování interpreta Pythonu

Nástroj notebookutils.session poskytuje způsob, jak restartovat interpret Pythonu.

notebookutils.session.restartPython()

Poznámka:

V případě spuštění odkazu na poznámkový blok restartPython() restartuje interpret Pythonu aktuálního poznámkového bloku, na který se odkazuje.
Ve výjimečných případech může příkaz selhat kvůli mechanismu reflexe Sparku a přidání opakování může problém zmírnit.

Známý problém

Pokud používáte verzi modulu runtime vyšší než 1.2 a spustíte notebookutils.help(), uvedená rozhraní fabricClient, rozhraní API PBIClient se prozatím nepodporují, budou v další části k dispozici. V poznámkových blocích Scala se navíc zatím nepodporuje rozhraní API pro přihlašovací údaje .
Poznámkový blok Pythonu nepodporuje zastavení, restartPython API při použití nástroje notebookutils.session pro správu relací.

Sdílet prostřednictvím

NotebookUtils (dříve MSSparkUtils) pro Prostředky infrastruktury

Nástroje systému souborů

Zobrazení souborů

Zobrazení vlastností souboru

Vytvoření nového adresáře

Kopírování souboru

Výkonný soubor kopírování

Náhled obsahu souboru

Přesun souboru

Zápis souboru

Připojení obsahu k souboru

Odstranění souboru nebo adresáře

Připojení nebo odpojení adresáře

Nástroje poznámkového bloku

Odkaz na poznámkový blok

Paralelní spouštění více poznámkových bloků

Ukončení poznámkového bloku

Správa artefaktů poznámkového bloku

Vytvoření poznámkového bloku

Získání obsahu poznámkového bloku

Aktualizace poznámkového bloku

Odstranění poznámkového bloku

Výpis poznámkových bloků v pracovním prostoru

Nástroje pro přihlašovací údaje

Získání tokenu

Získání tajného kódu pomocí přihlašovacích údajů uživatele

Připojení a odpojení souboru

Připojení účtu ADLS Gen2

Připojení prostřednictvím tokenu sdíleného přístupového podpisu nebo klíče účtu

Jak připojit jezerní dům

Přístup k souborům pod přípojným bodem pomocí rozhraní API notebookutils fs

Přístup k souborům pod přípojným bodem prostřednictvím místní cesty

Postup kontroly stávajících přípojných bodů

Jak odpojit přípojný bod

Známá omezení

Nástroje lakehouse

Přehled metod

Příklady použití

Vytvoření lakehouse

Získání lakehouse

Aktualizace lakehouse

Odstranění lakehouse

Výpis lakehouses v pracovním prostoru

Výpis všech tabulek v Lakehouse

Spuštění operace načtení tabulky v Lakehouse

Další informace

Nástroje modulu runtime

Zobrazení informací o kontextu relace

Správa relací

Zastavení interaktivní relace

Restartování interpreta Pythonu

Známý problém

Související obsah

Váš názor

Další materiály