Muistiinpano
Tälle sivulle pääsy edellyttää valtuutusta. Voit yrittää kirjautua sisään tai vaihtaa hakemistoja.
Tälle sivulle pääsy edellyttää valtuutusta. Voit yrittää vaihtaa hakemistoja.
Notebook Utilities (NotebookUtils) on sisäinen paketti, jonka avulla voit helposti suorittaa yleisiä tehtäviä Fabric Notebookissa. NotebookUtils-apuohjelman avulla voit käsitellä tiedostojärjestelmiä, saada ympäristömuuttujia, ketjuttaa muistikirjoja yhteen ja käsitellä salaisuuksia. NotebookUtils-paketti on saatavilla PySpark (Python) Scala-, SparkR-muistikirjoissa ja Fabric-putkissa.
Note
- MsSparkUtils on virallisesti nimetty uudelleen NotebookUtilsiksi. Olemassa oleva koodi pysyy taaksepäin yhteensopivana eikä aiheuta rikkovia muutoksia. On erittäin suositeltavaa päivittää notebookutils-versioon, jotta varmistetaan jatkuva tuki ja uusien ominaisuuksien käyttö. Mssparkutils-nimitila poistetaan käytöstä tulevaisuudessa.
- NotebookUtils on suunniteltu toimimaan spark 3.4(Runtime v1.2) ja sitä uudemmat versiot. Kaikkia uusia ominaisuuksia ja päivityksiä tuetaan vain niin, että notebookutils-nimitila jatkuu eteenpäin.
Tiedostojärjestelmäapuohjelmat
notebookutils.fs tarjoaa apuohjelmia eri tiedostojärjestelmien, kuten Azure Data Lake Storage (ADLS) Gen2:n ja Azure Blob Storagen, käsittelyyn. Varmista, että määrität Azure Data Lake Storage Gen2: n ja Azure Blob -säilön käyttöoikeudet asianmukaisesti.
Suorita seuraavat komennot, jotta saat yleiskatsauksen käytettävissä olevista menetelmistä:
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.
NotebookUtils toimii tiedostojärjestelmän kanssa samalla tavalla kuin Spark-ohjelmointirajapinnat. Otetaan esimerkiksi notebookutils.fs.mkdirs() ja Fabric lakehouse -käyttö:
| Usage | Suhteellinen polku HDFS-pääkansiosta | ABFS-tiedostojärjestelmän absoluuttinen polku | Paikallisen tiedostojärjestelmän absoluuttinen polku ohjainsolmussa |
|---|---|---|---|
| Ei-maksukyvytön lakehouse | Ei tueta | notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>") | notebookutils.fs.mkdirs("tiedosto:/<new_dir")> |
| Oletusarvoinen lakehouse | Hakemisto kohdassa 'Tiedostot' tai 'Taulukot': notebookutils.fs.mkdirs("Files/<new_dir>") | notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>") | notebookutils.fs.mkdirs("tiedosto:/<new_dir")> |
Lakehouse-oletustiedoston tiedostopolut on asennettu muistikirjaan, ja oletustiedoston välimuistin aikakatkaisu on 120 sekuntia. Tämä tarkoittaa sitä, että tiedostot tallennetaan muistikirjan paikalliseen väliaikaiseen kansioon 120 sekunnin ajan, vaikka ne olisi poistettu Lakehousesta. Jos haluat muuttaa aikakatkaisusääntöä, voit poistaa oletusarvoiset Lakehouse-tiedostopolut ja liittää ne uudelleen eri fileCacheTimeout-arvolla .
Muille kuin oletusarvoisille Lakehouse-määrityksille voit määrittää sopivan fileCacheTimeout-parametrin Lakehouse-polkujen liittämisen aikana. Aikakatkaisun asettaminen arvoon 0 varmistaa, että uusin tiedosto noudetaan Lakehouse-palvelimesta.
Luettelo tiedostoista
Voit luetella hakemiston sisällön notebookutils.fs.ls('Hakemistopolkusi'). Esimerkiksi:
notebookutils.fs.ls("Files/tmp") # The relatvie path may work with different base path, details in below
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>") # The absolute path, like: ABFS file system
notebookutils.fs.ls("file:/tmp") # The full path of the local file system of driver node
notebookutils.fs.ls()-ohjelmointirajapinta toimii eri tavalla käytettäessä suhteellista polkua muistikirjatyypin mukaan.
Spark-muistikirjassa: Suhteellinen polku on suhteessa oletusarvoisen Lakehousen ABFSS-polkuun.
notebookutils.fs.ls("Files")esimerkiksi osoittaa oletusasetusten LakehousenFiles-hakemistoon.Esimerkiksi:
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")Python-muistikirja-: Suhteellinen polku on suhteessa paikallisen tiedostojärjestelmän työhakemistoon, joka on oletusarvoisesti /home/trusted-service-user/work. Siksi sinun tulee käyttää koko polkua suhteellisen polun sijaan,
notebookutils.fs.ls("/lakehouse/default/Files")käyttääksesi oletusarvoisen LakehousenFiles-hakemistoa.Esimerkiksi:
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
Näytä tiedoston ominaisuudet
Tämä menetelmä palauttaa tiedoston ominaisuudet, kuten tiedoston nimen, tiedostopolun, tiedostokoon ja sen, onko kyseessä hakemisto ja tiedosto.
files = notebookutils.fs.ls('Your directory path')
for file in files:
print(file.name, file.isDir, file.isFile, file.path, file.size)
Luo uusi hakemisto
Tämä menetelmä luo annetun hakemiston, jos sitä ei ole, ja luo tarvittavat päähakemistot.
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
Kopioi tiedosto
Tämä menetelmä kopioi tiedoston tai hakemiston ja tukee kopiointitoimintoja tiedostojärjestelmien välillä. Määritämme recurse=True kopioimaan kaikki tiedostot ja hakemistot rekursiivisesti.
notebookutils.fs.cp('source file or directory', 'destination file or directory', recurse=True)
Note
OneLake-pikakuvakkeen rajoitusten vuoksi, kun sinun on käytettävä notebookutils.fs.cp() tietojen kopioimiseen S3/GCS-tyypin pikakuvakkeesta, on suositeltavaa käyttää määritettyä polkua abfs-polun sijaan.
Suorita kopiotiedosto
Tämä menetelmä tarjoaa tehokkaamman lähestymistavan tiedostojen kopioimiseen tai siirtämiseen etenkin suuria tietomääriä käsiteltäessä. Fabric-suorituskyvyn parantamiseksi on suositeltavaa käyttää fastcp perinteisen cp menetelmän korvikkeena.
notebookutils.fs.fastcp('source file or directory', 'destination file or directory', recurse=True)
Näkökohdat:
-
notebookutils.fs.fastcp()ei tue tiedostojen kopioimista OneLakessa alueiden välillä. Tässä tapauksessa voit käyttää -toimintoanotebookutils.fs.cp()sen sijaan. - OneLake-pikakuvakkeen rajoitusten vuoksi, kun sinun on käytettävä
notebookutils.fs.fastcp()tietojen kopioimiseen S3/GCS-tyypin pikakuvakkeesta, on suositeltavaa käyttää määritettyä polkua abfs-polun sijaan.
Esikatselutiedoston sisältö
Tämä menetelmä palauttaa enintään annetun tiedoston ensimmäiset maxBytes-tavut merkkijonona, joka on KOODattu UTF-8:ssa.
notebookutils.fs.head('file path', maxBytes to read)
Siirrä tiedosto
Tämä menetelmä siirtää tiedoston tai hakemiston ja tukee siirtoja tiedostojärjestelmien välillä.
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.
Kirjoita tiedosto
Tämä menetelmä kirjoittaa annetun merkkijonon tiedostoon, joka on UTF-8-koodattu.
notebookutils.fs.put("file path", "content to write", True) # Set the last parameter as True to overwrite the file if it existed already
Sisällön liilisääminen tiedostoon
Tämä menetelmä liittää annetun merkkijonon tiedostoon, joka on UTF-8-koodattu.
notebookutils.fs.append("file path", "content to append", True) # Set the last parameter as True to create the file if it does not exist
Näkökohdat:
-
notebookutils.fs.append()janotebookutils.fs.put()älä tue samanaikaista kirjoittamista samaan tiedostoon, koska atomiteettitakuita ei ole. - Kun käytät
notebookutils.fs.append-ohjelmointirajapintaafor-silmukassa samaan tiedostoon kirjoittamiseksi, suosittelemme lisäämään toistuvien kirjoitusten välillesleep-lausekkeen, joka on noin 0,5~1. Tämä suositus johtuu siitä, ettänotebookutils.fs.append-ohjelmointirajapinnan sisäinenflush-toiminto on asynkroninen, joten lyhyt viive auttaa varmistamaan tietojen eheyden.
Poista tiedosto tai hakemisto
Tämä menetelmä poistaa tiedoston tai hakemiston. Määritimme recurse=True poistamaan kaikki tiedostot ja hakemistot rekursiivisesti.
notebookutils.fs.rm('file path', recurse=True)
Hakemiston liittäminen/irrottaminen
Katso lisätietoja yksityiskohtaisesta käytöstä kohdassa Tiedoston käyttöönotto ja määrän poistaminen.
Kannettavan tietokoneen apuohjelmat
Muistikirja-apuohjelman avulla voit suorittaa muistikirjan tai poistua muistikirjasta, jossa on arvo. Saat yleiskatsauksen käytettävissä olevista menetelmistä suorittamalla seuraavan komennon:
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
Muistikirja-apuohjelmat eivät koske Apache Spark -työmääritelmiä (SJD).
Viittaa muistikirjaan
Tämä menetelmä viittaa muistikirjaan ja palauttaa sen poistumisarvon. Voit suorittaa sisäkkäiset funktiokutsut muistikirjassa vuorovaikutteisesti tai jaksossa. Viitattava muistikirja kulkee muistikirjan Spark-altaassa, joka kutsuu tätä funktiota.
notebookutils.notebook.run("notebook name", <timeoutSeconds>, <parameterMap>, <workspaceId>)
Esimerkiksi:
notebookutils.notebook.run("Sample1", 90, {"input": 20 })
Kangasmuistikirja tukee myös muistikirjoihin viittaamista useissa työtiloissa määrittämällä työtilan tunnuksen.
notebookutils.notebook.run("Sample1", 90, {"input": 20 }, "fe0a6e2a-a909-4aa3-a698-0a651de790aa")
Voit avata viitesuorituksen tilannevedoslinkin solun tulostessa. Tilannevedos tallentaa koodin suoritustulokset ja mahdollistaa viitesuorituksen virheenkorjauksen helpon virheenkorjauksen.
Näkökohdat:
- Työtilojen välistä viitemuistikirjaa tuetaan suorituksenaikaisessa versiossa 1.2 ja sitä uudemmat.
- Jos käytät Muistikirjan resurssi -kohdan tiedostoja, varmista
notebookutils.nbResPathviitatussa muistikirjassa, että se osoittaa samaan kansioon kuin vuorovaikutteinen suoritus. - Viitesuoritus sallii alimuistikirjojen suorittamisen vain, jos ne käyttävät samaa lakehousea kuin ylätaso, perivät pääluettelon lakehousen tai kumpikaan ei määritä sellaista. Suoritus estetään, jos alitaso määrittää päämuistikirjalle eri lakehousen. Voit ohittaa tämän tarkistuksen asettamalla
useRootDefaultLakehouse: True.
Viiteajo useita muistikirjoja rinnakkain
-menetelmän notebookutils.notebook.runMultiple() avulla voit suorittaa useita muistikirjoja rinnakkain tai ennalta määritetyn topologisen rakenteen kanssa. Ohjelmointirajapinta käyttää monisäikeistä toteutusmekanismia spark-istunnon sisällä, mikä tarkoittaa, että viitemuistikirja suoritetaan jaa käsittelyresurssit.
:n avulla notebookutils.notebook.runMultiple()voit:
Suorita useita muistikirjoja samanaikaisesti odottamatta jokaisen päättymistä.
Määritä muistikirjojen riippuvuudet ja suoritusjärjestys käyttämällä yksinkertaista JSON-muotoa.
Optimoi Spark-käsittelyresurssien käyttö ja pienennä Fabric-projektiesi kustannuksia.
Tarkastele kunkin muistikirjan suoritustietueen tilannevedoksia tulosteessa ja korjaa muistikirjatehtäväsi virheenkorjaus/valvonta helposti.
Nouda kunkin johtajatoiminnon exit-arvo ja käytä niitä jatkotehtävissä.
Voit myös yrittää suorittaa notebookutils.notebook.help("runMultiple") löytääksesi esimerkin ja yksityiskohtaisen käytön.
Tässä on yksinkertainen esimerkki muistikirjojen luettelon suorittamisesta rinnakkain tällä menetelmällä:
notebookutils.notebook.runMultiple(["NotebookSimple", "NotebookSimple2"])
Päämuistikirjasta saatu suoritustulos on seuraava:
Tässä on esimerkki käynnissä olevista muistikirjoista, joissa on topologinen rakenne, käyttämällä notebookutils.notebook.runMultiple(). Tämän menetelmän avulla voit helposti järjestää muistikirjat koodikokemuksen kautta.
# 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})
Päämuistikirjasta saatu suoritustulos on seuraava:
Tarjoamme myös menetelmän, jolla tarkistetaan, onko DAG määritetty oikein.
notebookutils.notebook.validateDAG(DAG)
Näkökohdat:
- Useiden muistikirjojen suoritusten rinnakkaisuusaste on rajoitettu Spark-istunnon käytettävissä olevaan käsittelyresurssiin.
- Samanaikaisten muistikirjojen oletusmäärä on 50 Spark-muistikirjassa, kun taas Python-muistikirjassa se on oletusarvoisesti 25 . Voit mukauttaa tätä arvoa, mutta liiallinen rinnakkaisuus voi johtaa vakaus- ja suorituskykyongelmiin laskentaresurssien suuren käytön vuoksi. Jos ongelmia ilmenee, harkitse muistikirjojen erottamista useisiin
runMultiplekutsuihin tai samanaikaisuuden vähentämistä säätämällä DAG-parametrin samanaikaisuuskenttää . - Koko DAG:n oletusaikakatkaisu on 12 tuntia, ja alimuistikirjassa olevan solun oletusaikakatkaisuarvo on 90 sekuntia. Voit muuttaa aikakatkaisua määrittämällä DAG-parametrin timeoutInSeconds - ja timeoutPerCellInSeconds-kentät .
Poistu muistikirjasta
Tämä menetelmä sulkee muistikirjasta arvon. Voit suorittaa sisäkkäiset funktiokutsut muistikirjassa vuorovaikutteisesti tai jaksossa.
Kun kutsut exit() -funktiota muistikirjasta vuorovaikutteisesti, Fabric-muistikirja antaa poikkeuksen, ohittaa seuraavien solujen suorittamisen ja pitää Spark-istunnon elossa.
Kun orkestroit muistikirjaa putkessa, joka kutsuu exit()-funktiota, muistikirja-aktiviteetti palaa poistumisarvolla. Tämä viimeistelee putken suorittamisen ja pysäyttää Spark-istunnon.
Kun kutsut exit() -funktiota muistikirjassa, johon viitataan, Fabric Spark pysäyttää viitatun muistikirjan suorittamisen ja jatkaa run () -funktiota kutsuvan päämuistikirjan seuraavien solujen suorittamista. Esimerkki: Muistikirja1:ssä on kolme solua, ja se kutsuu exit() -funktiota toisessa solussa. Notebook2:ssa on viisi solua, ja kolmannessa solussa on kutsu run(notebook1). Kun suoritat Notebook2:n, Notebook1 pysähtyy toiseen soluun, kun painat exit() -funktiota. Notebook2 jatkaa neljännen solunsa ja viidennen solunsa pyörimistä.
notebookutils.notebook.exit("value string")
Note
Exit () -funktio korvaa nykyisen solulähdön. Jos haluat välttää muiden koodilausekkeiden tuloksen menettämisen, kutsu notebookutils.notebook.exit() erilliseen soluun.
Esimerkiksi:
Sample1-muistikirja , jossa on seuraavat kaksi solua:
Solu 1 määrittää syöttöparametrin , jonka oletusarvoksi on asetettu 10.
Solu 2 poistuu muistikirjasta, jonka lähtöarvona on syöte.
Voit suorittaa Sample1:n toisessa muistikirjassa oletusarvoilla:
exitVal = notebookutils.notebook.run("Sample1")
print (exitVal)
Output:
Notebook is executed successfully with exit value 10
Voit suorittaa Sample1:n toisessa muistikirjassa ja määrittää syötearvoksi 20:
exitVal = notebookutils.notebook.run("Sample1", 90, {"input": 20 })
print (exitVal)
Output:
Notebook is executed successfully with exit value 20
Hallitse muistikirjan artefakteja
notebookutils.notebook tarjoaa erityisapuohjelmia muistikirjakohteiden ohjelmallisesti hallintaan. Näiden ohjelmointirajapintojen avulla voit helposti luoda, hankkia, päivittää ja poistaa muistikirjakohteita.
Jos haluat hyödyntää näitä menetelmiä tehokkaasti, katso seuraavia käyttöesimerkkejä:
Muistikirjan luominen
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")
Muistikirjan sisällön hakeminen
artifact = notebookutils.notebook.get("artifact_name", "optional_workspace_id")
Muistikirjan päivittäminen
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")
Muistikirjan poistaminen
is_deleted = notebookutils.notebook.delete("artifact_name", "optional_workspace_id")
Luetteloi muistikirjat työtilassa
artifacts_list = notebookutils.notebook.list("optional_workspace_id")
User Data Function (UDF) -apuohjelmat
notebookutils.udf tarjoaa apuohjelmat, jotka on suunniteltu muistikirjakoodin integroimiseen käyttäjätietofunktioihin (UDF). Näiden apuohjelmien avulla voit käyttää funktioita UDF-kohteelta samassa työtilassa tai eri työtiloissa. Voit sen jälkeen käynnistää funktioita UDF-kohteessa tarpeen mukaan.
Seuraavassa on esimerkkejä UDF-apuohjelmien käytöstä:
# 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')
Funktioiden noutaminen UDF:stä
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")
Funktion kutsuminen
myFunctions.functionName('value1', 'value2'...)
val res = myFunctions.functionName('value1', 'value2'...)
myFunctions$functionName('value1', 'value2'...)
Näytä UDF-kohteen tiedot
display([myFunctions.itemDetails])
display(Array(myFunctions.itemDetails))
myFunctions$itemDetails()
UDF:n funktion tietojen näyttäminen
display(myFunctions.functionDetails)
display(myFunctions.functionDetails)
myFunctions$functionDetails()
Tunnistetietojen apuohjelmat
Voit käyttää tunnistetietoja apuohjelmia käyttöoikeustietueiden hankkimiseen ja salaisten koodien hallintaan Azure Key Vaultissa.
Saat yleiskatsauksen käytettävissä olevista menetelmistä suorittamalla seuraavan komennon:
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
Hanki tunnus
getToken palauttaa Microsoft Entra -tunnuksen annetulle kohderyhmälle ja nimelle (valinnainen). Seuraavassa luettelossa näytetään käytettävissä olevat yleisöavaimet:
- Tallennusryhmän resurssi: "tallennustila"
- Power BI -resurssi: "pbi"
- Azure Key Vault -resurssi: "keyvault"
- Synapse RTA KQL DB -resurssi: "kusto"
Saat tunnuksen suorittamalla seuraavan komennon:
notebookutils.credentials.getToken('audience Key')
Näkökohdat:
Token-laajuudet, joissa on "pbi" yleisönä, voivat muuttua ajan myötä. Seuraavia vaikutusalueita tuetaan tällä hetkellä.
Kun kutsut notebookutils.credentials.getToken("pbi"), palautetulla tunnuksella on rajoitettu vaikutusalue, jos muistikirja suoritetaan palvelun päänimen alla. Tunnuksella ei ole täyttä Fabric-palvelun vaikutusaluetta. Jos muistikirja suoritetaan käyttäjätiedoissa, tunnuksella on edelleen koko Fabric-palvelun vaikutusalue, mutta tämä voi muuttua suojausparannusten myötä. Jos haluat varmistaa, että tunnuksella on täysi Fabric-palvelun vaikutusalue, käytä MSAL-todennusta notebookutils.credentials.getToken ohjelmointirajapinnan sijaan. Lisätietoja on artikkelissa Todentaminen Microsoft Entra ID:llä.
Seuraavassa on luettelo vaikutusalueista, jotka tunnuksella on, kun notebookutils.credentials.getToken kutsutaan käyttöryhmäavaimella pbi palvelun päänimen käyttäjätietojen alla:
- Lakehouse.ReadWrite.All
- MLExperiment.ReadWrite.All
- MLModel.ReadWrite.All
- Notebook.ReadWrite.All
- SparkJobDefinition.ReadWrite.All
- Workspace.ReadWrite.All
- Dataset.ReadWrite.All
Hanki salaisuus
getSecret palauttaa Azure Key Vaultin salaisen koodin annetulle Azure Key Vaultin päätepisteelle ja salaiselle nimelle käyttäjän tunnistetietojen avulla.
notebookutils.credentials.getSecret('https://<name>.vault.azure.net/', 'secret name')
Tiedostokiinnitys ja -mittarin irrottaminen
Fabric tukee seuraavia Microsoft Spark Utilities -paketin käyttöönottoskenaarioita. Voit käyttää mount-, unmount-, getMountPath()- ja mounts()- ohjelmointirajapintoja etätallennustilan (ADLS Gen2) liittämiseen kaikkiin toimiviin solmuihin (ohjainsolmu ja työsolmu). Kun tallennustilan käyttöönottopiste on paikallaan, käytä paikallista tiedoston ohjelmointirajapintaa tietojen käyttämiseen ikään kuin ne olisi tallennettu paikalliseen tiedostojärjestelmään.
ADLS Gen2 -tilin lisääminen käyttöön
Seuraavassa esimerkissä havainnollistetaan, miten Azure Data Lake Storage Gen2 voidaan ottaa käyttöön. Blob Storagen ja Azure File Share:n asentaminen toimii samalla tavalla.
Tässä esimerkissä oletetaan, että sinulla on yksi Data Lake Storage Gen2 -tili nimeltä storegen2, jossa on mycontainer-niminen säilö, jonka haluat liittää /test-tiedostoon muistikirjan Spark-istunnossa.
Mycontainer-nimisen säilön liittämiseksi notebookutilsin on ensin tarkistettava, onko sinulla oikeus käyttää säilöä. Tällä hetkellä Fabric tukee kahta todennusmenetelmää liipaisimen liittämistoiminnolle: accountKey ja sastoken.
Käyttöönotto jaetun käytön allekirjoitustunnuksen tai tiliavaimen avulla
NotebookUtils tukee nimenomaisesti tilin avaimen tai SAS-tunnuksen välittämistä parametrina kohteen ottamiseksi käyttöön.
Suojaussyistä suosittelemme, että tallennat tiliavaimet tai SAS-tunnukset Azure Key Vaultiin (kuten seuraavassa näyttökuvassa näkyy). Voit sitten noutaa ne notebookutils.credentials.getSecret-ohjelmointirajapinnan avulla. Lisätietoja Azure Key Vaultista on artikkelissa Tietoja Azure Key Vaultin hallitun tallennustilin avaimista.
Esimerkkikoodi accountKey-menetelmälle :
# 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}
)
Esimerkkikoodi sastokenille:
# 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}
)
Asenna parametrit:
- fileCacheTimeout: Blob-objektit tallennetaan oletusarvoisesti paikallisen tilapäiskansion välimuistiin 120 sekunnin ajaksi. Tänä aikana blobfuse ei tarkista, onko tiedosto ajan tasalla. Parametri voidaan määrittää muuttamaan oletusarvoista aikakatkaisuaikaa. Kun useat asiakasohjelmat muokkaavat tiedostoja samanaikaisesti, paikallisten ja etätiedostojen välisten epäjohdonmukaisuuksien välttämiseksi suosittelemme, että lyhennät välimuistin aikaa tai jopa muutat sen arvoon 0 ja haet aina uusimmat tiedostot palvelimelta.
- timeout: Käyttöönoton aikakatkaisu on oletusarvoisesti 120 sekuntia. Parametri voidaan määrittää muuttamaan oletusarvoista aikakatkaisuaikaa. Jos suoritettavia tiedostoja on liikaa tai kun ne otetaan käyttöön aikakatkaistaan, on suositeltavaa suurentaa arvoa.
Voit käyttää näitä parametreja seuraavasti:
notebookutils.fs.mount(
"abfss://mycontainer@<accountname>.dfs.core.windows.net",
"/test",
{"fileCacheTimeout": 120, "timeout": 120}
)
Note
Suojaussyistä on suositeltavaa välttää tunnistetietojen upottamista suoraan koodiin. Jotta tunnistetietojasi voidaan suojata edelleen, muistikirjojen tulosteissa näkyvät salaisuudet poistetaan. Lisätietoja on kohdassa Salainen hävitys.
Kuinka ottaa lakehouse käyttöön
Näytekoodi Lakehousen luomiseksi /<mount_name>:
notebookutils.fs.mount(
"abfss://<workspace_name>@onelake.dfs.fabric.microsoft.com/<lakehouse_name>.Lakehouse",
"/<mount_name>"
)
Käytä liityntäkohdan alla olevia tiedostoja notebookutils fs -ohjelmointirajapinnan avulla
Käyttöönottotoiminnon päätarkoitus on antaa asiakkaiden käyttää etätallennustilille tallennettuja tietoja paikallisen tiedostojärjestelmän ohjelmointirajapinnalla. Voit käyttää tietoja myös käyttämällä notebookutils fs -ohjelmointirajapintaa, jonka parametrina on asennettu polku. Tämä polkumuoto on hieman erilainen.
Oletetaan, että olet asentanut Data Lake Storage Gen2 -säilön mycontainerkohteeseen /test käyttämällä asennusohjelmointirajapintaa. Kun käytät paikallisen tiedostojärjestelmän ohjelmointirajapinnan tietoja, polkumuoto on seuraavanlainen:
/synfs/notebook/{sessionId}/test/{filename}
Kun haluat käyttää tietoja notebookutils fs -ohjelmointirajapinnan avulla, suosittelemme käyttämään getMountPath()- toimintoa tarkan polun saamiseksi:
path = notebookutils.fs.getMountPath("/test")
Luettelohakemistot:
notebookutils.fs.ls(f"file://{notebookutils.fs.getMountPath('/test')}")Lue tiedoston sisältöä:
notebookutils.fs.head(f"file://{notebookutils.fs.getMountPath('/test')}/myFile.txt")Luo hakemisto:
notebookutils.fs.mkdirs(f"file://{notebookutils.fs.getMountPath('/test')}/newdir")
Käyttötiedostot käyttöönottopisteen alla paikallisen polun kautta
Voit helposti lukea ja kirjoittaa tiedostot käyttöönottopisteessä käyttämällä vakiotiedostojärjestelmää. Tässä on esimerkki Pythonista:
#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"))
Aiemmin luotujen käyttöönottopisteiden tarkistaminen
Voit käyttää notebookutils.fs.mounts()- ohjelmointirajapintaa tarkistaaksesi kaikki olemassa olevat liitospisteen tiedot:
notebookutils.fs.mounts()
Miten voit poistaa kiinnikkeen vuoren yltä
Käytä seuraavaa koodia irrottaaksesi liitoskohdan (/test tässä esimerkissä):
notebookutils.fs.unmount("/test")
Tunnetut rajoitukset
Nykyinen asennus on työtason kokoonpano; Suosittelemme, että käytät asennusten ohjelmointirajapintaa tarkistaaksesi, onko liityntäkohta olemassa vai ei.
Poista summa -mekanismia ei käytetä automaattisesti. Kun sovelluksen suorittaminen on valmis, jotta voit poistaa kiinnityskohdan ja vapauttaa levytilan, sinun on eksplisiittisesti kutsuttava koodin määrittämätöntä ohjelmointirajapintaa. Muussa tapauksessa käyttöönottopiste on solmussa sen jälkeen, kun sovelluksen suorittaminen on valmis.
ADLS Gen1 -tallennustilin asentamista ei tueta.
Lakehousen apuohjelmat
notebookutils.lakehouse tarjoaa Lakehouse-tuotteiden hallintaan räätälöityjä apuohjelmia. Näillä apuohjelmilla voit luoda, hankkia, päivittää ja poistaa Lakehouse-artefakteja vaivattomasti.
Menetelmien yleiskatsaus
Tässä on yleiskatsaus notebookutils.lakehousetarjoamista käytettävissä olevista menetelmistä:
# 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]
Esimerkkejä käytöstä
Jos haluat hyödyntää näitä menetelmiä tehokkaasti, katso seuraavia käyttöesimerkkejä:
Lakehousen luominen
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})
Lakehousen hakeminen
artifact = notebookutils.lakehouse.get("artifact_name", "optional_workspace_id")
artifact = notebookutils.lakehouse.getWithProperties("artifact_name", "optional_workspace_id")
Lakehousen päivittäminen
updated_artifact = notebookutils.lakehouse.update("old_name", "new_name", "Updated description", "optional_workspace_id")
Lakehousen poistaminen
is_deleted = notebookutils.lakehouse.delete("artifact_name", "optional_workspace_id")
Lakehouse-talojen listaaminen työtilassa
artifacts_list = notebookutils.lakehouse.list("optional_workspace_id")
Kaikkien Lakehouse-taulukoiden luettelo
artifacts_tables_list = notebookutils.lakehouse.listTables("artifact_name", "optional_workspace_id")
Lataustaulukkotoiminnon aloittaminen Lakehousessa
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")
Lisätietoja
Saat tarkempia tietoja kustakin menetelmästä ja sen parametreista käyttämällä -funktiota notebookutils.lakehouse.help("methodName") .
Ajonaikaiset apuohjelmat
Näytä istunnon kontekstitiedot
Voit notebookutils.runtime.context näin hakea nykyisen live-istunnon kontekstitiedot, kuten muistikirjan nimen, oletusjärvitalon, työtilan tiedot, jos kyseessä on jakson suorittaminen jne.
notebookutils.runtime.context
Seuraavassa taulukossa on esitetty ominaisuudet.
| Parameter | Explanation |
|---|---|
currentNotebookName |
Nykyisen muistikirjan nimi |
currentNotebookId |
Nykyisen muistikirjan yksilöivä tunnus |
currentWorkspaceName |
Nykyisen työtilan nimi |
currentWorkspaceId |
Nykyisen työtilan tunnus |
defaultLakehouseName |
Oletussäilötalon näyttönimi, jos sellainen on määritetty |
defaultLakehouseId |
Oletus lakehouse-kohteen tunnus, jos määritetty |
defaultLakehouseWorkspaceName |
Oletus lakehouse-järjestelmän työtilan nimi, jos sellainen on määritetty |
defaultLakehouseWorkspaceId |
Oletus-Lakehousen työtilatunnus, jos sellainen on määritetty |
currentRunId |
Viittaussuorituksessa nykyinen suoritustunnus |
parentRunId |
Sisäkkäisiä suorituksia sisältävässä viitesuorituksessa tämä tunnus on pääsuorituksen tunnus |
rootRunId |
Sisäkkäisiä suorituksia sisältävässä viitesuorituksessa tämä tunnus on pääsuorituksen tunnus |
isForPipeline |
Onko suoritus tarkoitettu putkelle |
isReferenceRun |
Onko nykyinen suoritus viiteajo |
referenceTreePath |
Sisäkkäisten viittausten suoritusten puurakenne, jota käytetään vain tilannevedoshierarkiassa valvonta-L2-sivulla |
rootNotebookId |
(Vain viitteen suorittamisessa) Juurimuistikirjan tunnus viittaussuorituksessa. |
rootNotebookName |
(Vain viitteen suorittamisessa) Juurimuistikirjan nimi viittaussuorituksessa. |
rootWorkspaceId |
(Vain viitteen suorittamisessa) Juurimuistikirjan työtilan tunnus viittaussuorituksessa. |
rootWorkspaceName |
(Vain viitteen suorittamisessa) Päämuistikirjan työtilan nimi viittaussuorituksessa. |
activityId |
Livy-työtunnus nykyiselle aktiviteetille |
hcRepId |
REPL-tunnus suuren samanaikaisuuden tilassa |
clusterId |
Synapse Spark -klusterin käyttäjätiedot |
poolName |
Käytettävän Spark-varannon nimi |
environmentId |
Ympäristötunnus, jossa työ suoritetaan |
environmentWorkspaceId |
Ympäristön työtilan tunnus |
userId |
Nykyisen käyttäjän käyttäjätunnus |
userName |
Nykyisen käyttäjän käyttäjänimi |
Istunnon hallinta
Vuorovaikutteisen istunnon lopettaminen
Sen sijaan, että napsautat lopeta-painiketta manuaalisesti, on joskus kätevämpää pysäyttää vuorovaikutteinen istunto kutsumalla koodin ohjelmointirajapintaa. Tällaisissa tapauksissa tarjoamme ohjelmointirajapinnan notebookutils.session.stop(), joka tukee vuorovaikutteisen istunnon pysäyttämistä koodilla. Se on saatavilla Scalalle ja PySparkille.
notebookutils.session.stop()
notebookutils.session.stop() ohjelmointirajapinta pysäyttää nykyisen vuorovaikutteisen istunnon asynkronisesti taustalla. Se myös pysäyttää Spark-istunnon ja julkaisee istunnon käyttämät resurssit, joten ne ovat käytettävissä muissa saman varannon istunnoissa.
Käynnistä Python-tulkki uudelleen
notebookutils.session-apuohjelma mahdollistaa Python-tulkin uudelleenkäynnistämisen.
notebookutils.session.restartPython()
Näkökohdat:
- Muistikirjaviittauksen suoritustapauksessa
restartPython()käynnistää uudelleen vain viitatun nykyisen muistikirjan Python-tulkin. - Joissakin harvoissa tapauksissa komento voi epäonnistua Spark-heijastusmekanismin vuoksi, mutta uudelleenyritysten lisääminen voi lieventää ongelmaa.
Muuttujakirjasto-apuohjelmat
Note
Muistikirjat-kohdassa "Muuttujakirjaston apuohjelmat" on esikatseluvaiheessa.
Muuttujakirjastojen avulla voit välttää arvojen koodaamisen muistikirjakoodissasi. Voit päivittää kirjaston arvot koodin muokkaamisen sijaan. Muistikirja viittaa muuttujakirjastoon näiden arvojen noutamiseksi. Tämä lähestymistapa yksinkertaistaa koodin uudelleenkäyttöä tiimeissä ja projekteissa käyttämällä keskitetysti hallittua kirjastoa.
Suorita seuraavat komennot, jotta saat yleiskatsauksen käytettävissä olevista menetelmistä:
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.
Muuttujan määrittäminen muuttujakirjastossa
Määritä muuttujat ensin ennen -kohteen käyttämistä notebookutils.variableLibrary.
Muuttujakirjaston noutaminen muistikirjasta
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
Esimerkki muuttujan dynaamisesta käytöstä.
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)
Käytä yksittäistä muuttujaa viittauksella
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
- -
notebookutils.variableLibraryohjelmointirajapinta tukee vain samassa työtilassa olevien muuttujien kirjastojen käyttöä. - Muuttujakirjastojen noutamista työtiloista ei tueta alimuistikirjoissa viitesuorituksen aikana.
- Muistikirjan koodi viittaa muuttujiin, jotka on määritetty muuttujakirjaston aktiivisessa arvojoukossa.
Tunnetut ongelmat
Kun käytät ajonaikaista versiota 1.2 ja suoritetaan
notebookutils.help(), lueteltuja fabricClient-sovellusliittymiä ei tueta toistaiseksi, ne ovat käytettävissä edelleen. Lisäksi Tunnistetietojen ohjelmointirajapintaa ei tueta toistaiseksi Scala-muistikirjoissa.Python-muistikirja ei tue stop, restartPython-ohjelmointirajapintoja, kun käytät notebookutils.session-apuohjelmaa istunnon hallintaan.
Tällä hetkellä SPN:ää ei tueta muuttujakirjaston apuohjelmissa.