NotebookUtils (bývalý MSSparkUtils) pre Fabric

Notebook Utilities (NotebookUtils) je vstavaný balík, ktorý vám pomôže jednoducho vykonávať bežné úlohy v notebooku fabric. NotebookUtils môžete používať na prácu so súborovými systémami, získavanie premenných prostredia, reťazové poznámkové bloky a prácu s tajomstvámi. Balík NotebookUtils je k dispozícii v nástrojoch Scala (Python) v PySparku, poznámkových blokoch SparkR a kanáloch služby Fabric.

Note

MsSparkUtils je oficiálne premenovaný na NotebookUtils. Existujúci kód zostáva spätne kompatibilný a nespôsobuje žiadne zásadné zmeny. Dôrazne odporúčame upgradovať na notebookutils, aby ste zabezpečili nepretržitú podporu a prístup k novým funkciám. Priestor názvov mssparkutils sa v budúcnosti vyradí.
NotebookUtils je navrhnutý tak, aby fungoval so službou Spark 3.4(Runtime v1.2) a novšou. Všetky nové funkcie a aktualizácie sú v budúcnosti výlučne podporované v priestore názvov notebookutils.

Pomôcky systému súborov

notebookutils.fs poskytuje pomôcky na prácu s rôznymi súborovými systémami vrátane Azure Data Lake Storage (ADLS) Gen2 a Azure Blob Storage. Nezabudnite nakonfigurovať prístup k službe Azure Data Lake Storage Gen2 a úložisku Azure Blob Storage správne.

Spustite nasledujúce príkazy a získajte prehľad dostupných metód:

notebookutils.fs.help()

Output

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

Pomôcky pre notebookUtils fungujú so systémom súborov rovnakým spôsobom ako rozhrania Spark API. Vezmite si napríklad notebookutils.fs.mkdirs() a použitie Fabric lakehouse:

Usage	Relatívna cesta z koreňa HDFS	Absolútna cesta k systému súborov ABFS	Absolútna cesta k lokálnemu systému súborov v uzli ovládača
Iný ako predvolený dom pri jazere	Nepodporované	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("súbor:/<new_dir>")
Predvolený dom pri jazere	Adresár v časti Súbory alebo Tabuľky: notebookutils.fs.mkdirs("Files/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("súbor:/<new_dir>")

Pre predvolený lakehouse sú cesty k súboru pripojené v notebooku s predvoleným časovým limitom vyrovnávacej pamäte súboru 120 sekúnd. To znamená, že súbory sú uložené v lokálnom dočasnom priečinku poznámkového bloku 120 sekúnd, dokonca aj vtedy, ak sú odstránené z lakehouse. Ak chcete zmeniť pravidlo časového limitu, môžete odpojiť predvolené cesty k súborom Lakehouse a znova ich pripojiť s inou hodnotou fileCacheTimeout .
Pre iné ako predvolené konfigurácie Lakehouse môžete nastaviť príslušný parameter fileCacheTimeout počas pripájania ciest Lakehouse. Ak nastavíte časový limit na hodnotu 0, načíta sa najnovší súbor zo servera Lakehouse.

Zoznam súborov

Ak chcete zobraziť zoznam obsahu adresára, použite notebookutils.fs.ls ('Cesta k adresáru').. Naprí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

Rozhranie API notebookutils.fs.ls() sa pri použití relatívnej cesty správa inak v závislosti od typu poznámkového bloku.

v notebooku Spark: Relatívna cesta je relatívna k predvolenej ceste ABFSS lakehouse. Napríklad notebookutils.fs.ls("Files") odkazuje na Files adresár v predvolenom komplexe Lakehouse.

Napríklad:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
V poznámkovom bloku jazyka Python: Relatívna cesta je relatívna vzhľadom na pracovný adresár lokálneho systému súborov, ktorý je v predvolenom nastavení /home/trusted-service-user/work. Preto by ste mali namiesto relatívnej cesty použiť úplnú cestu notebookutils.fs.ls("/lakehouse/default/Files") na prístup k adresáru Files v predvolenom komplexe Lakehouse.

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

Zobrazenie vlastností súboru

Táto metóda vráti vlastnosti súboru vrátane názvu súboru, cesty k súboru, veľkosti súboru a toho, či ide o adresár a súbor.

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

Vytvorenie nového adresára

Táto metóda vytvorí daný adresár, ak neexistuje, a vytvorí všetky potrebné nadradené adresáre.

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írovať súbor

Táto metóda skopíruje súbor alebo adresár a podporuje aktivitu kopírovania v súborových systémoch. Nastavili recurse=True sme rekurzívne kopírovanie všetkých súborov a adresárov.

notebookutils.fs.cp('source file or directory', 'destination file or directory', recurse=True)

Note

Vzhľadom na obmedzenia klávesovej skratky OneLake, keď potrebujete použiť notebookutils.fs.cp() na kopírovanie údajov z odkazu na typ S3/GCS, odporúča sa použiť pripevnenú cestu namiesto cesty so abfss.

Výkonný kopírovací súbor

Táto metóda ponúka efektívnejší prístup k kopírovaniu alebo presúvaniu súborov, najmä pri práci s veľkými objemami údajov. Na zvýšenie výkonu v službe fastcp Fabric sa odporúča použiť ako náhrada za tradičnú cp metódu.

notebookutils.fs.fastcp('source file or directory', 'destination file or directory', recurse=True)

Úvahy:

notebookutils.fs.fastcp() Nepodporuje kopírovanie súborov vo OneLake naprieč oblasťami. V tomto prípade môžete namiesto toho použiť funkciu notebookutils.fs.cp() .
Vzhľadom na obmedzenia klávesovej skratky OneLake, keď potrebujete použiť notebookutils.fs.fastcp() na kopírovanie údajov z odkazu na typ S3/GCS, odporúča sa použiť pripevnenú cestu namiesto cesty so abfss.

Zobraziť ukážku obsahu súboru

Táto metóda vráti až prvé bajty "maxBytes" daného súboru ako reťazec kódovaný v UTF-8.

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

Presunúť súbor

Táto metóda premiestni súbor alebo adresár a podporuje presuny do súborových systémov.

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.

Napísať súbor

Táto metóda zapíše daný reťazec do súboru, ktorý je kódovaný 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

Pripojenie obsahu k súboru

Táto metóda pripojí daný reťazec k súboru, ktorý je kódovaný 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

Úvahy:

notebookutils.fs.append() a notebookutils.fs.put() nepodporujú súbežné písanie na rovnaký súbor z dôvodu nedostatku záruk atomity.
Pri písaní do rovnakého súboru pomocou rozhrania notebookutils.fs.append API v slučke for, odporúčame pridať medzi opakujúce sa zápisy príkaz sleep približne 0,5 s ~ 1 s. Toto odporúčanie je spôsobené tým, že notebookutils.fs.append interná operácia flush rozhrania API je asynchrónne, takže krátke oneskorenie pomáha zabezpečiť integritu údajov.

Odstránenie súboru alebo adresára

Táto metóda odstráni súbor alebo adresár. Nastavili recurse=True sme rekurzívne odstránenie všetkých súborov a adresárov.

notebookutils.fs.rm('file path', recurse=True)

Pripojiť/odpojiť adresár

Ďalšie informácie o podrobnom používaní nájdete v téme Pripojenie a zrušenie pripojenia súboru.

Pomôcky pre notebooky

Pomocou pomôcok poznámkového bloku môžete spustiť poznámkový blok alebo ukončiť poznámkový blok s hodnotou. Spustením nasledujúceho príkazu získate prehľad dostupných metód:

notebookutils.notebook.help()

Output:


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] -> Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> This method check if the DAG is correctly defined.

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.

Note

Pomôcky poznámkového blokov nie sú použiteľné pre definície úloh Apache Spark (SJD).

Odkaz na poznámkový blok

Táto metóda odkazuje na poznámkový blok a vráti jeho výstupnú hodnotu. Volania vnorených funkcií môžete spustiť interaktívne v poznámkovom bloke alebo v kanáli. Poznámkový blok, na ktorý sa odkazuje, je spustený vo fonde spark poznámkového bloku, ktorý túto funkciu volá.

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

Napríklad:

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

Poznámkový blok Fabric tiež podporuje odkazovanie na poznámkové bloky vo viacerých pracovných priestoroch zadaním ID pracovného priestoru.

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

Prepojenie na snímku odkazu môžete otvoriť v bunke výstupe. Snímka zaznamenáva výsledky spustenia kódu a umožňuje jednoducho ladiť referenčné spustenie.

Úvahy:

Referenčný poznámkový blok krížového pracovného priestoru je podporovaný verziou 1.2 a novšou verziou modulu runtime.
Ak používate súbory v časti Zdroj poznámkového bloku, použite notebookutils.nbResPath odkazovaný poznámkový blok, aby ste sa uistili, že odkazuje na rovnaký priečinok ako interaktívne spustenie.
Spustenie odkazu umožňuje spustenie podriadených poznámkových blokov iba v prípade, že používajú rovnaký jazerný dom ako nadradený objekt, dedia nadradený jazerársky dom alebo ho nedefinuje. Spustenie sa zablokuje, ak dieťa zadá iný poznámkový blok pri jazere. Ak chcete túto kontrolu obísť, nastavte useRootDefaultLakehouse: True.

Odkaz na paralelné spustenie viacerých poznámkových blokov

Metóda notebookutils.notebook.runMultiple() vám umožňuje spustiť viaceré poznámkové bloky paralelne alebo s preddefinovanou topologickou štruktúrou. Rozhranie API používa mechanizmus implementácie viacerých vlákien v rámci relácie spark, čo znamená, že referenčný poznámkový blok je spustený a zdieľa výpočtové zdroje.

S možnosťou notebookutils.notebook.runMultiple()môžete:

Vykonajte viacero poznámkových blokov súčasne bez čakania na dokončenie každého z nich.
Zadajte závislosti a poradie vykonávania pre poznámkové bloky pomocou jednoduchého formátu JSON.
Optimalizujte použitie výpočtových zdrojov služby Spark a znížte náklady na projekty služby Fabric.
Zobrazte snímky každého záznamu spúšťania poznámkového bloku vo výstupe a pohodlné ladenie/monitorovanie úloh poznámkového bloku.
Získajte hodnotu výstupu každej aktivity vedúceho pracovníka a použite ich v následných úlohách.

Môžete tiež skúsiť spustiť notebookutils.notebook.help("runMultiple") a nájsť príklad a podrobné použitie.

Tu je jednoduchý príklad paralelného spustenia zoznamu poznámkových blokov pomocou tejto metódy:

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

Výsledok spustenia koreňového poznámkového bloku je nasledovný:

Tu je príklad spustenia poznámkových blokov s topologickou štruktúrou pomocou notebookutils.notebook.runMultiple(). Pomocou tejto metódy môžete jednoducho koordinovať poznámkové bloky prostredníctvom prostredia 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ýsledok spustenia koreňového poznámkového bloku je nasledovný:

Poskytujeme aj metódu na kontrolu správneho definovania jazyka DAG.

notebookutils.notebook.validateDAG(DAG)

Úvahy:

Stupeň paralelného spustenia viacerých poznámkových blokov je obmedzený na celkový dostupný výpočtový prostriedok relácie služby Spark.
Predvolený počet súbežných notebookov je 50 pre Spark notebook, zatiaľ čo pre Python Notebook je to predvolene 25 . Túto hodnotu si môžete prispôsobiť, ale nadmerný paralelizmus môže viesť k problémom so stabilitou a výkonom kvôli vysokej spotrebe výpočtových zdrojov. Ak sa vyskytnú problémy, zvážte rozdelenie poznámkových blokov do viacerých runMultiple volaní alebo zníženie súbežnosti úpravou poľa súbežnosti v parametri DAG.
Predvolený časový odstup pre celý jazyk DAG je 12 hodín a predvolený časový odstup pre každú bunku v podriadenom poznámkovom bloke je 90 sekúnd. Časový limit môžete zmeniť nastavením polí timeoutInSeconds a timeoutPerCellInSeconds v parametri DAG.

Ukončenie poznámkového bloku

Táto metóda ukončí poznámkový blok s hodnotou. Volania vnorených funkcií môžete spustiť interaktívne v poznámkovom bloke alebo v kanáli.

Keď interaktívne zavoláte funkciu exit() z poznámkového bloku, poznámkový blok Fabric vyvolá výnimku, preskočí spustenie nasledujúcich buniek a udrží reláciu Spark nažive.
Pri koordinovaní poznámkového bloku v kanáli, ktorý volá funkciu exit(), sa aktivita poznámkového bloka vráti s hodnotou výstupu. Tým sa dokončí spustenie kanála a zastaví sa relácia Spark.
Keď zavoláte funkciu exit() v poznámkovom bloku, na ktorý sa odkazuje, Fabric Spark zastaví ďalšie vykonávanie odkazovaného poznámkového bloku a bude pokračovať v spúšťaní ďalších buniek v hlavnom poznámkovom bloku, ktorý volá funkciu run(). Napríklad: Poznámkový blok1 má tri bunky a v druhej bunke volá funkciu exit(). Notebook2 má päť buniek a hovory run(notebook1) v tretej bunke. Keď spustíte Notebook2, Notebook1 sa po stlačení funkcie exit() zastaví v druhej bunke. Notebook2 naďalej spúšťa svoju štvrtú bunku a piatu bunku.

notebookutils.notebook.exit("value string")

Note

Funkcia exit() prepíše aktuálny výstup bunky. Ak sa chcete vyhnúť strate výstupu iných príkazov kódu, zavolajte notebookutils.notebook.exit() v samostatnej bunke.

Napríklad:

Poznámkový blok Sample1 s nasledujúcimi dvoma bunkami:

Bunka 1 definuje vstupný parameter s predvolenou hodnotou nastavenou na 10.
Bunka 2 ukončí poznámkový blok so vstupom ako výstupnou hodnotou.

Ukážku1 môžete spustiť v inom poznámkovom bloku s predvolenými hodnotami:

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

Output:

Notebook is executed successfully with exit value 10

Ukážku1 môžete spustiť v inom poznámkovom bloku a nastaviť vstupnú hodnotu na 20:

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

Output:

Notebook is executed successfully with exit value 20

Spravovanie poznámkových blokov artefaktov

notebookutils.notebook Poskytuje špecializované pomôcky na programovú správu položiek poznámkového bloku. Tieto rozhrania API vám môžu pomôcť jednoducho vytvárať, získavať, aktualizovať a odstraňovať položky poznámkového bloku.

Ak chcete efektívne využiť tieto metódy, zvážte nasledujúce príklady používania:

Vytvorenie 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ískanie obsahu poznámkového bloku

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

Aktualizácia 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")

Odstránenie poznámkového bloku

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

Zápisníky v pracovnom priestore

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

Pomôcky funkcie User Data Function (UDF)

notebookutils.udf poskytuje pomôcky určené na integráciu kódu notebooku s používateľskými dátovými funkciami (User Data Functions, UDF). Tieto pomôcky vám umožňujú získať prístup k funkciám z položky UDF v rámci toho istého pracovného priestoru alebo v rôznych pracovných priestoroch. Potom môžete podľa potreby vyvolať funkcie v rámci položky UDF.

Tu je niekoľko príkladov použitia pomôcok UDF:

# Get functions from a UDF item
myFunctions = notebookutils.udf.getFunctions('UDFItemName')
# Or from another workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

# Display function and item details
display(myFunctions.functionDetails)
display(myFunctions.itemDetails)

# Invoke a function
myFunctions.functionName('value1', 'value2')
# Or with named parameters
myFunctions.functionName(parameter1='value1', parameter2='value2')

Načítanie funkcií z jazyka UDF

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

Vyvolanie funkcie

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

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

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

Zobrazenie podrobností pre položku UDF

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Zobrazenie podrobností o funkciách pre UDF

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Poverenia pomôcky

Pomocou pomôcok poverení môžete získať prístupové tokeny a spravovať tajné kódy v službe Azure Key Vault.

Spustením nasledujúceho príkazu získate prehľad dostupných metód:

notebookutils.credentials.help()

Output:

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ískať token

Funkcia getToken vráti token Microsoft Entra pre danú cieľovú skupinu a meno (voliteľné). Nasledujúci zoznam zobrazuje aktuálne dostupné kľúče cieľovej skupiny:

Zdroj publika úložiska: "úložisko"
Zdroj služby Power BI: pbi
Prostriedok služby Azure Key Vault: "keyvault"
Synapse RTA KQL DB Zdroj: "kusto"

Spustite nasledujúci príkaz, aby ste získali token:

notebookutils.credentials.getToken('audience Key')

Úvahy:

Rozsahy tokenov s publikom "pbi" sa môžu časom meniť. V súčasnosti sú podporované nasledujúce rozsahy.
Keď zavoláte notebookutils.credentials.getToken("pbi")), vrátený token má obmedzený rozsah, ak je poznámkový blok spustený v rámci objektu služby. Token nemá úplný rozsah služby Fabric. Ak je poznámkový blok spustený pod identitou používateľa, token má stále úplný rozsah služby Fabric, ale to sa môže zmeniť s vylepšeniami zabezpečenia. Ak chcete zabezpečiť, aby token mal úplný rozsah služby Fabric, použite overovanie MSAL namiesto rozhrania notebookutils.credentials.getToken API. Ďalšie informácie nájdete v téme Overenie pomocou Microsoft Entra ID.
Nasleduje zoznam rozsahov, ktoré má token pri volaní notebookutils.credentials.getToken s kľúčom cieľovej skupiny pbi pod identitou objektu služby:
- Lakehouse.ReadWrite.All
- MLExperiment.ReadWrite.All
- MLModel.ReadWrite.All
- Notebook.ReadWrite.All
- SparkJobDefinition.ReadWrite.All
- Workspace.ReadWrite.All
- Dataset.ReadWrite.All

Získanie tajnosti

Funkcia getSecret vráti tajný kód služby Azure Key Vault pre daný koncový bod a meno tajného kódu služby Azure Key Vault pomocou prihlasovacích údajov používateľa.

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

Pripojenie a zrušenie pripojenia k súboru

Služba Fabric podporuje nasledujúce možnosti pripojenia v balíku služby Microsoft Spark Utilities. Rozhrania API mount, unmount, getMountPath() a mounts() môžete použiť na pripojenie vzdialeného úložiska (ADLS Gen2) ku všetkým pracovným uzlom (uzle ovládača a pracovné uzly). Po uložení bodu pripojenia ukladacieho priestoru použite rozhranie API lokálneho súboru na prístup k údajom, akoby boli uložené v lokálnom systéme súborov.

Ako pripojiť konto služby ADLS Gen2

V nasledujúcom príklade je znázornené, ako pripojiť Azure Data Lake Storage Gen2. Pripojenie Blob Storage a Azure File Share funguje podobne.

V tomto príklade sa predpokladá, že máte jedno konto Data Lake Storage Gen2 s názvom storegen2, ktoré má kontajner s názvom mycontainer , ktorý chcete pripojiť k /test v relácii Spark poznámkového bloku.

Ak chcete pripojiť kontajner s názvom mycontainer, notebookutils musí najprv skontrolovať, či máte povolenie na prístup ku kontajneru. V súčasnosti Fabric podporuje dve metódy overovania pre operáciu pripojenia spúšťača: accountKey a sastoken.

Pripojenie prostredníctvom tokenu podpisu zdieľaného prístupu alebo kľúča konta

Pomôcka NotebookUtils podporuje explicitné odovzdanie kľúča konta alebo tokenu Podpis zdieľaného prístupu (SAS) ako parametra na pripojenie cieľa.

Z bezpečnostných dôvodov odporúčame uložiť kľúče kont alebo tokeny SAS v službe Azure Key Vault (ako je znázornené na nasledujúcej snímke obrazovky). Potom ich môžete načítať pomocou rozhrania Notebookutils.credentials.getSecret API. Ďalšie informácie o službe Azure Key Vault nájdete v téme Informácie o kľúčoch konta spravovaného úložiska Azure Key Vault.

Vzorový kód pre metódu 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}
)

Vzorový kód pre 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}
)

Parametre montáže:

fileCacheTimeout: Objekty BLOB sú predvolene uložené vo vyrovnávacej pamäti v miestnom dočasnom priečinku na 120 sekúnd. Počas tohto obdobia objekt blobfuse nekontroluje, či je súbor aktualizovaný alebo nie. Parameter možno nastaviť tak, aby sa zmenil predvolený časový parameter. Ak viacerí klienti upravujú súbory v rovnakom čase, odporúčame skrátiť čas vyrovnávacej pamäte alebo dokonca zmeniť ho na 0 a vždy získať z servera najnovšie súbory.
časový limit: Časový limit operácie pripojenia je predvolene 120 sekúnd. Parameter možno nastaviť tak, aby sa zmenil predvolený časový parameter. Keď je príliš veľa spustiteľných vykonaní, alebo keď unikne čas pripojenia, odporúča sa zvýšiť hodnotu.

Nasledujúce parametre môžete použiť:

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

Note

Z bezpečnostných dôvodov sa odporúča nevkladať poverenia priamo do kódu. Ak chcete ďalej chrániť svoje poverenia, všetky tajné kódy zobrazené vo výstupoch poznámkového bloku sú redigované. Ďalšie informácie nájdete v téme Tajné redigovanie.

Ako pripojiť lakehouse

Vzorový kód pre montáž jazera do /<mount_name>:

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

Prístup k súborom v bode pripojenia pomocou rozhrania Notebookutils fs API

Hlavným účelom operácie pripojenia je umožniť zákazníkom prístup k údajom uloženým vo vzdialenom konte úložiska s lokálnym rozhraním API systému súborov. K údajom môžete pristupovať aj pomocou rozhrania API notebookutils fs s pripojenou cestou ako parametrom. Tento formát cesty je trochu iný.

Predpokladajme, že ste pripojili kontajner Data Lake Storage Gen2 mycontainer do /test pomocou rozhrania API pripojenia. Keď pristupujete k údajom pomocou rozhrania API lokálneho systému súborov, formát cesty je takýto:

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

Ak chcete získať prístup k údajom pomocou notebookutils fs API, odporúčame použiť getMountPath() na získanie presnej cesty:

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

Zoznam adresárov:

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

Čítať obsah súboru:

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

Vytvorte adresár:

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

Prístup k súborom pod bodom pripojenia cez lokálnu cestu

Súbory môžete jednoducho čítať a zapisovať do bodu pripojenia pomocou štandardného systému súborov. Tu je príklad jazyka Python:

#File read
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "r") as f:
    print(f.read())
#File write
with open(notebookutils.fs.getMountPath('/test2') + "/myFile.txt", "w") as f:
    print(f.write("dummy data"))

Kontrola existujúcich bodov pripojenia

Rozhranie API notebookutils.fs.mounts() môžete použiť na kontrolu všetkých existujúcich informácií o prípojných bodoch:

notebookutils.fs.mounts()

Ako zrušiť pripojenie bodu pripojenia

Pomocou nasledujúceho kódu odpojte prípojný bod (v tomto príklade /test ):

notebookutils.fs.unmount("/test")

Známe obmedzenia

Aktuálny držiak je konfigurácia na úrovni úlohy; Odporúčame vám použiť rozhranie API pripojenia na kontrolu, či bod pripojenia existuje alebo nie je k dispozícii.
Mechanizmus unmount sa nepoužije automaticky. Po dokončení spustenia aplikácie musíte explicitne zavolať rozhranie API na zrušenie pripojenia a uvoľniť miesto na disku. V opačnom prípade bude bod pripojenia po dokončení spustenia aplikácie naďalej existovať v uzli.
Montáž konta úložiska ADLS Gen1 nie je podporovaná.

Inžinierske siete pri jazere

notebookutils.lakehouse poskytuje pomôcky prispôsobené pre správu položiek Lakehouse. Tieto pomôcky vám umožňujú vytvárať, získavať, aktualizovať a odstraňovať artefakty služby Lakehouse bez námahy.

Prehľad metód

Tu je prehľad dostupných metód poskytovaných notebookutils.lakehouse:

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

# Create Lakehouse with Schema Support
create(name: String, description: String = "", definition: {"enableSchemas": True}): 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]

Príklady použitia

Ak chcete efektívne využiť tieto metódy, zvážte nasledujúce príklady používania:

Vytvorenie služby Lakehouse

artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", "optional_workspace_id")
# Create Lakehouse with Schema Support
artifact = notebookutils.lakehouse.create("artifact_name", "Description of the artifact", {"enableSchemas": True})

Získanie Lakehouse

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

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

Aktualizácia služby Lakehouse

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

Odstránenie jazera

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

Uvedenie domov lakehouse v pracovnom priestore

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

Uvedenie všetkých tabuliek v Lakehouse

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

Spustenie operácie načítania tabuľky v službe 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")

Doplňujúce informácie

Podrobné informácie o každej metóde a jej parametroch získate v téme o funkcii notebookutils.lakehouse.help("methodName") .

Runtime utility

Zobrazenie kontextovej informácie relácie

Vďaka notebookutils.runtime.context službe môžete získať kontextové informácie o aktuálnej živej relácii vrátane názvu poznámkového bloku, predvoleného prostredia jazera, informácií o pracovnom priestore, spustenia kanála atď.

notebookutils.runtime.context

V nasledujúcej tabuľke sú uvedené vlastnosti.

Parameter	Explanation
`currentNotebookName`	Názov aktuálneho poznámkového bloku
`currentNotebookId`	Jedinečné ID aktuálneho poznámkového bloku
`currentWorkspaceName`	Názov aktuálneho pracovného priestoru
`currentWorkspaceId`	ID aktuálneho pracovného priestoru
`defaultLakehouseName`	Zobrazovaný názov predvoleného jazera, ak je definovaný
`defaultLakehouseId`	ID predvoleného jazera, ak je definovaný
`defaultLakehouseWorkspaceName`	Názov pracovného priestoru predvoleného jazera, ak je definovaný
`defaultLakehouseWorkspaceId`	ID pracovného priestoru predvoleného jazera, ak je definované
`currentRunId`	Pri spustení odkazu sa aktuálne ID spustenia
`parentRunId`	V referenčnom spustení s vnorenými spusteniami je toto ID ID nadradeného spustenia
`rootRunId`	V referenčnom spustení s vnorenými spusteniami je toto ID ID koreňového spustenia
`isForPipeline`	Určuje, či je spustenie pre kanál
`isReferenceRun`	Či je aktuálne spustenie odkazové spustenie
`referenceTreePath`	Stromová štruktúra vnorených odkazov sa spustí a používa sa len pre hierarchiu snímok na strane monitorovania L2.
`rootNotebookId`	(Iba v referenčnom spustení) ID koreňového poznámkového bloku v rámci spustenia odkazov.
`rootNotebookName`	(Iba v referenčnom spustení) Názov koreňového poznámkového bloku v spustení odkazov.
`rootWorkspaceId`	(Iba v referenčnom spustení) ID pracovného priestoru koreňového poznámkového bloku v rámci spustenia odkazov.
`rootWorkspaceName`	(Iba v referenčnom spustení) Názov pracovného priestoru koreňového poznámkového bloku v spustení odkazov.
`activityId`	ID úlohy Livy pre aktuálnu aktivitu
`hcRepId`	ID REPL v režime vysokej súbežnosti
`clusterId`	Identita klastra Synapse Spark
`poolName`	Názov použitého fondu Spark
`environmentId`	ID prostredia, v ktorom je úloha spustená
`environmentWorkspaceId`	ID pracovného priestoru prostredia
`userId`	ID používateľa aktuálneho používateľa
`userName`	Meno používateľa aktuálneho používateľa

Správa relácií

Zastavenie interaktívnej relácie

Namiesto manuálneho kliknutia na tlačidlo zastaviť niekedy je pohodlnejšie zastaviť interaktívnu reláciu volaním rozhrania API v kóde. V takýchto prípadoch poskytujeme notebookutils.session.stop() rozhrania API na podporu zastavenia interaktívnej relácie prostredníctvom kódu, ktorý je k dispozícii pre Scala a PySpark.

notebookutils.session.stop()

notebookutils.session.stop() rozhranie API zastaví aktuálnu interaktívnu reláciu asynchrónne na pozadí. Zastaví sa tiež relácia Spark a zdroje na uvoľnenie obsadené reláciou, takže sú k dispozícii pre ostatné relácie v tom istom fonde.

Reštartovanie interpreta jazyka Python

notebookutils.session nástroj poskytuje spôsob, ako reštartovať tlmočníka jazyka Python.

notebookutils.session.restartPython()

Úvahy:

V prípade spustenia odkazu na poznámkový blok restartPython() iba reštartuje tlmočníka jazyka Python aktuálneho poznámkového bloku, na ktorý sa odkazuje.
V zriedkavých prípadoch príkaz môže zlyhať z dôvodu mechanizmu reflexie služby Spark a pridanie opätovného pokusu môže problém zmierniť.

Pomôcky pre premennú knižnicu

Note

Pomôcky pre premennú knižnice v poznámkových blokoch sú v režime ukážky.

Knižnice premenných vám umožňujú vyhnúť sa hodnotám pevného kódovania v kóde poznámkového bloku. Namiesto úpravy kódu môžete aktualizovať hodnoty v knižnici. Poznámkový blok odkazuje na knižnicu premenných na načítanie týchto hodnôt. Tento prístup zjednodušuje opätovné použitie kódu v tímoch a projektoch s využitím centrálne spravovanej knižnice.

Spustite nasledujúce príkazy a získajte prehľad dostupných metód:

notebookutils.variableLibrary.help()

Output

[Preview] notebookutils.variableLibrary is a utility to Variable Library.

Below is overview about the available methods:

get(variableReference: String): String
-> Run the variable value with type.
getLibrary(variableLibraryName: String): VariableLibrary
-> Get the variable library.
Use notebookutils.variableLibrary.help("methodName") for more info about a method.

Definovanie premennej v knižnici premenných

Pred použitím notebookutils.variableLibraryfunkcie definujte premenné najskôr .

Načítanie knižnice premenných z poznámkového bloku

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

val samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

samplevl <- notebookutils.variableLibrary.getLibrary("sampleVL")

samplevl.test_int
samplevl.test_str

Príklad dynamického používania premennej.

samplevl = notebookutils.variableLibrary.getLibrary("sampleVL")

file_path = f"abfss://{samplevl.Workspace_name}@onelake.dfs.fabric.microsoft.com/{samplevl.Lakehouse_name}.Lakehouse/Files/<FileName>.csv" 
df = spark.read.format("csv").option("header","true").load(file_path) 

display(df)

Prístup k jednej premennej pomocou odkazu

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

notebookutils.variableLibrary.get("$(/**/samplevl/test_int)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_str)")
notebookutils.variableLibrary.get("$(/**/samplevl/test_bool)")

Note

Rozhranie notebookutils.variableLibrary API podporuje iba prístup k knižniciam premenných v rámci toho istého pracovného priestoru.
Načítanie knižníc premenných v pracovných priestoroch nie je v podradených poznámkových blokoch podporované počas spustenia odkazu.
Kód poznámkového bloku odkazuje na premenné definované v množine aktívnych hodnôt knižnice premenných.

Známe problémy

Pri použití runtime verzie nad 1.2 a run notebookutils.help(), uvedený fabricClient, PBIClient API zatiaľ nie sú podporované, bude k dispozícii v ďalšom. Okrem toho rozhranie API poverení zatiaľ nie je podporované v poznámkových blokoch Scala.
Poznámkový blok jazyka Python nepodporuje rozhrania API stop, restartPython pri použití pomôcky notebookutils.session na správu relácií.
V súčasnosti nie je SPN podporované pre pomôcky knižnice s premenlivými technológiami.

Spätná väzba

Bola táto stránka užitočná?

Last updated on 2025-08-16

Zdieľať cez

NotebookUtils (bývalý MSSparkUtils) pre Fabric

Pomôcky systému súborov

Zoznam súborov

Zobrazenie vlastností súboru

Vytvorenie nového adresára

Kopírovať súbor

Výkonný kopírovací súbor

Zobraziť ukážku obsahu súboru

Presunúť súbor

Napísať súbor

Pripojenie obsahu k súboru

Odstránenie súboru alebo adresára

Pripojiť/odpojiť adresár

Pomôcky pre notebooky

Odkaz na poznámkový blok

Odkaz na paralelné spustenie viacerých poznámkových blokov

Ukončenie poznámkového bloku

Spravovanie poznámkových blokov artefaktov

Vytvorenie poznámkového bloku

Získanie obsahu poznámkového bloku

Aktualizácia poznámkového bloku

Odstránenie poznámkového bloku

Zápisníky v pracovnom priestore

Pomôcky funkcie User Data Function (UDF)

Načítanie funkcií z jazyka UDF

Vyvolanie funkcie

Zobrazenie podrobností pre položku UDF

Zobrazenie podrobností o funkciách pre UDF

Poverenia pomôcky

Získať token

Získanie tajnosti

Pripojenie a zrušenie pripojenia k súboru

Ako pripojiť konto služby ADLS Gen2

Pripojenie prostredníctvom tokenu podpisu zdieľaného prístupu alebo kľúča konta

Ako pripojiť lakehouse

Prístup k súborom v bode pripojenia pomocou rozhrania Notebookutils fs API

Prístup k súborom pod bodom pripojenia cez lokálnu cestu

Kontrola existujúcich bodov pripojenia

Ako zrušiť pripojenie bodu pripojenia

Známe obmedzenia

Inžinierske siete pri jazere

Prehľad metód

Príklady použitia

Vytvorenie služby Lakehouse

Získanie Lakehouse

Aktualizácia služby Lakehouse

Odstránenie jazera

Uvedenie domov lakehouse v pracovnom priestore

Uvedenie všetkých tabuliek v Lakehouse

Spustenie operácie načítania tabuľky v službe Lakehouse

Doplňujúce informácie

Runtime utility

Zobrazenie kontextovej informácie relácie

Správa relácií

Zastavenie interaktívnej relácie

Reštartovanie interpreta jazyka Python

Pomôcky pre premennú knižnicu

Definovanie premennej v knižnici premenných

Načítanie knižnice premenných z poznámkového bloku

Prístup k jednej premennej pomocou odkazu

Známe problémy

Súvisiaci obsah

Spätná väzba

Ďalšie zdroje