Delen via

NotebookUtils (voormalige MSSparkUtils) voor Fabric

  • Artikel

Notebook Utilities (NotebookUtils) is een ingebouwd pakket om u te helpen eenvoudig algemene taken uit te voeren in Fabric Notebook. U kunt NotebookUtils gebruiken om te werken met bestandssystemen, om omgevingsvariabelen op te halen, notebooks aan elkaar te koppelen en met geheimen te werken. Het NotebookUtils-pakket is beschikbaar in PySpark (Python) Scala, SparkR-notebooks en Fabric-pijplijnen.

Notitie

  • MsSparkUtils is officieel hernoemd naar NotebookUtils. De bestaande code blijft achterwaarts compatibel en veroorzaakt geen wijzigingen die fouten veroorzaken. Het wordt ten zeerste aangeraden een upgrade uit te voeren naar notebookutils om te zorgen voor continue ondersteuning en toegang tot nieuwe functies. De mssparkutils-naamruimte wordt in de toekomst buiten gebruik gesteld.
  • NotebookUtils is ontworpen voor gebruik met Spark 3.4(Runtime v1.2) en hoger. Alle nieuwe functies en updates worden exclusief ondersteund met de naamruimte notebookutils.

Hulpprogramma's voor bestandssysteem

notebookutils.fs biedt hulpprogramma's voor het werken met verschillende bestandssystemen, waaronder Azure Data Lake Storage (ADLS) Gen2 en Azure Blob Storage. Zorg ervoor dat u de toegang tot Azure Data Lake Storage Gen2 en Azure Blob Storage op de juiste manier configureert.

Voer de volgende opdrachten uit voor een overzicht van de beschikbare methoden:

notebookutils.fs.help()

Uitvoer

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 werkt op dezelfde manier met het bestandssysteem als Spark-API's. Neem notebookutils.fs.mkdirs() en Fabric lakehouse-gebruik, bijvoorbeeld:

Gebruik Relatief pad van HDFS-hoofdmap Absoluut pad voor ABFS-bestandssysteem Absoluut pad voor lokaal bestandssysteem in stuurprogrammaknooppunt
Niet-standaard lakehouse Niet ondersteund notebookutils.fs.mkdirs("abfss://< container_name>@<storage_account_name.dfs.core.windows.net/>< new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Standaard lakehouse Map onder Bestanden of Tabellen: 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>")

Bestanden in een lijst weergeven

Als u de inhoud van een map wilt weergeven, gebruikt u notebookutils.fs.ls('Uw mappad'). Voorbeeld:

notebookutils.fs.ls("Files/tmp") # works with the default lakehouse files using relative path 
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # based on ABFS file system 
notebookutils.fs.ls("file:/tmp")  # based on local file system of driver node

Bestandseigenschappen weergeven

Deze methode retourneert bestandseigenschappen, waaronder bestandsnaam, bestandspad, bestandsgrootte en of het een map en een bestand is.

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

Nieuwe map maken

Met deze methode maakt u de opgegeven map als deze niet bestaat en maakt u eventuele benodigde bovenliggende mappen.

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

Bestand kopiëren

Met deze methode wordt een bestand of map gekopieerd en worden kopieeractiviteiten in bestandssystemen ondersteund.

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

Performant kopieerbestand

Deze methode biedt een efficiëntere benadering voor het kopiëren of verplaatsen van bestanden, met name bij het verwerken van grote gegevensvolumes. Voor verbeterde prestaties op Fabric is het raadzaam om te gebruiken fastcp als vervanging voor de traditionele cp methode.

Notitie

notebookutils.fs.fastcp() biedt geen ondersteuning voor het kopiëren van bestanden in OneLake tussen regio's. In dit geval kunt u in plaats daarvan gebruiken notebookutils.fs.cp() .

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

Voorbeeld van bestandsinhoud

Deze methode retourneert maximaal de eerste 'maxBytes' bytes van het opgegeven bestand als een tekenreeks die is gecodeerd in UTF-8.

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

Bestand verplaatsen

Met deze methode wordt een bestand of map verplaatst en worden verplaatsingen tussen bestandssystemen ondersteund.

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.

Bestand schrijven

Met deze methode wordt de opgegeven tekenreeks weggeschreven naar een bestand, gecodeerd in 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

Inhoud toevoegen aan een bestand

Met deze methode wordt de opgegeven tekenreeks toegevoegd aan een bestand, gecodeerd in 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

Notitie

  • notebookutils.fs.append() en notebookutils.fs.put() bieden geen ondersteuning voor gelijktijdig schrijven naar hetzelfde bestand vanwege een gebrek aan atomiciteitsgaranties.
  • Wanneer u de notebookutils.fs.append API in een for lus gebruikt om naar hetzelfde bestand te schrijven, wordt u aangeraden een sleep instructie rond 0,5s~1s toe te voegen tussen de terugkerende schrijfbewerkingen. Dit komt doordat de interne notebookutils.fs.append bewerking van de flush API asynchroon is, dus een korte vertraging zorgt voor gegevensintegriteit.

Bestand of map verwijderen

Met deze methode wordt een bestand of map verwijderd.

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

Map koppelen/ontkoppelen

Meer informatie over gedetailleerd gebruik in bestandskoppeling en ontkoppelen.

Hulpprogramma's voor notitieblokken

Gebruik de hulpprogramma's voor notebooks om een notebook uit te voeren of een notebook af te sluiten met een waarde. Voer de volgende opdracht uit om een overzicht te krijgen van de beschikbare methoden:

notebookutils.notebook.help()

Uitvoer:


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.

Notitie

Hulpprogramma's voor notebooks zijn niet van toepassing op Apache Spark-taakdefinities (SJD).

Verwijzen naar een notitieblok

Deze methode verwijst naar een notebook en retourneert de afsluitwaarde. U kunt geneste functie-aanroepen in een notebook interactief of in een pijplijn uitvoeren. Het notebook waarnaar wordt verwezen, wordt uitgevoerd in de Spark-pool van het notebook dat deze functie aanroept.

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

Voorbeeld:

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

Fabric Notebook ondersteunt ook verwijzingen naar notebooks in meerdere werkruimten door de werkruimte-id op te geven.

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

U kunt de koppeling naar de momentopname van de verwijzingsuitvoering openen in de celuitvoer. Met de momentopname worden de resultaten van de codeuitvoering vastgelegd en kunt u eenvoudig fouten opsporen in een verwijzingsuitvoering.

Schermopname van het resultaat van de verwijzingsuitvoering.

Schermopname van een voorbeeld van een momentopname.

Notitie

  • Het referentienotebook voor meerdere werkruimten wordt ondersteund door runtimeversie 1.2 en hoger.
  • Als u de bestanden onder Notebook Resource gebruikt, gebruikt notebookutils.nbResPath u deze in het notitieblok waarnaar wordt verwezen om ervoor te zorgen dat deze verwijst naar dezelfde map als de interactieve uitvoering.

Naslaginformatie over het parallel uitvoeren van meerdere notebooks

Belangrijk

Deze functie is beschikbaar als preview-versie.

Met de methode notebookutils.notebook.runMultiple() kunt u meerdere notebooks parallel of met een vooraf gedefinieerde topologische structuur uitvoeren. De API maakt gebruik van een implementatiemechanisme met meerdere threads binnen een Spark-sessie, wat betekent dat het referentienotebook de rekenresources deelt.

Met notebookutils.notebook.runMultiple()kunt u het volgende doen:

  • Voer meerdere notebooks tegelijk uit, zonder te wachten tot elke notebook is voltooid.

  • Geef de afhankelijkheden en de volgorde van uitvoering voor uw notebooks op met behulp van een eenvoudige JSON-indeling.

  • Optimaliseer het gebruik van Spark-rekenresources en verlaag de kosten van uw Fabric-projecten.

  • Bekijk de momentopnamen van elke notebookuitvoeringsrecord in de uitvoer en foutopsporing/bewaak uw notebooktaken gemakkelijk.

  • Haal de afsluitwaarde van elke leidinggevende activiteit op en gebruik deze in downstreamtaken.

U kunt ook proberen de notebookutils.notebook.help("runMultiple") uit te voeren om het voorbeeld en het gedetailleerde gebruik te vinden.

Hier volgt een eenvoudig voorbeeld van het parallel uitvoeren van een lijst met notebooks met behulp van deze methode:


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

Het uitvoerresultaat van het hoofdnotebook is als volgt:

Schermopname van een verwijzing naar een lijst met notitieblokken.

Hier volgt een voorbeeld van het uitvoeren van notebooks met topologische structuur met behulp van notebookutils.notebook.runMultiple(). Gebruik deze methode om eenvoudig notebooks te organiseren via een code-ervaring.

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

Het uitvoerresultaat van het hoofdnotebook is als volgt:

Schermopname van een lijst met notebooks met parameters.

We bieden ook een methode om te controleren of de DAG juist is gedefinieerd.

notebookutils.notebook.validateDAG(DAG)

Notitie

  • De mate van parallelle uitvoering van meerdere notebooks is beperkt tot de totale beschikbare rekenresource van een Spark-sessie.
  • De bovengrens voor notitieblokactiviteiten of gelijktijdige notitieblokken is 50. Het overschrijden van deze limiet kan leiden tot stabiliteits- en prestatieproblemen vanwege een hoog rekenresourcegebruik. Als er problemen optreden, kunt u overwegen notebooks te scheiden in meerdere runMultiple aanroepen of de gelijktijdigheid te verminderen door het gelijktijdigheidsveld in de DAG-parameter aan te passen.
  • De standaardtime-out voor de hele DAG is 12 uur en de standaardtime-out voor elke cel in het onderliggende notitieblok is 90 seconden. U kunt de time-out wijzigen door de time-outInSeconds en time-outPerCellInSeconds in te stellen in de DAG-parameter.

Een notitieblok afsluiten

Met deze methode wordt een notebook afgesloten met een waarde. U kunt geneste functie-aanroepen in een notebook interactief of in een pijplijn uitvoeren.

  • Wanneer u een exit() -functie aanroept vanuit een notebook, genereert het Fabric-notebook een uitzondering, slaat het uitvoeren van volgende cellen over en blijft de Spark-sessie actief.

  • Wanneer u een notebook indeelt in een pijplijn die een exit() -functie aanroept, wordt de notebookactiviteit geretourneerd met een afsluitwaarde, wordt de pijplijnuitvoering voltooid en wordt de Spark-sessie gestopt.

  • Wanneer u een exit() -functie aanroept in een notebook waarnaar wordt verwezen, stopt Fabric Spark de verdere uitvoering van het notitieblok waarnaar wordt verwezen en gaat u door met het uitvoeren van de volgende cellen in het hoofdnotitieblok waarmee de run() -functie wordt aangeroepen. Bijvoorbeeld: Notebook1 heeft drie cellen en roept een exit() -functie aan in de tweede cel. Notebook2 heeft vijf cellen en aanroepen worden uitgevoerd (notebook1) in de derde cel. Wanneer u Notebook2 uitvoert, stopt Notebook1 in de tweede cel wanneer u de exit() -functie bereikt. Notebook2 blijft de vierde cel en vijfde cel uitvoeren.

notebookutils.notebook.exit("value string")

Notitie

Met de functie exit() wordt de huidige celuitvoer overschreven om te voorkomen dat de uitvoer van andere code-instructies verloren gaat. Roep notebookutils.notebook.exit() een afzonderlijke cel aan.

Voorbeeld:

Voorbeeld1 notebook met de volgende twee cellen:

  • Cel 1 definieert een invoerparameter met de standaardwaarde ingesteld op 10.

  • Cel 2 sluit het notitieblok af met invoer als afsluitwaarde.

Schermopname van een voorbeeldnotitieblok van de afsluitfunctie.

U kunt het voorbeeld1 uitvoeren in een ander notebook met standaardwaarden:

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

Uitvoer:

Notebook is executed successfully with exit value 10

U kunt het voorbeeld1 uitvoeren in een ander notebook en de invoerwaarde instellen als 20:

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

Uitvoer:

Notebook is executed successfully with exit value 20

Notebookartefacten beheren

notebookutils.notebook biedt gespecialiseerde hulpprogramma's voor het programmatisch beheren van Notebook-items. Met deze API's kunt u eenvoudig notebookitems maken, ophalen, bijwerken en verwijderen.

Bekijk de volgende gebruiksvoorbeelden om deze methoden effectief te gebruiken:

Een notitieblok maken

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

Inhoud van een notitieblok downloaden

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

Een notitieblok bijwerken

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

Een notitieblok verwijderen

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

Notitieblokken in een werkruimte weergeven

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

Hulpprogramma's voor referenties

U kunt de hulpprogramma's voor referenties gebruiken om toegangstokens op te halen en geheimen in een Azure Key Vault te beheren.

Voer de volgende opdracht uit om een overzicht te krijgen van de beschikbare methoden:

notebookutils.credentials.help()

Uitvoer:

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 ophalen

getToken retourneert een Microsoft Entra-token voor een bepaalde doelgroep en naam (optioneel). In de volgende lijst ziet u de momenteel beschikbare doelgroepsleutels:

  • Resource voor opslagdoelgroep: 'opslag'
  • Power BI-resource: 'pbi'
  • Azure Key Vault-resource: 'keyvault'
  • Synapse RTA KQL DB-resource: 'kusto'

Voer de volgende opdracht uit om het token op te halen:

notebookutils.credentials.getToken('audience Key')

Geheim ophalen met gebruikersreferenties

getSecret retourneert een Azure Key Vault-geheim voor een bepaald Azure Key Vault-eindpunt en een geheime naam met behulp van gebruikersreferenties.

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

Bestandskoppeling en ontkoppelen

Fabric ondersteunt de volgende koppelscenario's in het Microsoft Spark Utilities-pakket. U kunt de API's voor koppelen, ontkoppelen, getMountPath()en mounts() gebruiken om externe opslag (ADLS Gen2) te koppelen aan alle werkende knooppunten (stuurprogrammaknooppunt en werkknooppunten). Nadat het opslagkoppelingspunt is ingesteld, gebruikt u de API voor het lokale bestand om toegang te krijgen tot gegevens alsof deze zijn opgeslagen in het lokale bestandssysteem.

Een ADLS Gen2-account koppelen

In het volgende voorbeeld ziet u hoe u Azure Data Lake Storage Gen2 koppelt. Het koppelen van Blob Storage werkt op dezelfde manier.

In dit voorbeeld wordt ervan uitgegaan dat u één Data Lake Storage Gen2-account met de naam storegen2 hebt en dat het account één container heeft met de naam mycontainer die u wilt koppelen aan /test in uw Spark-notebooksessie.

Schermopname die laat zien waar een container moet worden gekoppeld.

Als u de container met de naam mycontainer wilt koppelen, moet notebookutils eerst controleren of u gemachtigd bent om toegang te krijgen tot de container. Momenteel ondersteunt Fabric twee verificatiemethoden voor de triggerkoppelingsbewerking: accountKey en sastoken.

Koppelen via shared access Signature-token of accountsleutel

NotebookUtils biedt ondersteuning voor het expliciet doorgeven van een accountsleutel of SAS-token (Shared Access Signature) als parameter om het doel te koppelen.

Om veiligheidsredenen raden we u aan accountsleutels of SAS-tokens op te slaan in Azure Key Vault (zoals in de volgende schermopname wordt weergegeven). U kunt ze vervolgens ophalen met behulp van de notebookutils.credentials.getSecret-API . Zie Over door Azure Key Vault beheerde opslagaccountsleutels voor Azure Key Vault voor meer informatie over Azure Key Vault.

Schermopname die laat zien waar geheimen zijn opgeslagen in een Azure Key Vault.

Voorbeeldcode voor de accountKey-methode :

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

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

Parameters koppelen:

  • fileCacheTimeout: Blobs worden standaard gedurende 120 seconden in de lokale tijdelijke map opgeslagen. Gedurende deze tijd controleert blobfuse niet of het bestand up-to-date is of niet. De parameter kan worden ingesteld om de standaardtime-outtijd te wijzigen. Wanneer meerdere clients tegelijkertijd bestanden wijzigen, om inconsistenties tussen lokale en externe bestanden te voorkomen, raden we u aan de cachetijd te verkorten of zelfs te wijzigen in 0 en altijd de meest recente bestanden van de server te krijgen.
  • time-out: de time-out voor de koppelbewerking is standaard 120 seconden. De parameter kan worden ingesteld om de standaardtime-outtijd te wijzigen. Als er te veel uitvoerders zijn of wanneer er een time-out optreedt voor koppelen, raden we u aan de waarde te verhogen.

U kunt deze parameters als volgt gebruiken:

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

Notitie

Voor beveiligingsdoeleinden is het raadzaam om te voorkomen dat referenties rechtstreeks in code worden ingesloten. Als u uw referenties verder wilt beveiligen, worden alle geheimen die worden weergegeven in notebookuitvoer, opnieuw uitgevoerd. Zie Geheime redaction voor meer informatie.

Een lakehouse koppelen

Voorbeeldcode voor het koppelen van een lakehouse aan /<mount_name>:

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

Toegang tot bestanden onder het koppelpunt met behulp van de notebookutils fs-API

Het belangrijkste doel van de koppelingsbewerking is om klanten toegang te geven tot de gegevens die zijn opgeslagen in een extern opslagaccount met een API voor het lokale bestandssysteem. U kunt de gegevens ook openen met behulp van de notebookutils fs-API met een gekoppeld pad als parameter. Deze padindeling is iets anders.

Stel dat u de Mycontainer mycontainer van de Data Lake Storage Gen2-container hebt gekoppeld aan /test met behulp van de koppelings-API. Wanneer u toegang krijgt tot de gegevens met een API voor een lokaal bestandssysteem, ziet de padindeling er als volgt uit:

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

Als u toegang wilt krijgen tot de gegevens met behulp van de notebookutils fs-API, raden we u aan om getMountPath() te gebruiken om het juiste pad op te halen:

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

  • Mappen weergeven:

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

  • Bestandsinhoud lezen:

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

  • Een map maken:

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

Toegang tot bestanden onder het koppelpunt via lokaal pad

U kunt de bestanden eenvoudig lezen en schrijven in koppelpunt met behulp van het standaardbestandssysteem. Hier volgt een Python-voorbeeld:

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

Bestaande koppelpunten controleren

U kunt notebookutils.fs.mounts() API gebruiken om alle bestaande koppelingspuntgegevens te controleren:

notebookutils.fs.mounts()

Het koppelpunt ontkoppelen

Gebruik de volgende code om het koppelpunt los te koppelen (/test in dit voorbeeld):

notebookutils.fs.unmount("/test")

Bekende beperkingen

  • De huidige koppeling is een configuratie op taakniveau; U wordt aangeraden de koppelings-API te gebruiken om te controleren of er een koppelpunt bestaat of niet beschikbaar is.

  • Het ontkoppelingsmechanisme wordt niet automatisch toegepast. Wanneer de uitvoering van de toepassing is voltooid, moet u expliciet een ontkoppelde API in uw code aanroepen om het koppelpunt los te koppelen en de schijfruimte vrij te geven. Anders bestaat het koppelpunt nog steeds in het knooppunt nadat de uitvoering van de toepassing is voltooid.

  • Het koppelen van een ADLS Gen1-opslagaccount wordt niet ondersteund.

Lakehouse-hulpprogramma's

notebookutils.lakehouse biedt hulpprogramma's die zijn afgestemd op het beheren van Lakehouse-items. Met deze hulpprogramma's kunt u moeiteloos Lakehouse-artefacten maken, ophalen, bijwerken en verwijderen.

Overzicht van methoden

Hieronder vindt u een overzicht van de beschikbare methoden die worden geboden door 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]

Voorbeelden van gebruik

Bekijk de volgende gebruiksvoorbeelden om deze methoden effectief te gebruiken:

Een Lakehouse maken

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

Een Lakehouse krijgen

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

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

Een Lakehouse bijwerken

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

Een Lakehouse verwijderen

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

Lakehouses in een werkruimte vermelden

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

Alle tabellen in een Lakehouse weergeven

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

Een laadtabelbewerking starten in een 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")

Aanvullende informatie

Gebruik de functie voor meer gedetailleerde informatie over elke methode en de notebookutils.lakehouse.help("methodName") bijbehorende parameters.

Runtimehulpprogramma's

De sessiecontextgegevens weergeven

Met notebookutils.runtime.context u kunt de contextinformatie van de huidige livesessie ophalen, waaronder de naam van het notitieblok, de standaard lakehouse, werkruimtegegevens, als het een pijplijnuitvoering is, enzovoort.

notebookutils.runtime.context

Sessiebeheer

Een interactieve sessie stoppen

In plaats van handmatig op de knop Stoppen te klikken, is het soms handiger om een interactieve sessie te stoppen door een API aan te roepen in de code. In dergelijke gevallen bieden we een API-notebookutils.session.stop() ter ondersteuning van het stoppen van de interactieve sessie via code, deze is beschikbaar voor Scala en PySpark.

notebookutils.session.stop()

nl-NL: notebookutils.session.stop() API stopt de huidige interactieve sessie asynchroon op de achtergrond, het stopt de Spark-sessie en geeft de bronnen vrij die door de sessie worden bezet, zodat ze beschikbaar zijn voor andere sessies in dezelfde pool.

De Python-interpreter opnieuw starten

het hulpprogramma notebookutils.session biedt een manier om de Python-interpreter opnieuw op te starten.

notebookutils.session.restartPython()

Notitie

  • In het geval van een notebookreferentie bij uitvoeren, wordt restartPython() alleen de Python-interpreter van het genoemde huidige notebook opnieuw opgestart.
  • In zeldzame gevallen kan de opdracht mislukken vanwege het Spark-weerspiegelingsmechanisme. Het toevoegen van een herhaalde poging kan het probleem verminderen.

Bekend probleem

  • Wanneer u runtimeversie boven 1.2 gebruikt en uitvoert notebookutils.help(), worden de vermelde fabricClient-, PBIClient-API's voorlopig niet ondersteund, beschikbaar in de verdere versie. Daarnaast wordt de Referentie-API voorlopig niet ondersteund in Scala-notebooks.

  • Het Python-notebook ondersteunt de stopPython- en restartPython-API's niet wanneer u het hulpprogramma notebookutils.session gebruikt voor sessiebeheer.

Gerelateerde inhoud