Dela via

NotebookUtils (tidigare MSSparkUtils) för Fabric

Notebook Utilities (NotebookUtils) är ett inbyggt paket som hjälper dig att enkelt utföra vanliga uppgifter i Fabric Notebook. Du kan använda NotebookUtils för att arbeta med filsystem, hämta miljövariabler, länka ihop notebook-filer och arbeta med hemligheter. NotebookUtils-paketet är tillgängligt i PySpark (Python) Scala, SparkR Notebooks och Fabric-pipelines.

Anteckning

  • MsSparkUtils har officiellt bytt namn till NotebookUtils. Den befintliga koden förblir bakåtkompatibel och orsakar inga förändringar som bryter kompatibiliteten. Vi rekommenderar starkt att du uppgraderar till notebookutils för att säkerställa fortsatt support och åtkomst till nya funktioner. Mssparkutils-namnområdet kommer att dras tillbaka i framtiden.
  • NotebookUtils är utformat för att fungera med Spark 3.4 (Runtime v1.2) och senare. Alla nya funktioner och uppdateringar stöds exklusivt med notebookutils-namnrymden framöver.

Filsystemverktyg

notebookutils.fs tillhandahåller verktyg för att arbeta med olika filsystem, inklusive Azure Data Lake Storage (ADLS) Gen2 och Azure Blob Storage. Se till att du konfigurerar åtkomsten till Azure Data Lake Storage Gen2 och Azure Blob Storage på rätt sätt.

Kör följande kommandon för en översikt över tillgängliga metoder:

notebookutils.fs.help()

Resultat

notebookutils.fs provides utilities for working with various FileSystems.

Below is overview about the available methods:

cp(from: String, to: String, recurse: Boolean = false): Boolean -> Copies a file or directory, possibly across FileSystems
fastcp(from: String, to: String, recurse: Boolean = true): Boolean -> [Preview] Copies a file or directory via azcopy, possibly across FileSystems
mv(from: String, to: String, createPath: Boolean = false, overwrite: Boolean = false): Boolean -> Moves a file or directory, possibly across FileSystems
ls(dir: String): Array -> Lists the contents of a directory
mkdirs(dir: String): Boolean -> Creates the given directory if it does not exist, also creating any necessary parent directories
put(file: String, contents: String, overwrite: Boolean = false): Boolean -> Writes the given String out to a file, encoded in UTF-8
head(file: String, maxBytes: int = 1024 * 100): String -> Returns up to the first 'maxBytes' bytes of the given file as a String encoded in UTF-8
append(file: String, content: String, createFileIfNotExists: Boolean): Boolean -> Append the content to a file
rm(dir: String, recurse: Boolean = false): Boolean -> Removes a file or directory
exists(file: String): Boolean -> Check if a file or directory exists
mount(source: String, mountPoint: String, extraConfigs: Map[String, Any]): Boolean -> Mounts the given remote storage directory at the given mount point
unmount(mountPoint: String): Boolean -> Deletes a mount point
mounts(): Array[MountPointInfo] -> Show information about what is mounted
getMountPath(mountPoint: String, scope: String = ""): String -> Gets the local path of the mount point

Use notebookutils.fs.help("methodName") for more info about a method.

NotebookUtils fungerar med filsystemet på samma sätt som Spark-API:er. Ta notebookutils.fs.mkdirs() och Fabric lakehouse-användning till exempel:

Användning Relativ sökväg från HDFS:s rot Absolut sökväg för ABFS-filsystem Absolut sökväg för det lokala filsystemet i drivrutinsnoden
Icke-standard sjöhus Stöds inte notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Standardlägg lakehouse Katalog under "Filer" eller "Tabeller": notebookutils.fs.mkdirs("Files/<new_dir>") notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")

Anteckning

  • För det förinställda Lakehouse ansluts filsökvägar i din anteckningsbok med en standardtidsgräns för filcache på 120 sekunder. Det innebär att filer cachelagras i notebook-filens lokala temporära mapp i 120 sekunder, även om de tas bort från Lakehouse. Om du vill ändra regeln för timeout kan du avmontera standardfilsökvägarna för Lakehouse och montera dem igen med ett annat fileCacheTimeout-värde.
  • För Lakehouse-konfigurationer som inte är standard kan du ange lämplig fileCacheTimeout-parameter under monteringen av Lakehouse-sökvägarna. Om tidsgränsen anges till 0 ser du till att den senaste filen hämtas från Lakehouse-servern.

Lista filer

Om du vill visa en lista över innehållet i en katalog använder du notebookutils.fs.ls('Din katalogsökväg'). Till exempel:

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()-API:t fungerar annorlunda när du använder relativ sökväg, beroende på typ av notebook.

  • I en Spark notebook: Den relativa sökvägen är relativ till Lakehouse ABFSS:s standardsökväg. Till exempel pekar notebookutils.fs.ls("Files") på katalogen Files i Standard Lakehouse.

    Till exempel:

    notebookutils.fs.ls("Files/sample_datasets/public_holidays.parquet")

  • I en Python-anteckningsbok: Den relativa sökvägen är relativ till det lokala filsystemets arbetskatalog, som i standard är /home/trusted-service-user/work. Därför bör du använda den fullständiga sökvägen i stället för en relativ sökväg notebookutils.fs.ls("/lakehouse/default/Files") för att få åtkomst till katalogen Files i standardkatalogen i Lakehouse.

    Till exempel:

    notebookutils.fs.ls("/lakehouse/default/Files/sample_datasets/public_holidays.parquet")

Visa filegenskaper

Den här metoden returnerar filegenskaper som filnamn, filsökväg, filstorlek och om det är en katalog och en fil.

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

Skapa ny katalog

Den här metoden skapar den angivna katalogen om den inte finns och skapar alla nödvändiga överordnade kataloger.

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

Kopiera fil

Den här metoden kopierar en fil eller katalog och stöder kopieringsaktivitet mellan filsystem.

notebookutils.fs.cp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Anteckning

På grund av -begränsningarna i OneLake-genvägen: när du behöver använda notebookutils.fs.cp() för att kopiera data från genvägar av S3/GCS-typ, rekommenderar vi att du använder en monterad sökväg istället för en abfss-sökväg.

Effektiv kopiera fil

Den här metoden erbjuder en effektivare metod för att kopiera eller flytta filer, särskilt när du hanterar stora datavolymer. För bättre prestanda på Fabric är det lämpligt att använda fastcp som ersättning för den traditionella cp-metoden.

Anteckning

  • notebookutils.fs.fastcp() stöder inte kopiering av filer i OneLake mellan regioner. I det här fallet kan du använda notebookutils.fs.cp() i stället.
  • På grund av -begränsningarna i OneLake-genvägen: när du behöver använda notebookutils.fs.fastcp() för att kopiera data från genvägar av S3/GCS-typ, rekommenderar vi att du använder en monterad sökväg istället för en abfss-sökväg.
notebookutils.fs.fastcp('source file or directory', 'destination file or directory', True)# Set the third parameter as True to copy all files and directories recursively

Förhandsgranska filinnehåll

Den här metoden returnerar upp till de första "maxBytes" byten av den angivna filen som en sträng kodad i UTF-8.

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

Flytta fil

Den här metoden flyttar en fil eller katalog och stöder flyttningar mellan filsystem.

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.

Skriv fil

Den här metoden skriver ut den angivna strängen till en fil, kodad i UTF-8.

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

Lägga till innehåll i en fil

Den här metoden lägger till den angivna strängen i en fil, kodad i UTF-8.

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

Anteckning

  • notebookutils.fs.append() och notebookutils.fs.put() stöder inte samtidig skrivning till samma fil på grund av brist på atomicitetsgarantier.
  • När du använder API:et notebookutils.fs.append i en for loop för att skriva till samma fil rekommenderar vi att du lägger till en sleep instruktion på cirka 0,5 s ~ 1 s mellan de återkommande skrivningar. Den här rekommendationen beror på att notebookutils.fs.append API:ets interna flush åtgärd är asynkron, så en kort fördröjning bidrar till att säkerställa dataintegriteten.

Ta bort fil eller katalog

Den här metoden tar bort en fil eller katalog.

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

Montera/demontera katalog

Mer information om detaljerad användning finns i Montera och demontera filer.

Notebook-verktyg

Använd Notebook Utilities för att köra en anteckningsbok eller avsluta en anteckningsbok med ett specificerat värde. Kör följande kommando för att få en översikt över tillgängliga metoder:

notebookutils.notebook.help()

Resultat:


The notebook module.

exit(value: String): void -> This method lets you exit a notebook with a value.
run(path: String, timeoutSeconds: int, arguments: Map, workspace: String): String -> This method runs a notebook and returns its exit value.
runMultiple(DAG: Any): Map[String, MsNotebookRunResult] -> [Preview] Runs multiple notebooks concurrently with support for dependency relationships.
validateDAG(DAG: Any): Boolean -> [Preview] This method check if the DAG is correctly defined.

[Preview] Below methods are only support Fabric Notebook.
create(name: String, description: String = "", content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = ""): Artifact -> Create a new Notebook.
get(name: String, workspaceId: String = ""): Artifact -> Get a Notebook by name or id.
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact -> Update a Artifact by name.
delete(name: String, workspaceId: String = ""): Boolean -> Delete a Notebook by name.
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact] -> List all Notebooks in the workspace.
updateDefinition(name: String, content: String = "", defaultLakehouse: String = "", defaultLakehouseWorkspace: String = "", workspaceId: String = "") -> Update the definition of a Notebook.

Use notebookutils.notebook.help("methodName") for more info about a method.

Anteckning

Notebook-verktyg gäller inte för Apache Spark-jobbdefinitioner (SJD).

Referera till en anteckningsbok

Den här metoden refererar till en notebook-fil och returnerar dess slutvärde. Du kan köra kapslade funktionsanrop i en anteckningsbok interaktivt eller i en pipeline. Anteckningsboken som refereras körs på Sparkklustret i anteckningsboken som anropar den här funktionen.

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

Till exempel:

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

Fabric notebook har också stöd för att referera till notebooks över flera arbetsytor genom att specificera arbetsyte-ID.

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

Du kan öppna länken för ögonblicksbilden av referenskörningen i cellens utdata. Skärmbilden registrerar resultatet av körd kod och gör att du enkelt kan felsöka en referenskörning.

Skärmbild av resultatet av referenskörningen.

Skärmbild av ett exempel på en ögonblicksbild.

Anteckning

  • Referensnotebooken för flera arbetsytor stöds av körningsversion 1.2 och senare.
  • Om du använder filerna under Notebook-resurs använder du notebookutils.nbResPath i den refererade notebook-filen för att se till att den pekar på samma mapp som den interaktiva körningen.

Referenskörning av flera notebook-filer parallellt

Viktigt!

Den här funktionen är i förhandsversion.

Med metoden notebookutils.notebook.runMultiple() kan du köra flera notebook-filer parallellt eller med en fördefinierad topologisk struktur. API:t använder en mekanism för implementering av flera trådar inom en Spark-session, vilket innebär att referensanteckningsbokens körningar delar på beräkningsresurserna.

Med notebookutils.notebook.runMultiple()kan du:

  • Kör flera notebooks samtidigt, utan att behöva vänta på att var och en ska bli klar.

  • Ange beroenden och körningsordning för dina notebook-filer med hjälp av ett enkelt JSON-format.

  • Optimera användningen av Spark-beräkningsresurser och minska kostnaden för dina Fabric-projekt.

  • Visa ögonblicksbilder av utförandet av varje notebook i resultatet och felsök och övervaka notebook-uppgifter på ett bekvämt sätt.

  • Hämta slutvärdet för varje verkställande aktivitet och använd dem i underordnade uppgifter.

Du kan också försöka köra notebookutils.notebook.help("runMultiple") för att hitta exemplet och den detaljerade användningen.

Här är ett enkelt exempel på hur du kör en lista över notebook-filer parallellt med den här metoden:


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

Körningsresultatet från huvudanteckningsboken är följande:

Skärmbild av en lista med anteckningsböcker.

Här är ett exempel på hur du kör notebook-filer med topologisk struktur med hjälp av notebookutils.notebook.runMultiple(). Använd den här metoden för att enkelt orkestrera notebook-filer via en kodupplevelse.

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

Körningsresultatet från huvudanteckningsboken är följande:

Skärmbild av en lista över anteckningsböcker med parametrar.

Vi tillhandahåller också en metod för att kontrollera om DAG är korrekt definierad.

notebookutils.notebook.validateDAG(DAG)

Anteckning

  • Parallellitetsgraden för flera notebook-körningar är begränsad till den totala tillgängliga beräkningsresursen för en Spark-session.
  • Den övre gränsen för bärbar dator-aktiviteter eller samtidiga bärbara datorer är 50. Om du överskrider den här gränsen kan det leda till stabilitets- och prestandaproblem på grund av hög beräkningsresursanvändning. Om det uppstår problem kan du överväga att separera notebook-filer i flera runMultiple anrop eller minska samtidigheten genom att justera samtidighetsfältet i DAG-parametern.
  • Standardtidsgränsen för hela DAG är 12 timmar och standardtidsgränsen för varje cell i den underordnade anteckningsboken är 90 sekunder. Du kan ändra tidsgränsen genom att ange timeoutInSeconds och timeoutPerCellInSeconds fält i DAG-parametern.

Stäng en notebook

Den här metoden avslutar en anteckningsbok med ett värde. Du kan köra kapslade funktionsanrop i en anteckningsbok interaktivt eller i en pipeline.

  • När du anropar en exit() -funktion från en notebook-fil interaktivt genererar Fabric-notebook-filen ett undantag, hoppar över efterföljande celler och håller Spark-sessionen vid liv.

  • När du orkestrerar en anteckningsbok i en pipeline som anropar en exit()-funktion returneras anteckningsboksaktiviteten med ett returvärde. Detta slutför pipelinekörningen och stoppar Spark-sessionen.

  • När du anropar en exit()-funktion i en refererad notebook kommer Fabric Spark att stoppa den fortsatta körningen av den refererade notebooken och fortsätta att köra nästa celler i huvudanteckningsboken som anropar funktionen run(). Till exempel: Notebook1 har tre celler och anropar en exit() -funktion i den andra cellen. Notebook2 har fem celler och anropar run(notebook1) i den tredje cellen. När du kör Notebook2 stoppas Notebook1 vid den andra cellen när du trycker på funktionen exit(). Notebook2 fortsätter att köra sin fjärde och femte cell.

notebookutils.notebook.exit("value string")

Anteckning

Funktionen exit() skriver över den aktuella cellens utdata. Om du vill undvika att förlora utdata från andra kodinstruktioner anropar du notebookutils.notebook.exit() i en separat cell.

Till exempel:

Sample1 anteckningsbok med följande två celler:

  • Cell 1 definierar en indataparameter med standardvärdet inställt på 10.

  • Cell 2 lämnar anteckningsboken med indata som slutvärde.

Skärmbild som visar en exempelanteckningsbok med avsluta-funktionen.

Du kan köra Sample1 i en annan notebook-fil med standardvärden:

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

Resultat:

Notebook is executed successfully with exit value 10

Du kan köra Sample1 i en annan notebook-fil och ange indatavärdet som 20:

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

Resultat:

Notebook is executed successfully with exit value 20

Hantera notebook-artefakter

notebookutils.notebook tillhandahåller specialiserade verktyg för att hantera notebook-objekt programmatiskt. Dessa API:er kan hjälpa dig att enkelt skapa, hämta, uppdatera och ta bort notebook-objekt.

Tänk på följande användningsexempel för att använda dessa metoder effektivt:

Skapa en notebook

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

Hämta innehåll från en anteckningsbok

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

Uppdatera ett anteckningsblock

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

Ta bort en anteckningsbok

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

Visa anteckningsböcker på en arbetsyta

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

UDF-verktyg (User Data Function)

notebookutils.udf tillhandahåller verktyg som är utformade för att integrera notebook-kod med användardatafunktioner (UDF:er). Med dessa verktyg kan du komma åt funktioner från ett UDF-objekt på samma arbetsyta eller mellan olika arbetsytor. Du kan sedan anropa funktioner i ett UDF-objekt efter behov.

Här är en översikt över tillgängliga metoder:

# Get functions
myFunctions = notebookutils.udf.getFunctions('UDFItemName') # Get functions from UDF within the same workspace
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId') # Get functions from UDF across different workspace

# Additional helper method to return all functions, their respective parameters, and types.
display(myFunctions.functionDetails)
display(myFunctions.itemDetails)

# Invoke the function
myFunctions.functionName('value1', 'value2')
myFunctions.functionName(parameter1='value1', parameter2='value2'...) # Another way to invoke the function

Hämta funktioner från en UDF

myFunctions = notebookutils.udf.getFunctions('UDFItemName')
myFunctions = notebookutils.udf.getFunctions('UDFItemName', 'workspaceId')

var myFunctions = notebookutils.udf.getFunctions("UDFItemName")
var myFunctions = notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

myFunctions <- notebookutils.udf.getFunctions("UDFItemName")
myFunctions <- notebookutils.udf.getFunctions("UDFItemName", "workspaceId")

Anropa en funktion

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

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

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

Visa information för ett UDF-objekt

display([myFunctions.itemDetails])

display(Array(myFunctions.itemDetails))

myFunctions$itemDetails()

Visa funktionsinformation för en UDF

display(myFunctions.functionDetails)

display(myFunctions.functionDetails)

myFunctions$functionDetails()

Verktyg för autentiseringsuppgifter

Du kan använda verktygen för autentiseringsuppgifter för att hämta åtkomsttoken och hantera hemligheter i ett Azure Key Vault.

Kör följande kommando för att få en översikt över tillgängliga metoder:

notebookutils.credentials.help()

Resultat:

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

Hämta token

getToken returnerar en Microsoft Entra-token för en viss målgrupp och ett visst namn (valfritt). I följande lista visas tillgängliga målgruppsnycklar:

  • Resurs för lagringsmålgrupp: "lagring"
  • Power BI-resurs: "pbi"
  • Azure Key Vault-resurs: "nyckelvalv"
  • Synapse RTA KQL DB-resurs: "kusto"

Kör följande kommando för att hämta token:

notebookutils.credentials.getToken('audience Key')

Hämta hemlighet med användarautentiseringsuppgifter

getSecret returnerar en Azure Key Vault-hemlighet för en viss Azure Key Vault-slutpunkt och ett hemligt namn med hjälp av autentiseringsuppgifter.

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

Montera och demontera filer

Fabric stöder följande monteringsscenarier i Microsoft Spark Utilities-paketet. Du kan använda API:erna mount, unmount, getMountPath()och mounts() för att ansluta fjärrlagring (ADLS Gen2) till alla arbetsnoder (drivrutinsnoder och arbetsnoder). När lagringsmonteringspunkten är på plats använder du det lokala fil-API:et för att komma åt data som om de lagras i det lokala filsystemet.

Montera ett ADLS Gen2-konto

I följande exempel visas hur du monterar Azure Data Lake Storage Gen2. Att montera Blob Storage fungerar på liknande sätt.

Det här exemplet förutsätter att du har ett Data Lake Storage Gen2-konto med namnet storegen2, som har en container med namnet mycontainer som du vill montera på /test i din notebook Spark-session.

Skärmbild som visar var du väljer en container att montera.

För att montera containern mycontainer måste notebookutils först kontrollera om du har behörighet att komma åt containern. För närvarande stöder Fabric två autentiseringsmetoder för utlösarmonteringsåtgärden: accountKey och sastoken.

Montera via signaturtoken för delad åtkomst eller kontonyckel

NotebookUtils stöder explicit överföring av en kontonyckel eller SAS-token (Signatur för delad åtkomst) som en parameter för att montera målet.

Av säkerhetsskäl rekommenderar vi att du lagrar kontonycklar eller SAS-token i Azure Key Vault (som följande skärmbild visar). Du kan sedan hämta dem med hjälp av API:et notebookutils.credentials.getSecret . Mer information om Azure Key Vault finns i Om Azure Key Vault-hanterade lagringskontonycklar.

Skärmbild som visar var hemligheter lagras i ett Azure Key Vault.

Exempelkod för metoden accountKey :

# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
accountKey = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"accountKey":accountKey}
)

Exempelkod för sastoken:

# get access token for keyvault resource
# you can also use full audience here like https://vault.azure.net
sasToken = notebookutils.credentials.getSecret("<vaultURI>", "<secretName>")
notebookutils.fs.mount(  
    "abfss://mycontainer@<accountname>.dfs.core.windows.net",  
    "/test",  
    {"sasToken":sasToken}
)

Monteringsparametrar:

  • fileCacheTimeout: Blobar cachelagras i den lokala temp-mappen i 120 sekunder som standard. Under den här tiden kontrollerar blobfuse inte om filen är uppdaterad eller inte. Parametern kan ställas in för att ändra standardtidsgränsen. När flera klienter ändrar filer samtidigt, för att undvika inkonsekvenser mellan lokala filer och fjärrfiler, rekommenderar vi att du förkortar cachetiden eller till och med ändrar den till 0 och alltid får de senaste filerna från servern.
  • timeout: Tidsgränsen för monteringsåtgärden är som standard 120 sekunder. Parametern kan ställas in för att ändra standardtidsgränsen. När det finns för många exekutorer eller när monteringsprocessen överskrider tidsgränsen rekommenderar vi att du ökar värdet.

Du kan använda följande parametrar:

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

Anteckning

I säkerhetssyfte rekommenderar vi att du undviker att bädda in autentiseringsuppgifter direkt i kod. För att ytterligare skydda dina autentiseringsuppgifter redigeras alla hemligheter som visas i notebook-utdata. Mer information finns i Hemlig redigering.

Hur man monterar ett sjöhus

Exempelkod för montering av ett sjöhus till /<mount_name>:

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

Komma åt filer under monteringspunkten med hjälp av notebookutils fs-API:et

Huvudsyftet med monteringsåtgärden är att låta kunder komma åt data som lagras i ett fjärrlagringskonto med ett lokalt filsystem-API. Du kan också få åtkomst till data med hjälp av notebookutils fs-API, med en monterad sökväg som parameter. Det här sökvägsformatet är lite annorlunda.

Anta att du monterade Data Lake Storage Gen2-containern mycontainer till /test med hjälp av monterings-API:et. När du kommer åt data med ett lokalt filsystems-API är sökvägsformatet så här:

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

När du vill komma åt data med hjälp av notebookutils fs-API:et rekommenderar vi att du använder getMountPath() för att få rätt sökväg:

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

  • Lista katalogerna:

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

  • Läs filinnehåll:

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

  • Skapa en katalog:

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

Komma åt filer under monteringspunkten via lokal sökväg

Du kan enkelt läsa och skriva filerna i monteringspunkten med hjälp av standardfilsystemet. Här är ett Python-exempel:

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

Så här kontrollerar du befintliga monteringspunkter

Du kan använda API:et notebookutils.fs.mounts() för att kontrollera all befintlig monteringspunktsinformation:

notebookutils.fs.mounts()

Avmontera monteringspunkten

Använd följande kod för att demontera monteringspunkten (/testa i det här exemplet):

notebookutils.fs.unmount("/test")

Kända begränsningar

  • Den aktuella monteringen är en konfiguration på jobbnivå. Vi rekommenderar att du använder monterings-API:et för att kontrollera om en monteringspunkt finns eller inte är tillgänglig.

  • Avmonteringsmekanismen tillämpas inte automatiskt. När programkörningen är klar måste du uttryckligen anropa ett avmonterings-API i koden för att demontera monteringspunkten och frigöra diskutrymmet. Annars finns monteringspunkten fortfarande i noden när programkörningen har slutförts.

  • Det går inte att montera ett ADLS Gen1-lagringskonto.

Lakehouse-verktyg

notebookutils.lakehouse tillhandahåller verktyg som är skräddarsydda för att hantera Lakehouse-objekt. Med dessa verktyg kan du enkelt skapa, hämta, uppdatera och ta bort Lakehouse-artefakter.

Översikt över metoder

Här är en översikt över tillgängliga metoder som tillhandahålls av notebookutils.lakehouse:

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

# Retrieve a Lakehouse artifact
get(name: String, workspaceId: String = ""): Artifact

# Get a Lakehouse artifact with properties
getWithProperties(name: String, workspaceId: String = ""): Artifact

# Update an existing Lakehouse artifact
update(name: String, newName: String, description: String = "", workspaceId: String = ""): Artifact

# Delete a Lakehouse artifact
delete(name: String, workspaceId: String = ""): Boolean 

# List all Lakehouse artifacts
list(workspaceId: String = "", maxResults: Int = 1000): Array[Artifact]

# List all tables in a Lakehouse artifact
listTables(lakehouse: String, workspaceId: String = "", maxResults: Int = 1000): Array[Table] 

# Starts a load table operation in a Lakehouse artifact
loadTable(loadOption: collection.Map[String, Any], table: String, lakehouse: String, workspaceId: String = ""): Array[Table]

Exempel på användning

Tänk på följande användningsexempel för att använda dessa metoder effektivt:

Skapa ett Lakehouse

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

Skaffa ett lakehouse

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

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

Uppdatering av ett Lakehouse

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

Ta bort en sjöstuga

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

Lista Lakehouses på en arbetsyta

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

Visa en lista över alla tabeller i ett Lakehouse

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

Starta en laddning av tabell i Lakehouse

notebookutils.lakehouse.loadTable(
    {
        "relativePath": "Files/myFile.csv",
        "pathType": "File",
        "mode": "Overwrite",
        "recursive": False,
        "formatOptions": {
            "format": "Csv",
            "header": True,
            "delimiter": ","
        }
    }, "table_name", "artifact_name", "optional_workspace_id")

Ytterligare information

Mer detaljerad information om varje metod och dess parametrar finns i notebookutils.lakehouse.help("methodName") funktionen.

Drifttidsverktyg

Visa information om sessionskontexten

Med notebookutils.runtime.context kan du hämta kontextinformationen för den aktuella livesessionen, inklusive anteckningsbokens namn, standard lakehouse, arbetsyteinformation, om det är en pipelinekörning osv.

notebookutils.runtime.context

Tabellen nedan beskriver egenskaperna.

Parameter Förklaring
currentNotebookName Namnet på den aktuella anteckningsboken
currentNotebookId Den unika ID:t för den aktuella notebooken
currentWorkspaceName Namnet på den aktuella arbetsytan
currentWorkspaceId ID för den aktuella arbetsytan
defaultLakehouseName Visningsnamnet för standard lakehouse, om det definieras
defaultLakehouseId ID för standard lakehouse, om det är definierat
defaultLakehouseWorkspaceName Arbetsytans namn för standardsjöhus, om det definieras
defaultLakehouseWorkspaceId Arbetsytans ID för standard-lakehouse, om den är definierad
currentRunId I en referenskörning är det aktuella kör-ID:t
parentRunId I en referenskörning med kapslade körningar är detta det överordnade körnings-ID:t
rootRunId I en referenskörning med kapslade körningar är detta rotkörningens ID
isForPipeline Om körningen är för en pipeline
isReferenceRun Om den aktuella körningen är en referenskörning
referenceTreePath Trädstrukturen för kapslade referenssekvenser, som endast används för snapshothierarkin på övervakningssidan L2.
rootNotebookId (Endast i referenskörning) ID:t för rotanteckningsboken i en referenskörning.
rootNotebookName (Endast i referenskörning) Namnet på rotanteckningsboken i en referenskörning.
rootWorkspaceId (Endast i en referenskörning) Rotanteckningsbokens arbetsyta-ID i en referenskörning.
rootWorkspaceName (Endast i referenskörning) Namnet på arbetsytan för rotanteckningsboken i en referenskörning.
activityId Livy-jobb-ID för den aktuella aktiviteten
hcRepId REPL-ID:t i läge med hög samtidighet
clusterId Identiteten för Synapse Spark-klustret
poolName Namnet på Spark-poolen som används
environmentId Miljö-ID:t där jobbet körs
environmentWorkspaceId Miljöns arbetsyte-ID
userId Användar-ID för den aktuella användaren
userName Användarnamnet för den aktuella användaren

Sessionshantering

Avbryt en interaktiv session

I stället för att klicka på stoppknappen manuellt är det ibland enklare att stoppa en interaktiv session genom att anropa ett API i koden. I sådana fall tillhandahåller vi ett API-notebookutils.session.stop() som stöder att stoppa den interaktiva sessionen via kod, den är tillgänglig för Scala och PySpark.

notebookutils.session.stop()

notebookutils.session.stop()-API:et stoppar den aktuella interaktiva sessionen asynkront i bakgrunden. Det avslutar också Spark-sessionen och frigör resurser som används av sessionen, så att de är tillgängliga för andra sessioner i samma pool.

Starta om Python-tolken

notebookutils.session-verktyget är ett sätt att starta om Python-tolken.

notebookutils.session.restartPython()

Anteckning

  • I fallet med referenskörningen av notebook startar restartPython() bara om Python-tolken för den aktuella notebook som det refereras till.
  • I sällsynta fall kan kommandot misslyckas på grund av Spark-reflektionsmekanismen. Om du lägger till ett nytt försök kan du åtgärda problemet.

Kända problem

  • När du använder körningsversion 1.2 eller högre och kör notebookutils.help() stöds inte de listade fabricClient- och PBIClient-API:erna för tillfället, men de kommer att vara tillgängliga i framtiden. Dessutom stöds inte API:et för autentiseringsuppgifter i Scala Notebooks för tillfället.

  • Python-notebooken stöder inte stop, starta om Python API när man använder notebookutils.session-verktyget för sessionshantering.

Relaterat innehåll