Jaa kautta


NotebookUtils (entinen MSSparkUtils) for Fabric

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 Lakehousen Files-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 Lakehousen Files-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ää -toimintoa notebookutils.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() ja notebookutils.fs.put() älä tue samanaikaista kirjoittamista samaan tiedostoon, koska atomiteettitakuita ei ole.
  • Kun käytät notebookutils.fs.append-ohjelmointirajapintaa for-silmukassa samaan tiedostoon kirjoittamiseksi, suosittelemme lisäämään toistuvien kirjoitusten välille sleep-lausekkeen, joka on noin 0,5~1. Tämä suositus johtuu siitä, että notebookutils.fs.append-ohjelmointirajapinnan sisäinen flush-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äyttökuva viittauksen suoritustuloksesta.

Näyttökuva tilannevedoksen esimerkistä.

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.nbResPath viitatussa 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:

Näyttökuva viittauksesta muistikirjojen luetteloon.

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:

Näyttökuva viittauksesta parametrit sisältävään muistikirjojen luetteloon.

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

Näyttökuva, jossa on esimerkkimuistikirja exit-funktiosta.

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.

Näyttökuva, jossa näkyy, mihin säilö valitaan.

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.

Näyttökuva, jossa näytetään salaisten koodien tallennuspaikka Azure Key Vaultiin.

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.

Näyttökuva muuttujakirjaston muuttujien luettelosta.

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.variableLibrary ohjelmointirajapinta 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 suoritetaannotebookutils.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.