NotebookUtils (korábbi MSSparkUtils) Fabric számára

A Notebook Utilities (NotebookUtils) egy beépített csomag, amely segít a Fabric Notebook gyakori feladatainak egyszerű végrehajtásában. A NotebookUtils használatával fájlrendszerekkel dolgozhat, környezeti változókat kérhet le, a jegyzetfüzeteket összeláncosíthatja, és titkos kódokkal dolgozhat. A NotebookUtils csomag a PySpark (Python) Scala, SparkR-jegyzetfüzetek és Fabric-folyamatokban érhető el.

Note

Az MsSparkUtils hivatalosan notebookUtils névre van átnevezve. A meglévő kód visszamenőlegesen kompatibilis marad, és nem okoz kompatibilitástörő változásokat. Határozottan javasoljuk , hogy frissítsen a notebookutilsra a folyamatos támogatás és az új funkciókhoz való hozzáférés biztosítása érdekében. Az mssparkutils névtér a jövőben megszűnik.
A NotebookUtils a Spark 3.4(Futtatókörnyezet v1.2) és újabb verziók használatára lett tervezve. Minden új funkció és frissítés kizárólag a notebookutils névtér előrehaladtával támogatott.

Fájlrendszer-segédprogramok

A notebookutils.fs segédprogramokat biztosít a különböző fájlrendszerek, például az Azure Data Lake Storage (ADLS) Gen2 és az Azure Blob Storage használatához. Győződjön meg arról, hogy megfelelően konfigurálja az Azure Data Lake Storage Gen2 és az Azure Blob Storage elérését.

Futtassa az alábbi parancsokat az elérhető módszerek áttekintéséhez:

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.

A NotebookUtils ugyanúgy működik a fájlrendszerrel, mint a Spark API-k. Vegyük például a notebookutils.fs.mkdirs() és a Fabric lakehouse használatát:

Usage	Relatív elérési út a HDFS-gyökérből	Az ABFS fájlrendszer abszolút elérési útja	A helyi fájlrendszer abszolút elérési útja az illesztőprogram-csomópontban
Nem alapértelmezett lakehouse	Nem támogatott	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("fájl:/<new_dir>")
Alapértelmezett lakehouse	Könyvtár a "Fájlok" vagy a "Táblák" mappa alatt: notebookutils.fs.mkdirs("Files/<new_dir>")	notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>")	notebookutils.fs.mkdirs("fájl:/<new_dir>")

Az alapértelmezett Lakehouse esetében a fájl elérési útjait a jegyzetfüzetben csatolták, és a fájl gyorsítótár alapértelmezett időtúllépése 120 másodperc. Ez azt jelenti, hogy a fájlok 120 másodpercig gyorsítótárazva lesznek a jegyzetfüzet helyi ideiglenes mappájában, még akkor is, ha eltávolítják őket a Lakehouse-ból. Ha módosítani szeretné az időtúllépési szabályt, leválaszthatja az alapértelmezett Lakehouse-fájlelérési utakat, és újra csatlakoztathatja őket különböző fileCacheTimeout értékkel.
Nem alapértelmezett Lakehouse-konfigurációk esetén a Lakehouse-útvonalak csatlakoztatása során beállíthatja a megfelelő fileCacheTimeout paramétert. Az időtúllépés 0 értékre állítása biztosítja, hogy a legújabb fájl lekérhető legyen a Lakehouse-kiszolgálóról.

Fájlok listázása

A címtár tartalmának listázásához használja a notebookutils.fs.ls('Saját könyvtár elérési útja') lehetőséget. Például:

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

A notebookutils.fs.ls() API a jegyzetfüzet típusától függően eltérően viselkedik a relatív elérési út használatakor.

Spark-jegyzetfüzetben: A relatív elérési út az alapértelmezett Lakehouse ABFSS-elérési úthoz képest van. Például notebookutils.fs.ls("Files") az alapértelmezett Lakehouse Files könyvtárára mutat.

Például:
```
notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")
```
Python-jegyzetfüzetben: A relatív elérési út a helyi fájlrendszer munkakönyvtárához van viszonyítva, amely alapértelmezés szerint a /home/trusted-service-user/work. Ezért a relatív elérési út notebookutils.fs.ls("/lakehouse/default/Files") helyett a teljes elérési utat kell használnia a Files könyvtár eléréséhez az alapértelmezett Lakehouse-ban.

Például:
```
notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")
```

Fájltulajdonságok megtekintése

Ez a metódus fájltulajdonságokat ad vissza, beleértve a fájlnevet, a fájl elérési útját, a fájlméretet, valamint azt, hogy könyvtárról és fájlról van-e szó.

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

Új címtár létrehozása

Ez a metódus létrehozza a megadott könyvtárat, ha nem létezik, és létrehozza a szükséges szülőkönyvtárakat.

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

Fájl másolása

Ez a módszer egy fájlt vagy könyvtárat másol, és támogatja a fájlrendszerek közötti másolási tevékenységet. recurse=True Az összes fájlt és könyvtárat rekurzív módon másoljuk.

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

Note

OneLake-parancsikon korlátozásai miatt, amikor adatok másolása S3/GCS típusú parancsikonról szükséges, javasoljuk, hogy csatolt elérési utat használjon abfss-elérési út helyett.

Hatékony fájlmásolás

Ez a módszer hatékonyabb módszert kínál a fájlok másolására vagy áthelyezésére, különösen nagy adatmennyiségek kezelésekor. A Fabric jobb teljesítménye érdekében ajánlott a hagyományos fastcp módszer helyettesítőjeként használnicp.

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

Considerations:

notebookutils.fs.fastcp() nem támogatja a oneLake-fájlok régiók közötti másolását. Ebben az esetben notebookutils.fs.cp() használhatja helyette.
OneLake-parancsikon korlátozásai miatt, amikor adatok másolása S3/GCS típusú parancsikonról szükséges, javasoljuk, hogy csatolt elérési utat használjon abfss-elérési út helyett.

Fájltartalom előnézete

Ez a metódus legfeljebb az adott fájl első "maxBytes" bájtját adja vissza UTF-8-ban kódolt sztringként.

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

Fájl áthelyezése

Ez a módszer áthelyez egy fájlt vagy könyvtárat, és támogatja a fájlrendszerek közötti áthelyezést.

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.

Fájl írása

Ez a metódus egy UTF-8 kóddal kódolt fájlba írja ki az adott sztringet.

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

Tartalom hozzáfűzése fájlhoz

Ez a metódus hozzáfűzi az adott sztringet egy UTF-8 kódolt fájlhoz.

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

Considerations:

notebookutils.fs.append() és notebookutils.fs.put() nem támogatja az egyidejű írást ugyanarra a fájlra az atomitási garanciák hiánya miatt.
Ha a notebookutils.fs.append API-t egy for ciklusban használja ugyanahhoz a fájlhoz való íráshoz, javasoljuk, hogy az ismétlődő írások között 0,5 s ~ 1 s körüli sleep utasítást adjon hozzá. Ennek a javaslatnak az az oka, hogy a notebookutils.fs.append API belső flush művelete aszinkron, így rövid késleltetéssel biztosítható az adatok integritása.

Fájl vagy könyvtár törlése

Ez a metódus eltávolít egy fájlt vagy könyvtárat. Úgy állítottuk be recurse=True , hogy az összes fájlt és könyvtárat rekurzív módon eltávolítsuk.

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

Könyvtár csatlakoztatása/leválasztása

További információ a részletes használatról a Fájl csatlakoztatása és leválasztása részben.

Jegyzetfüzet-segédprogramok

A Jegyzetfüzet segédprogrammal futtathat egy jegyzetfüzetet, vagy kiléphet egy értékekkel rendelkező jegyzetfüzetből. Futtassa a következő parancsot az elérhető módszerek áttekintéséhez:

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

A jegyzetfüzet-segédprogramok nem alkalmazhatók az Apache Spark-feladatdefiníciókra (SJD).

Hivatkozzon egy jegyzetfüzetre

Ez a módszer egy munkafüzetre hivatkozik, és visszaadja annak kilépési értékét. A beágyazott függvényhívásokat interaktívan vagy folyamatban is futtathatja egy jegyzetfüzetben. A hivatkozott jegyzetfüzet a függvényt meghívó jegyzetfüzet Spark-készletében fut.

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

Például:

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

A hálójegyzetfüzet a munkaterület azonosítójának megadásával több munkaterületen is támogatja a jegyzetfüzetek hivatkozását.

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

Megnyithatja a referenciafuttatás pillanatkép-hivatkozását a cella kimeneti eredményeinél. A pillanatkép rögzíti a kódfuttatási eredményeket, és lehetővé teszi a referenciafuttatások egyszerű hibakeresését.

Considerations:

A munkaterületek közötti referenciajegyzetfüzetet az 1.2-es és újabb futtatókörnyezet támogatja.
Ha a Jegyzetfüzet-erőforrás csoportban lévő fájlokat használja, a notebookutils.nbResPath hivatkozott jegyzetfüzetben győződjön meg arról, hogy az az interaktív futtatáshoz használt mappára mutat.
A referenciafuttatás lehetővé teszi, hogy a gyermekjegyzetfüzetek csak akkor fussanak, ha ugyanazt a tóházat használják, mint a szülő, öröklik a szülő tóházát, vagy egyik sem definiál egyet. A végrehajtás le lesz tiltva, ha a gyermek egy másik tóházat ad meg a szülőjegyzetfüzethez. Az ellenőrzés megkerüléséhez állítsa be a következőt useRootDefaultLakehouse: True:

Hivatkozás több jegyzetfüzet párhuzamos futtatására

A módszer notebookutils.notebook.runMultiple() lehetővé teszi több jegyzetfüzet párhuzamos vagy előre definiált topológiai szerkezettel történő futtatását. Az API egy spark-munkameneten belül többszálas implementációs mechanizmust használ, ami azt jelenti, hogy a referenciafüzet-futtatások osztoznak a számítási erőforrásokon.

A(z) notebookutils.notebook.runMultiple() segítségével a következőket teheted:

Több jegyzetfüzet egyidejű végrehajtása, anélkül, hogy megvárnánk mindegyik befejezését.
Egyszerű JSON-formátum használatával adja meg a jegyzetfüzetek függőségeit és végrehajtási sorrendjét.
Optimalizálja a Spark számítási erőforrások használatát, és csökkentse a Fabric-projektek költségeit.
A kimenetben megtekintheti az egyes jegyzetfüzet-futtatási rekordok pillanatképeit, és kényelmesen hibakeresést/monitorozást végezhet a jegyzetfüzet-feladatokban.
Szerezze be az egyes vezetői tevékenységek kilépési értékét, és használja őket az alsóbb rétegbeli feladatokban.

A notebookutils.notebook.help("runMultiple") futtatásával is megkeresheti a példát és a részletes használatot.

Íme egy egyszerű példa a jegyzetfüzetek listájának párhuzamos futtatására ezzel a módszerrel:

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

A gyökérjegyzetfüzet végrehajtási eredménye a következő:

Íme egy példa a topológiai szerkezetű jegyzetfüzetek notebookutils.notebook.runMultiple()használatával történő futtatására. Ezzel a módszerrel könnyedén vezényelheti a jegyzetfüzeteket egy kódélményen keresztül.

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

A gyökérjegyzetfüzet végrehajtási eredménye a következő:

Egy módszert is biztosítunk annak ellenőrzésére, hogy a DAG helyesen van-e definiálva.

notebookutils.notebook.validateDAG(DAG)

Considerations:

A több jegyzetfüzet-futtatás párhuzamossági foka a Spark-munkamenet teljes rendelkezésre álló számítási erőforrására korlátozódik.
Az egyidejű jegyzetfüzetek alapértelmezett száma a Spark-jegyzetfüzet esetében 50 , a Python Notebook esetében pedig alapértelmezés szerint 25 . Ezt az értéket testre szabhatja, de a túlzott párhuzamosság stabilitási és teljesítménybeli problémákhoz vezethet a magas számítási erőforrás-használat miatt. Ha problémák merülnek fel, érdemes lehet a jegyzetfüzeteket több runMultiple hívásra különválasztani, vagy csökkenteni az egyidejűséget a DAG paraméter egyidejűségi mezőjének módosításával.
A teljes DAG alapértelmezett időtúllépése 12 óra, a gyermekjegyzetfüzetben lévő cellák alapértelmezett időtúllépése pedig 90 másodperc. Az időtúllépést a DAG paraméter timeoutInSeconds és timeoutPerCellInSeconds mezőinek beállításával módosíthatja.

Kilépés a jegyzetfüzetből

Ez a metódus egy értékkel lép ki a jegyzetfüzetből. A beágyazott függvényhívásokat interaktívan vagy folyamatban is futtathatja egy jegyzetfüzetben.

Amikor interaktívan meghív egy kilépési() függvényt egy jegyzetfüzetből, a Háló jegyzetfüzet kivételt jelez, kihagyja a további cellák futtatását, és életben tartja a Spark-munkamenetet.
Amikor egy olyan folyamat jegyzetfüzetét vezényli, amely exit() függvényt hív meg, a jegyzetfüzet-tevékenység kilépési értékkel tér vissza. Ezzel befejezi a folyamat futtatását, és leállítja a Spark-munkamenetet.
Amikor meghív egy exit() függvényt egy hivatkozott jegyzetfüzetben, a Fabric Spark leállítja a hivatkozott jegyzetfüzet további végrehajtását, és folytatja a run() függvényt meghívó fő jegyzetfüzet következő celláinak futtatását. Például: A Jegyzetfüzet1 három cellával rendelkezik, és egy exit() függvényt hív meg a második cellában. A Jegyzetfüzet2 a harmadik cellában öt cellával és hívással (notebook1) rendelkezik . A Notebook2 futtatásakor a Notebook1 a második cellánál áll meg, amikor eléri a kilépési() függvényt. A Notebook2 továbbra is futtatja a negyedik és az ötödik celláit.

notebookutils.notebook.exit("value string")

Note

Az exit() függvény felülírja az aktuális cellakimenetet. Az egyéb kódkivonatok kimenetének elvesztésének elkerülése érdekében hívja meg a notebookutils.notebook.exit() egy külön cellában.

Például:

1. mintajegyzetfüzet a következő két cellával:

Az 1. cella egy bemeneti paramétert határoz meg, amelynek alapértelmezett értéke 10.
A 2. cella kilépési értékkel lép ki a jegyzetfüzetből.

A Minta1 egy másik, alapértelmezett értékekkel rendelkező jegyzetfüzetben is futtatható:

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

Output:

Notebook is executed successfully with exit value 10

A Minta1 egy másik jegyzetfüzetben is futtatható, és a bemeneti érték 20 lehet:

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

Output:

Notebook is executed successfully with exit value 20

Jegyzetfüzet-összetevők kezelése

notebookutils.notebook Speciális segédprogramokat biztosít a jegyzetfüzetelemek programozott kezeléséhez. Ezek az API-k megkönnyítik a jegyzetfüzetelemek létrehozását, beszerzését, frissítését és törlését.

A módszerek hatékony használatához vegye figyelembe a következő használati példákat:

Jegyzetfüzet létrehozása

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

Jegyzetfüzet tartalmának lekérése

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

Jegyzetfüzet frissítése

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

Jegyzetfüzet törlése

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

Jegyzetfüzetek listázása egy munkaterületen

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

Felhasználói adatfüggvény (UDF) segédprogramok

notebookutils.udf Olyan segédprogramokat biztosít, amelyek a notebook kódját a Felhasználói adatfüggvényekkel (UDF-ekkel) integrálják. Ezek a segédprogramok lehetővé teszik a függvények elérését egy UDF-elemből ugyanazon a munkaterületen vagy különböző munkaterületeken. Ezután szükség szerint meghívhat függvényeket egy UDF-elemen belül.

Íme néhány példa az UDF-segédprogramok használatára:

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

Függvények lekérése egy UDF-ből

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

Függvény meghívása

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

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

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

UDF-elem részleteinek megjelenítése

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Az UDF függvény részleteinek megjelenítése

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Hitelesítő adatok segédprogramok

A hitelesítő adatok segédprogramjaival hozzáférési jogkivonatokat szerezhet be, és titkos kulcsokat kezelhet egy Azure Key Vaultban.

Futtassa a következő parancsot az elérhető módszerek áttekintéséhez:

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

Token lekérése

A getToken egy Microsoft Entra-jogkivonatot ad vissza egy megadott közönség és név (opcionális) számára. Az alábbi listában a jelenleg elérhető célközönségkulcsok láthatók:

Tárolók célközönségének erőforrása: "tároló"
Power BI-erőforrás: "pbi"
Azure Key Vault-erőforrás: "keyvault"
Synapse RTA KQL Adatbázis Erőforrás: "kusto"

Futtassa a következő parancsot a jogkivonat lekéréséhez:

notebookutils.credentials.getToken('audience Key')

Considerations:

A "pbi" célközönséggel rendelkező jogkivonat-hatókörök idővel változhatnak. Jelenleg az alábbi hatókörök támogatottak.
A notebookutils.credentials.getToken("pbi") hívásakor a visszaadott jogkivonat korlátozott hatókörrel rendelkezik, ha a jegyzetfüzet szolgáltatásnév alatt fut. A jogkivonat nem rendelkezik a Teljes Háló szolgáltatás hatókörével. Ha a notebook a felhasználói identitás alatt fut, a token továbbra is a teljes Fabric szolgáltatási hatókörrel rendelkezik, de ez a biztonsági fejlesztésekkel változhat. Annak érdekében, hogy a jogkivonat teljes Fabric-szolgáltatáshatókörrel rendelkezzen, használjon MSAL-hitelesítést a notebookutils.credentials.getToken API helyett. További információ: Hitelesítés a Microsoft Entra-azonosítóval.
Az alábbiakban felsoroljuk azokat a hatóköröket, amelyekkel a jogkivonat a notebookutils.credentials.getToken meghívásakor a szolgáltatásnév identitása alatt lévő pbi célközönség-kulccsal rendelkezik:
- Lakehouse.ReadWrite.All
- MLExperiment.ReadWrite.All
- MLModel.ReadWrite.All
- Notebook.ReadWrite.All
- SparkJobDefinition.ReadWrite.All
- Workspace.ReadWrite.All
- Dataset.ReadWrite.All

Titkos kód lekérése

A getSecret egy Azure Key Vault-titkos kulcsot ad vissza egy adott Azure Key Vault-végponthoz és titkos névhez a felhasználói hitelesítő adatok használatával.

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

Fájl csatolása és leválasztása

A Fabric a Következő csatlakoztatási forgatókönyveket támogatja a Microsoft Spark Utilities csomagban. A csatlakoztatás, a leválasztás, a getMountPath()és a mounts() API-k segítségével távoli tárolást (ADLS Gen2) csatolhat az összes munkacsomóponthoz (illesztőprogram-csomópont és feldolgozó csomópont). A tárolási csatlakoztatási pont létrehozása után a helyi fájl API-val úgy érheti el az adatokat, mintha a helyi fájlrendszerben tárolva lenne.

ADLS Gen2-fiók csatlakoztatása

Az alábbi példa az Azure Data Lake Storage Gen2 csatlakoztatását mutatja be. A Blob Storage és az Azure File Share csatlakoztatása hasonlóan működik.

Ez a példa feltételezi, hogy rendelkezik egy Storegen2 nevű Data Lake Storage Gen2-fiókkal, amely rendelkezik egy mycontainer nevű tárolóval, amelyet csatlakoztatni szeretne a jegyzetfüzet Spark-munkamenetében a /teszteléshez .

A mycontainer nevű tároló csatlakoztatásához a notebookutilsnak először ellenőriznie kell, hogy rendelkezik-e engedéllyel a tároló eléréséhez. A Fabric jelenleg két hitelesítési módszert támogat az eseményindító csatlakoztatási műveletéhez: accountKey és sastoken.

Csatlakoztatás megosztott hozzáférési jogosultság vagy fiókkulcs segítségével

A NotebookUtils támogatja a fiókkulcs vagy a közös hozzáférésű jogosultságkód (SAS) jogkivonat paraméterként történő átadását a cél csatlakoztatásához.

Biztonsági okokból javasoljuk, hogy a fiókkulcsokat vagy SAS-jogkivonatokat az Azure Key Vaultban tárolja (ahogy az alábbi képernyőképen látható). Ezután lekérheti őket a notebookutils.credentials.getSecret API használatával. Az Azure Key Vaultról további információt az Azure Key Vault által felügyelt tárfiókkulcsokról szóló cikkben talál.

Mintakód az accountKey metódushoz:

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

Mintakód a sastokenhez:

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

Csatlakoztatási paraméterek:

fileCacheTimeout: A blobok alapértelmezés szerint 120 másodpercig gyorsítótárazva vannak a helyi ideiglenes mappában. Ez idő alatt a blobfuse nem ellenőrzi, hogy a fájl naprakész-e vagy sem. A paraméter beállítható úgy, hogy módosítsa az alapértelmezett időtúllépési időt. Ha több ügyfél egyszerre módosítja a fájlokat, hogy elkerülje a helyi és a távoli fájlok közötti ellentmondásokat, javasoljuk, hogy lerövidítse a gyorsítótár idejét, vagy akár 0-ra módosítsa, és mindig a legújabb fájlokat kapja a kiszolgálótól.
időtúllépés: A csatlakoztatási művelet időtúllépése alapértelmezés szerint 120 másodperc. A paraméter beállítható úgy, hogy módosítsa az alapértelmezett időtúllépési időt. Ha túl sok a végrehajtó, vagy ha a csatlakoztatás ideje lejár, javasoljuk az érték növelését.

A következő paramétereket használhatja:

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

Note

Biztonsági okokból javasoljuk, hogy ne ágyazza be a hitelesítő adatokat közvetlenül a kódba. A hitelesítő adatok további védelme érdekében a jegyzetfüzet kimeneteiben megjelenő titkok ki lesznek takarva. További információ: Titkos kód újraválasztása.

Hogyan telepítsünk egy tóházat

Mintakód egy tóház /<mount_name> csatlakoztatásához:

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

Fájlok elérése a csatlakoztatási pont alatt a notebookutils fs API használatával

A csatlakoztatási művelet fő célja, hogy az ügyfelek hozzáférhessenek egy távoli tárfiókban tárolt adatokhoz egy helyi fájlrendszer API-val. Az adatokat a notebookutils fs API-val is elérheti egy csatlakoztatott elérési út paraméterként. Ez az elérési út formátuma egy kicsit más.

Tegyük fel, hogy csatlakoztatta a Data Lake Storage Gen2 tárolómontainert a csatlakoztatási API használatával történő /teszteléshez . Amikor egy helyi fájlrendszer API-val éri el az adatokat, az elérési út formátuma a következő:

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

Ha a notebookutils fs API-val szeretné elérni az adatokat, javasoljuk, hogy a getMountPath() használatával szerezze be a pontos elérési utat:

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

Címtárak listázása:

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

Fájltartalom olvasása:

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

Címtár létrehozása:

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

A csatlakoztatási pont alatti fájlok elérése helyi elérési úton

A standard fájlrendszerrel egyszerűen olvashatja és írhatja a fájlokat a csatlakoztatási pontban. Íme egy Python-példa:

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

Meglévő csatlakoztatási pontok ellenőrzése

A notebookutils.fs.mounts() API használatával ellenőrizheti a csatlakoztatási pontok összes meglévő információját:

notebookutils.fs.mounts()

A csatlakoztatási pont leválasztása

A csatlakoztatási pont leválasztásához használja az alábbi kódot (/tesztelje ebben a példában):

notebookutils.fs.unmount("/test")

Ismert korlátozások

Az aktuális csatlakoztatás feladatszintű konfiguráció; Javasoljuk, hogy a csatlakoztatási API használatával ellenőrizze, hogy létezik-e csatlakoztatási pont, vagy nem érhető el.
A leválasztó mechanizmus nem alkalmazódik automatikusan. Ha az alkalmazás futtatása befejeződött, a csatlakoztatási pont leválasztásához és a lemezterület felszabadításához explicit módon meg kell hívnia egy leválasztott API-t a kódban. Ellenkező esetben a csatlakoztatási pont az alkalmazás futtatása után is megmarad a csomópontban.
Az ADLS Gen1-tárfiók csatlakoztatása nem támogatott.

Lakehouse-segédprogramok

notebookutils.lakehouse a Lakehouse-elemek kezelésére szabott segédprogramokat biztosít. Ezek a segédprogramok segítségével könnyedén hozhat létre, kérhet le, frissíthet és törölhet Lakehouse-összetevőket.

A metódusok áttekintése

Az alábbiakban áttekintheti a notebookutils.lakehouseáltal biztosított elérhető módszereket:

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

Használati példák

A módszerek hatékony használatához vegye figyelembe a következő használati példákat:

Lakehouse létrehozása

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

Tóparti ház beszerzése

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

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

Lakehouse frissítése

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

Lakehouse törlése

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

Lakehouse-k listázása egy munkaterületen

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

A Lakehouse összes táblázatának felsorolása

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

Adatbetöltési táblaművelet indítása egy Lakehouse-ban

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

További információk

Az egyes metódusokkal és paramétereikkel kapcsolatos részletesebb információkért használja a függvényt notebookutils.lakehouse.help("methodName") .

Futtatókörnyezeti segédprogramok

A munkamenet környezeti adatainak megjelenítése

A notebookutils.runtime.context segítségével lekérheti az aktuális élő munkamenet környezeti adatait, beleértve a jegyzetfüzet nevét, az alapértelmezett lakehouse-t, a munkaterület adatait, és ha az egy folyamat futtatás, stb.

notebookutils.runtime.context

Az alábbi táblázat a tulajdonságokat ismerteti.

Parameter	Explanation
`currentNotebookName`	Az aktuális jegyzetfüzet neve
`currentNotebookId`	Az aktuális jegyzetfüzet egyedi azonosítója
`currentWorkspaceName`	Az aktuális munkaterület neve
`currentWorkspaceId`	Az aktuális munkaterület azonosítója
`defaultLakehouseName`	Az alapértelmezett lakehouse megjelenítendő neve, ha meg van adva
`defaultLakehouseId`	Az alapértelmezett lakehouse azonosítója, ha meg van adva
`defaultLakehouseWorkspaceName`	Az alapértelmezett lakehouse munkaterületneve, ha meg van adva
`defaultLakehouseWorkspaceId`	Az alapértelmezett lakehouse munkaterület-azonosítója, ha meg van adva
`currentRunId`	Referenciafuttatásban az aktuális futtatási azonosító
`parentRunId`	Beágyazott futtatásokkal rendelkező referenciafuttatásokban ez az azonosító a szülő futtatási azonosítója
`rootRunId`	Beágyazott futtatásokkal rendelkező referenciafuttatásban ez az azonosító a gyökérfuttatás azonosítója
`isForPipeline`	Annak eldöntése, hogy a futtatás egy csőfolyamathoz tartozik-e.
`isReferenceRun`	Azt jelzi, hogy az aktuális futtatás referenciafuttatás-e
`referenceTreePath`	A beágyazott referenciák fa-struktúrája, amelyet kizárólag a pillanatkép-hierarchiához használnak a figyelő L2 oldalon.
`rootNotebookId`	(Csak referenciafuttatásban) A gyökérjegyzetfüzet azonosítója egy referenciafuttatásban.
`rootNotebookName`	(Csak referenciafuttatás esetén) Egy referenciafuttatásban a gyökérjegyzetfüzet neve.
`rootWorkspaceId`	(Csak referenciafuttatásban) A gyökérjegyzetfüzet munkaterület-azonosítója egy referenciafuttatásban.
`rootWorkspaceName`	(Csak referenciafuttatásban) A gyökérjegyzetfüzet munkaterületneve egy referenciafuttatásban.
`activityId`	Az aktuális tevékenység Livy feladat-azonosítója
`hcRepId`	A REPL-azonosító magas egyidejűségi módban
`clusterId`	A(z) Synapse Spark klaszter identitása
`poolName`	A használt Spark-készlet neve
`environmentId`	A környezeti azonosító, amelyen a feladat fut
`environmentWorkspaceId`	A környezet munkaterület-azonosítója
`userId`	Az aktuális felhasználó felhasználói azonosítója
`userName`	Az aktuális felhasználó felhasználóneve

Munkamenet-kezelés

Interaktív munkamenet leállítása

Ahelyett, hogy manuálisan kattintanál a Leállítás gombra, néha kényelmesebb leállítani egy interaktív munkamenetet egy API meghívásával a kódban. Ilyen esetekben egy API-notebookutils.session.stop() biztosítunk az interaktív munkamenet kódon keresztüli leállításának támogatásához, amely a Scala és a PySpark számára érhető el.

notebookutils.session.stop()

notebookutils.session.stop() API a háttérben aszinkron módon állítja le az aktuális interaktív munkamenetet. Emellett leállítja a Spark-munkamenetet, és felszabadítja a munkamenet által foglalt erőforrásokat, így azok elérhetők az ugyanabban a készletben lévő többi munkamenet számára.

Indítsa újra a Python-értelmezőt

A notebookutils.session segédprogram lehetővé teszi a Python-értelmező újraindítását.

notebookutils.session.restartPython()

Considerations:

A jegyzetfüzet-referenciafuttatási esetben a restartPython() csak a hivatkozott aktuális jegyzetfüzet Python-értelmezőjét indítja újra.
Ritkán előfordulhat, hogy a parancs a Spark tükröződési mechanizmusa miatt meghiúsul, az újrapróbálkozás pedig enyhítheti a problémát.

Változó könyvtár segédletek

Note

A jegyzetfüzetek "Változótár segédprogramjai" előzetes verzióban érhetőek el.

A változó kódtárak lehetővé teszik, hogy elkerülje a jegyzetfüzet kódjában lévő keménykód-értékeket. A kód módosítása helyett frissítheti a kódtár értékeit. A jegyzetfüzet a változótárra hivatkozik az értékek lekéréséhez. Ez a megközelítés egy központilag felügyelt kódtár használatával leegyszerűsíti a kódok csapatok és projektek közötti újrafelhasználását.

Futtassa az alábbi parancsokat az elérhető módszerek áttekintéséhez:

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.

A változó definiálása a változótárban

Először definiálja a változókat, mielőtt használja a notebookutils.variableLibrary-t.

A változótár lekérése a jegyzetfüzetből

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

Példa a változó dinamikus használatára.

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)

Egyetlen változó elérése hivatkozás alapján

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

Az notebookutils.variableLibrary API csak ugyanazon a munkaterületen belül támogatja a változókódtárak elérését.
A változó könyvtárak munkaterületek közötti lekérése nem támogatott gyermek notebookokban a referenciafuttatás során.
A jegyzetfüzet kódja a változótár aktív értékhalmazában definiált változókra hivatkozik.

Ismert problémák

Az 1.2-es notebookutils.help()verzió feletti futtatókörnyezeti verzió használata esetén a felsorolt fabricClient, PBIClient API-k egyelőre nem támogatottak, a további verziókban is elérhetők lesznek. Emellett a Hitelesítő adatok API egyelőre nem támogatott a Scala-jegyzetfüzetekben.
A Python-jegyzetfüzet nem támogatja a stop, restartPython API-kat, amikor a notebookutils.session segédprogramot használja a munkamenet-kezeléshez.
A változó kódtár-segédprogramok jelenleg nem támogatják az egyszerű szolgáltatásneveket.

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-08-16

Megosztás a következőn keresztül:

NotebookUtils (korábbi MSSparkUtils) Fabric számára

Fájlrendszer-segédprogramok

Fájlok listázása

Fájltulajdonságok megtekintése

Új címtár létrehozása

Fájl másolása

Hatékony fájlmásolás

Fájltartalom előnézete

Fájl áthelyezése

Fájl írása

Tartalom hozzáfűzése fájlhoz

Fájl vagy könyvtár törlése

Könyvtár csatlakoztatása/leválasztása

Jegyzetfüzet-segédprogramok

Hivatkozzon egy jegyzetfüzetre

Hivatkozás több jegyzetfüzet párhuzamos futtatására

Kilépés a jegyzetfüzetből

Jegyzetfüzet-összetevők kezelése

Jegyzetfüzet létrehozása

Jegyzetfüzet tartalmának lekérése

Jegyzetfüzet frissítése

Jegyzetfüzet törlése

Jegyzetfüzetek listázása egy munkaterületen

Felhasználói adatfüggvény (UDF) segédprogramok

Függvények lekérése egy UDF-ből

Függvény meghívása

UDF-elem részleteinek megjelenítése

Az UDF függvény részleteinek megjelenítése

Hitelesítő adatok segédprogramok

Token lekérése

Titkos kód lekérése

Fájl csatolása és leválasztása

ADLS Gen2-fiók csatlakoztatása

Csatlakoztatás megosztott hozzáférési jogosultság vagy fiókkulcs segítségével

Hogyan telepítsünk egy tóházat

Fájlok elérése a csatlakoztatási pont alatt a notebookutils fs API használatával

A csatlakoztatási pont alatti fájlok elérése helyi elérési úton

Meglévő csatlakoztatási pontok ellenőrzése

A csatlakoztatási pont leválasztása

Ismert korlátozások

Lakehouse-segédprogramok

A metódusok áttekintése

Használati példák

Lakehouse létrehozása

Tóparti ház beszerzése

Lakehouse frissítése

Lakehouse törlése

Lakehouse-k listázása egy munkaterületen

A Lakehouse összes táblázatának felsorolása

Adatbetöltési táblaművelet indítása egy Lakehouse-ban

További információk

Futtatókörnyezeti segédprogramok

A munkamenet környezeti adatainak megjelenítése

Munkamenet-kezelés

Interaktív munkamenet leállítása

Indítsa újra a Python-értelmezőt

Változó könyvtár segédletek

A változó definiálása a változótárban

A változótár lekérése a jegyzetfüzetből

Egyetlen változó elérése hivatkozás alapján

Ismert problémák

Kapcsolódó tartalom

Visszajelzés

További források