NotebookUtils (antiguo MSSparkUtils) para Fabric

Artículo
07/26/2024

Las utilidades de notebook (NotebookUtils) son un paquete integrado que le ayudará a realizar fácilmente tareas comunes en Fabric Notebook. Puede usar NotebookUtils para trabajar con sistemas de archivos, obtener variables de entorno, encadenar cuadernos entre sí y trabajar con secretos. El paquete NotebookUtils está disponible en PySpark (Python) Scala, cuadernos de SparkR y canalizaciones de Fabric.

Nota:

MsSparkUtils ha cambiado oficialmente el nombre a NotebookUtils. El código existente seguirá siendo compatible con versiones anteriores y no provocará cambios importantes. Se recomienda encarecidamente actualizar a notebookutils para garantizar el soporte y el acceso continuos a las nuevas características. El espacio de nombres mssparkutils se retirará en el futuro.
NotebookUtils está diseñado para funcionar con Spark 3.4(Runtime v1.2) y versiones posteriores. Todas las nuevas características y actualizaciones se admitirán exclusivamente con el espacio de nombres notebookutils en el futuro.

Utilidades del sistema de archivos

notebookutils.fs ofrece utilidades para trabajar con varios sistemas de archivos, como Azure Data Lake Storage (ADLS) Gen2 y Azure Blob Storage. Asegúrese de configurar el acceso a Azure Data Lake Storage Gen2 y Azure Blob Storage adecuadamente.

Ejecute los siguientes comandos para obtener información general sobre los métodos disponibles:

notebookutils.fs.help()

Salida

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 funciona con el sistema de archivos de la misma manera que las API de Spark. Tomemos como ejemplo notebookutils.fs.mkdirs() y el uso del almacén de lago de Fabric:

Uso	Ruta de acceso relativa desde la raíz de HDFS	Ruta de acceso absoluta para el sistema de archivos ABFS	Ruta de acceso absoluta para el sistema de archivos local en el nodo del driver
Lakehouse no predeterminado	No compatible	notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")	notebookutils.fs.mkdirs("file:/<new_dir>")
Lakehouse predeterminado	Directorio en "Files" o "Tables": 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>")

Enumerar archivos

Para enumerar el contenido de un directorio, use notebookutils.fs.ls('Your directory path'). Por ejemplo:

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

Vea las propiedades del archivo.

Este método devuelve las propiedades del archivo, incluido el nombre, la ruta de acceso, el tamaño y si es un directorio o un archivo.

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

Creación de un directorio

Este método crea el directorio especificado si no existe y también crea los directorios principales necesarios.

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

Copiar archivo

Este método copia un archivo o directorio y admite la actividad de copia entre sistemas de archivos.

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

Copiar archivos de un modo más eficaz

Este método ofrece un enfoque más eficaz para copiar o mover archivos, especialmente cuando se trabaja con grandes volúmenes de datos. Para mejorar el rendimiento en Fabric, es aconsejable utilizar fastcp como sustituto del método tradicional cp.

Nota:

notebookutils.fs.fastcp() no admite la copia de archivos en OneLake entre regiones. En este caso, puede usar notebookutils.fs.cp() en su lugar.

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

Vista previa del contenido del archivo

Este método devuelve hasta los primeros "maxBytes" bytes del archivo especificado como una cadena codificada en UTF-8.

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

Mover archivo

Este método mueve un archivo o directorio y admite movimientos entre sistemas de archivos.

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.

Escritura de archivos

Este método escribe la cadena especificada en un archivo, codificada en formato 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

Adición de contenido a un archivo

Este método anexa la cadena especificada a un archivo, codificada en formato 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

Nota:

notebookutils.fs.append() y notebookutils.fs.put() no admiten la escritura simultánea en el mismo archivo debido a la falta de garantías de atomicidad.
Al usar la API de notebookutils.fs.append en un bucle de for para escribir en el mismo archivo, se recomienda agregar una instrucción sleep de alrededor de 0,5s~1s entre las escrituras periódicas. Esto se debe a que la operación flush interna de la API de notebookutils.fs.append es asincrónica, por lo que un breve retraso ayuda a garantizar la integridad de los datos.

Eliminación de un archivo o directorio

Este método quita un archivo o directorio.

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

Montaje o desmontaje del directorio

Obtenga más información sobre el uso detallado en Montaje y desmontaje de archivos.

Utilidades de cuaderno

Use las utilidades de cuaderno para ejecutar un cuaderno o salir de uno con un valor. Ejecute el siguiente comando para obtener información general sobre los métodos disponibles:

notebookutils.notebook.help()

Salida:


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.

Nota:

Las utilidades de cuaderno no son aplicables a las definiciones de trabajo de Apache Spark (SJD).

Referencia a un cuaderno

Este método hace referencia a un cuaderno y devuelve su valor de salida. Puede ejecutar llamadas de función anidadas en un cuaderno de manera interactiva o en una canalización. El cuaderno al que se hace referencia se ejecuta en el grupo de Spark del cuaderno que llama a esta función.

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

Por ejemplo:

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

El cuaderno de Fabric también admite la referencia a cuadernos en varias áreas de trabajo especificando el ID del área de trabajo.

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

Puede abrir el vínculo de instantánea de la ejecución de referencia en la salida de la celda. La instantánea captura los resultados de la ejecución del código y permite depurar fácilmente una ejecución de referencia.

Nota:

El cuaderno de referencia entre áreas de trabajo es compatible con la versión 1.2 y posteriores del tiempo de ejecución.
Si utiliza los archivos en Recurso de cuaderno, use notebookutils.nbResPath en el cuaderno al que se hace referencia para asegurarse de que apunta a la misma carpeta que la ejecución interactiva.

Referencia que ejecuta varios cuadernos en paralelo

Importante

Esta característica se encuentra en versión preliminar.

El método notebookutils.notebook.runMultiple() permite ejecutar varios cuadernos en paralelo o con una estructura topológica predefinida. La API utiliza un mecanismo de implementación de varios subprocesos dentro de una sesión de Spark, lo que significa que los recursos de proceso se comparten mediante las ejecuciones del cuaderno de referencia.

Con notebookutils.notebook.runMultiple(), puede:

Ejecute varios cuadernos simultáneamente, sin esperar a que finalice cada uno.
Especifique las dependencias y el orden de ejecución de los cuadernos mediante un formato JSON simple.
Optimice el uso de recursos de proceso de Spark y reduzca el costo de los proyectos de Fabric.
Vea las instantáneas de cada registro de ejecución de cuadernos en la salida y depure o supervise las tareas del cuaderno de forma cómoda.
Obtenga el valor de salida de cada actividad ejecutiva y úselos en tareas descendentes.

También puede intentar ejecutar notebookutils.notebook.help("runMultiple") para buscar el ejemplo y el uso detallado.

Este es un ejemplo sencillo de ejecutar una lista de cuadernos en paralelo mediante este método:


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

El resultado de la ejecución del cuaderno raíz es el siguiente:

A continuación se muestra un ejemplo de ejecución de cuadernos con estructura topológica mediante notebookutils.notebook.runMultiple(). Use este método para organizar fácilmente cuadernos a través de una experiencia de código.

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

El resultado de la ejecución del cuaderno raíz es el siguiente:

También proporcionamos un método para comprobar si el DAG está definido correctamente.

notebookutils.notebook.validateDAG(DAG)

Nota:

El grado de paralelismo de la ejecución de varios cuadernos está restringido al recurso de proceso total disponible de una sesión de Spark.
El límite superior de actividades de cuadernos o cuadernos simultáneos es de 50. Superar este límite puede provocar problemas de estabilidad y rendimiento debido a un uso elevado de recursos de proceso. Si surgen problemas, considere la posibilidad de separar cuadernos en varias llamadas de runMultiple o reducir la simultaneidad ajustando el campo de simultaneidad en el parámetro DAG.
El tiempo de expiración predeterminado para el DAG completo es de 12 horas y el tiempo de expiración predeterminado para cada celda del cuaderno secundario es de 90 segundos. Puede cambiar el tiempo de expiración definiendo los campos timeoutInSeconds y timeoutPerCellInSeconds en el parámetro DAG.

Salida de un cuaderno

Este método sale de un cuaderno con un valor. Puede ejecutar llamadas de función anidadas en un cuaderno de manera interactiva o en una canalización.

Cuando llama a una función exit() desde un cuaderno de forma interactiva, el cuaderno de Fabric generará una excepción, omitirá la ejecución de celdas de subsecuencia y mantendrá activa la sesión de Spark.
Cuando se orquesta un cuaderno en una canalización que llama a una función exit(), la actividad de cuaderno vuelve con un valor de salida, completa la ejecución de canalización y detiene la sesión de Spark.
Cuando se llama a una función exit() en un cuaderno al que se está haciendo referencia, Fabric Spark detendrá la ejecución posterior del cuaderno al que se hace referencia y continuará ejecutando las siguientes celdas en el cuaderno principal que llama a la función run(). Por ejemplo: Notebook1 tiene tres celdas y llama a una función exit() en la segunda celda. Notebook2 tiene cinco celdas y llama a run(notebook1) en la tercera celda. Al ejecutar Notebook2, Notebook1 se detiene en la segunda celda al pulsar la función exit(). Notebook2 continua con la ejecución de su cuarta y quinta celda.

notebookutils.notebook.exit("value string")

Nota:

La función exit() sobrescribirá la salida de celda actual para evitar perder la salida de otras instrucciones de código, llame a notebookutils.notebook.exit() en una celda independiente.

Por ejemplo:

El cuaderno Sample1 con las dos celdas siguientes:

La celda 1 define un parámetro input con un valor predeterminado establecido en 10.
La celda 2 sale del cuaderno con el valor de input como valor de salida.

Puede ejecutar Sample1 en otro cuaderno con los valores predeterminados:

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

Salida:

Notebook is executed successfully with exit value 10

Puede ejecutar Sample1 en otro cuaderno y establecer el valor de input en 20:

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

Salida:

Notebook is executed successfully with exit value 20

Administración de artefactos de cuadernos

notebookutils.notebook proporciona utilidades especializadas para administrar elementos de Notebook mediante programación. Estas API pueden ayudarle a crear, obtener, actualizar y eliminar elementos de Notebook fácilmente.

Para usar estos métodos de forma eficaz, tenga en cuenta los ejemplos de utilización siguientes:

Creación de un cuaderno

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

Obtener contenido de un cuaderno

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

Actualización de un cuaderno

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

Eliminación de un cuaderno

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

Enumeración de cuadernos en un área de trabajo

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

Utilidades de credenciales

Puede usar las utilidades de credenciales para obtener los tokens de acceso y administrar los secretos en Azure Key Vault.

Ejecute el siguiente comando para obtener información general sobre los métodos disponibles:

notebookutils.credentials.help()

Salida:

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

Obtener el token

getToken devuelve un token de Microsoft Entra para una audiencia y un nombre determinado (opcional). En la lista siguiente se muestran las claves de público disponibles actualmente:

Recurso de público de almacenamiento: "storage"
Recursos de Power BI: "pbi"
Recurso de Azure Key Vault: "keyvault"
Recurso de base de datos KQL de Synapse RTA: "kusto"

Ejecute el siguiente comando para obtener el token:

notebookutils.credentials.getToken('audience Key')

Obtención del secreto con las credenciales de usuario

getSecret devuelve un secreto de Azure Key Vault para un punto de conexión y un nombre de secreto de Azure Key Vault determinados mediante las credenciales del usuario.

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

Montaje y desmontaje de archivos

Fabric admite los siguientes escenarios de montaje en el paquete de utilidades de Microsoft Spark. Puede usar las API mount, unmount, getMountPath() y mounts() para adjuntar almacenamiento remoto (ADLG Gen2) a todos los nodos de trabajo (nodo de driver y nodos de trabajo). Una vez instalado el punto de montaje de almacenamiento, utilice la API de archivos locales para acceder a los datos como si estuvieran almacenados en el sistema de archivos local.

Montaje de una cuenta de ADLS Gen2

En el ejemplo siguiente se muestra cómo montar Azure Data Lake Storage Gen2. El montaje de Blob Storage funciona de forma similar.

En este ejemplo se supone que tiene una cuenta de Data Lake Storage Gen2 denominada storegen2 y que la cuenta tiene un contenedor denominado mycontainer que desea montar en /test en la sesión de Spark del cuaderno.

Para montar el contenedor llamado mycontainer, notebookutils primero necesita comprobar si tiene permiso para acceder al contenedor. Actualmente, Fabric admite dos métodos de autenticación para la operación de montaje del desencadenador: accountKey y sastoken.

Montaje con un token de firma de acceso compartido o una clave de cuenta

NotebookUtils permite pasar explícitamente una clave de cuenta o firma de acceso compartido (SAS) como parámetro para montar el destino.

Por motivos de seguridad, se recomienda almacenar las claves de cuenta o los tokens de SAS en Azure Key Vault (como se muestra en la siguiente captura de pantalla). A continuación, puede recuperarlos mediante la API notebookutils.credentials.getSecret API. Para obtener más información sobre Azure Key Vault, consulte Acerca de las claves de cuenta de almacenamiento administradas de Azure Key Vault.

Código de ejemplo para el método 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}
)

Código de ejemplo para 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}
)

Parámetros de montaje:

fileCacheTimeout: los blobs se almacenarán en caché en la carpeta temporal local durante 120 segundos de forma predeterminada. Durante este tiempo, blobfuse no comprobará si el archivo está actualizado o no. El parámetro se puede establecer para cambiar el tiempo de espera predeterminado. Cuando varios clientes modifican archivos al mismo tiempo, para evitar incoherencias entre archivos locales y remotos, se recomienda acortar el tiempo de caché o incluso cambiarlo a 0 y obtener siempre los archivos más recientes del servidor.
timeout: el tiempo de espera de la operación de montaje es de 120 segundos de forma predeterminada. El parámetro se puede establecer para cambiar el tiempo de espera predeterminado. Cuando hay demasiados ejecutores o cuando se agota el tiempo de espera de montaje, se recomienda aumentar el valor.

Puede usar estos parámetros de la siguiente manera:

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

Nota:

A efectos de seguridad, se recomienda evitar la inserción de credenciales directamente en el código. Para proteger aún más las credenciales, se censurarán los secretos mostrados en las salidas del cuaderno. Para más información, consulte el artículo sobre redacción de secretos.

Cómo montar un almacén de lago

Código de ejemplo para montar un almacén de lago de datos en /<mount_name>:

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

Acceso a los archivos del punto de montaje por medio de la API notebookutils fs

El objetivo principal de la operación de montaje es permitir a los clientes acceder a los datos almacenados en una cuenta de almacenamiento remoto con una API del sistema de archivos local. También puede acceder a los datos por medio de la API notebookutils fs con una ruta de acceso montada como parámetro. Este formato de ruta de acceso es un poco diferente.

Supongamos que ha montado el contenedor de Data Lake Storage Gen2 mycontainer en /test utilizando la API de montaje. Cuando accede a los datos con la API del sistema de archivos local, el formato de la ruta de acceso es como el siguiente:

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

Cuando quiera acceder a los datos mediante la API notebookutils fs, se recomienda usar getMountPath() para obtener la ruta de acceso precisa:

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

Enumerar directorios:

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

Leer el contenido de archivos:

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

Crear un directorio:

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

Acceso a los archivos en el punto de montaje a través de la ruta de acceso local

Puede leer y escribir fácilmente los archivos en el punto de montaje mediante el sistema de archivos estándar. Este es un ejemplo de Python:

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

Cómo comprobar los puntos de montaje existentes

Puede usar la API notebookutils.fs.mounts() para comprobar toda la información existente sobre los puntos de montaje:

notebookutils.fs.mounts()

Desmontaje del punto de montaje.

Use el siguiente código para desmontar el punto de montaje (/test en este ejemplo):

notebookutils.fs.unmount("/test")

Restricciones conocidas

El montaje actual es una configuración de nivel de trabajo; se recomienda usar las API de montajes para comprobar si existe un punto de montaje o no está disponible.
El mecanismo de desmontaje no es automático. Cuando termine la ejecución de la aplicación, para desmontar el punto de montaje y liberar el espacio en disco, debe llamar explícitamente a una API de desmontaje en el código. De lo contrario, el punto de montaje seguirá existiendo en el nodo cuando termine la ejecución de la aplicación.
No se admite el montaje de una cuenta de almacenamiento de ADLS Gen1.

Utilidades de Lakehouse

notebookutils.lakehouse proporciona utilidades adaptadas específicamente para administrar elementos de Lakehouse. Estas utilidades le permiten crear, obtener, actualizar y eliminar artefactos de Lakehouse sin esfuerzo.

Información general de los métodos

A continuación se muestra información general de los métodos disponibles proporcionados por 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]

Ejemplos de uso

Para usar estos métodos de forma eficaz, tenga en cuenta los ejemplos de utilización siguientes:

Creación de un Lakehouse

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

Obtención de un Lakehouse

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

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

Actualización de un Lakehouse

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

Eliminación de un Lakehouse

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

Enumeración de Lakehouses en un área de trabajo

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

Enumeración de todas las tablas de una instancia de Lakehouse

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

Inicio de una operación de tabla de carga en una instancia de 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")

Información adicional

Para obtener información más detallada sobre cada método y sus parámetros, utilice la función notebookutils.lakehouse.help("methodName").

Utilidades en tiempo de ejecución

Mostrar la información de contexto de sesión

Con notebookutils.runtime.context puede obtener la información de contexto de la sesión activa actual, incluido el nombre del cuaderno, el almacén de lago predeterminado, la información del área de trabajo, si se trata de una ejecución de canalización, etc.

notebookutils.runtime.context

Problema conocido

Al usar la versión en tiempo de ejecución anterior a 1.2 y ejecutar notebookutils.help(), las API fabricClient y PBIClient enumeradas no se admiten por ahora; estarán disponibles posteriormente. Además, la API de credenciales no se admite por ahora en cuadernos de Scala.

Compartir a través de

NotebookUtils (antiguo MSSparkUtils) para Fabric

Utilidades del sistema de archivos

Enumerar archivos

Vea las propiedades del archivo.

Creación de un directorio

Copiar archivo

Copiar archivos de un modo más eficaz

Vista previa del contenido del archivo

Mover archivo

Escritura de archivos

Adición de contenido a un archivo

Eliminación de un archivo o directorio

Montaje o desmontaje del directorio

Utilidades de cuaderno

Referencia a un cuaderno

Referencia que ejecuta varios cuadernos en paralelo

Salida de un cuaderno

Administración de artefactos de cuadernos

Creación de un cuaderno

Obtener contenido de un cuaderno

Actualización de un cuaderno

Eliminación de un cuaderno

Enumeración de cuadernos en un área de trabajo

Utilidades de credenciales

Obtener el token

Obtención del secreto con las credenciales de usuario

Montaje y desmontaje de archivos

Montaje de una cuenta de ADLS Gen2

Montaje con un token de firma de acceso compartido o una clave de cuenta

Cómo montar un almacén de lago

Acceso a los archivos del punto de montaje por medio de la API notebookutils fs

Acceso a los archivos en el punto de montaje a través de la ruta de acceso local

Cómo comprobar los puntos de montaje existentes

Desmontaje del punto de montaje.

Restricciones conocidas

Utilidades de Lakehouse

Información general de los métodos

Ejemplos de uso

Creación de un Lakehouse

Obtención de un Lakehouse

Actualización de un Lakehouse

Eliminación de un Lakehouse

Enumeración de Lakehouses en un área de trabajo

Enumeración de todas las tablas de una instancia de Lakehouse

Inicio de una operación de tabla de carga en una instancia de Lakehouse

Información adicional

Utilidades en tiempo de ejecución

Mostrar la información de contexto de sesión

Problema conocido

Contenido relacionado

Comentarios

Recursos adicionales