Condividi tramite

Utilità del file system NotebookUtils per Fabric

notebookutils.fs fornisce utilità per l'uso di vari file system, tra cui Azure Data Lake Storage (ADLS) Gen2 e Azure Blob Storage. Assicurarsi che l'accesso ad Azure Data Lake Storage Gen2 e Azure Blob Storage sia configurato in modo appropriato.

Usare i comandi seguenti per una panoramica dei metodi disponibili:

notebookutils.fs.help()

Nella tabella seguente sono elencati i metodi del file system disponibili:

metodo Firma Descrizione
ls ls(path: String): Array Elenca i contenuti di una directory.
mkdirs mkdirs(path: String): Boolean Crea la directory specificata, se non esiste, creando anche le directory padre necessarie.
cp cp(src: String, dest: String, recurse: Boolean = false): Boolean Copia un file o una directory, possibilmente attraverso sistemi di file.
fastcp fastcp(src: String, dest: String, recurse: Boolean = true, extraConfigs: Map = None): Boolean Copia un file o una directory tramite azcopy per ottenere prestazioni migliori con volumi di dati di grandi dimensioni.
mv mv(src: String, dest: String, create_path: Boolean, overwrite: Boolean = false): Boolean Sposta un file o una directory, possibilmente tra file system.
put put(file: String, content: String, overwrite: Boolean = false): Boolean Scrive la stringa specificata in un file codificato in UTF-8.
head head(file: String, max_bytes: int = 1024 * 100): String Restituisce fino ai primi max_bytes byte del file specificato come stringa codificata in UTF-8.
append append(file: String, content: String, createFileIfNotExists: Boolean = false): Boolean Aggiunge il contenuto a un file.
rm rm(path: String, recurse: Boolean = false): Boolean Rimuove un file o una directory.
exists exists(path: String): Boolean Controlla se esiste un file o una directory.
getProperties getProperties(path: String): Map Ottiene le proprietà del percorso specificato. Disponibile solo nei notebook Python (non supportato in PySpark, Scala o R).

Annotazioni

Tutti i metodi del file system sono disponibili nei notebook Python, PySpark, Scala e R, salvo diversa indicazione. Scala usa nomi dei parametri in camelCase (ad esempio, createPath invece di create_path, maxBytes invece di max_bytes).

Per le operazioni di montaggio e smontaggio, vedere Montaggio e smontaggio di file.

Annotazioni

Tenere presenti i vincoli e le considerazioni seguenti quando si lavora con notebookutils.fs:

  • Il comportamento del percorso varia in base al tipo di notebook: nei notebook Spark i percorsi relativi si risolvono nel percorso ABFSS predefinito di Lakehouse. Nei notebook di Python, i percorsi relativi si risolvono nella directory di lavoro del sistema locale (/home/trusted-service-user/work).
  • Limitazioni di scrittura simultanee: notebookutils.fs.append() e notebookutils.fs.put() non supportano scritture simultanee nello stesso file a causa di una mancanza di garanzie di atomicità.
  • Ritardo del ciclo di loop: quando si usano notebookutils.fs.append() i cicli, aggiungere 0,5-1 secondo di pausa tra le scritture per l'integrità dei dati.
  • Limitazioni dei collegamenti a OneLake: per i collegamenti di tipo S3/GCS, usare percorsi montati invece di percorsi ABFS per eseguire operazioni cp() e fastcp().
  • Limitazioni tra aree: fastcp() non supporta la copia di file in OneLake tra aree. Utilizzare invece cp().
  • Versione di runtime: NotebookUtils è progettato per funzionare con Spark 3.4 (Runtime v1.2) e versioni successive.
  • cp() comportamento nei notebook Python: cp() utilizza internamente, nei notebook Python, lo stesso meccanismo basato su azcopy di fastcp(), quindi entrambi i metodi si comportano identicamente.

NotebookUtils funziona con il file system nello stesso modo delle API Spark. Ad esempio, usare notebookutils.fs.mkdirs() e Lakehouse:

Utilizzo Percorso relativo dalla radice HDFS Percorso assoluto per il file system ABFS Percorso assoluto del file system locale nel nodo driver
Lakehouse non predefinito Non supportato notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>") notebookutils.fs.mkdirs("file:/<new_dir>")
Default Lakehouse Directory sotto '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>")

  • Per il Lakehouse predefinito, i percorsi dei file vengono montati nel notebook con un timeout della cache dei file impostato di default a 120 secondi. Ciò significa che i file vengono memorizzati nella cache nella cartella temporanea locale del notebook per 120 secondi, anche se vengono rimossi da Lakehouse. Se si vuole modificare la regola di timeout, è possibile smontare i percorsi predefiniti dei file Lakehouse e montarli di nuovo con un valore diverso fileCacheTimeout .

  • Per le configurazioni Lakehouse non predefinite, è possibile impostare il parametro appropriato fileCacheTimeout durante il montaggio dei percorsi Lakehouse. L'impostazione del timeout su 0 garantisce che il file più recente venga recuperato dal server Lakehouse.

Elencare file

Per elencare il contenuto di una directory, usare notebookutils.fs.ls('Your directory path'). Per esempio:

notebookutils.fs.ls("Files/tmp") # Relative path works with different base paths depending on notebook type
notebookutils.fs.ls("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")  # Absolute path using ABFS file system
notebookutils.fs.ls("file:/tmp")  # Full path of the local file system of driver node

L'API notebookutils.fs.ls() si comporta in modo diverso quando si usa un percorso relativo, a seconda del tipo di notebook.

  • In un notebook Spark: il percorso relativo è riferito al percorso ABFSS predefinito di Lakehouse. Ad esempio, notebookutils.fs.ls("Files") punta alla directory Files nel Lakehouse predefinito.

    Per esempio:

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

  • In un notebook Python: il percorso relativo si riferisce alla directory di lavoro del file system locale, che per impostazione predefinita è /home/trusted-service-user/work. Pertanto, è consigliabile usare il percorso completo anziché un percorso relativo notebookutils.fs.ls("/lakehouse/default/Files") per accedere alla directory Files nel Lakehouse di default.

    Per esempio:

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

Visualizzazione delle proprietà di file

Usare notebookutils.fs.ls() per controllare le proprietà dei file, ad esempio nome file, percorso file, dimensioni del file e se un elemento è un file o una directory.

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

Usare f-strings se si vuole ottenere un output più leggibile:

files = notebookutils.fs.ls("Files/data")
for file in files:
    print(f"Name: {file.name}, Size: {file.size}, IsDir: {file.isDir}, Path: {file.path}")

Creare una nuova cartella

Creare una directory se non esiste, incluse le eventuali directory padre necessarie.

notebookutils.fs.mkdirs('new directory name')  
notebookutils.fs.mkdirs("Files/<new_dir>")  # Works with the default Lakehouse files using relative path 
notebookutils.fs.mkdirs("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<new_dir>")  # Based on ABFS file system 
notebookutils.fs.mkdirs("file:/<new_dir>")  # Based on local file system of driver node

Copia file

Copiare un file o una directory tra sistemi di file. Impostare recurse=True per copiare le directory in modo ricorsivo.

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

Annotazioni

Nota del notebook Python: Nei notebook Python, cp() utilizza internamente lo stesso meccanismo basato su azcopy come fastcp(), offrendo prestazioni efficienti per entrambi i metodi. A causa delle limitazioni del collegamento a OneLake, quando è necessario usare notebookutils.fs.cp() per copiare dati dal collegamento di tipo S3/GCS, è consigliabile usare un percorso montato anziché un percorso di tipo abfss.

Suggerimento

Controllare sempre il valore restituito booleano per verificare se l'operazione è riuscita. Usare notebookutils.fs.exists() per verificare il percorso di origine prima di avviare un'operazione di copia.

L'esempio seguente mostra una copia tra risorse di archiviazione dal lakehouse predefinito a un account ADLS Gen2:

notebookutils.fs.cp(
    "Files/local_data",
    "abfss://<container>@<account>.dfs.core.windows.net/remote_data",
    recurse=True
)

File di copia con prestazioni elevate

Usare fastcp per operazioni di copia più efficienti, in particolare con volumi di dati di grandi dimensioni. Per impostazione predefinita, il recurse parametro è True.

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

Suggerimento

Usare fastcp() invece di cp() per trasferimenti di dati di grandi dimensioni. Il fastcp metodo utilizza azcopy in secondo piano, il che offre una velocità effettiva significativamente migliore per le operazioni di file in blocco. Nei notebook Python, entrambi cp() e fastcp() usano lo stesso meccanismo sottostante.

Tenere presenti queste considerazioni:

  • notebookutils.fs.fastcp() non supporta la copia di file in OneLake tra aree. In questo caso, è possibile usare notebookutils.fs.cp() invece .
  • A causa delle limitazioni del collegamento a OneLake, quando è necessario usare notebookutils.fs.fastcp() per copiare dati dal collegamento di tipo S3/GCS, è consigliabile usare un percorso montato anziché un percorso di tipo abfss.

Anteprima del contenuto del file

Restituisce fino ai primi max_bytes byte di un file come stringa UTF-8.

notebookutils.fs.head('file path', max_bytes)

Suggerimento

Per i file di grandi dimensioni, usare head() con un valore appropriato max_bytes per evitare problemi di memoria. Il valore predefinito è 100 KB (1024 * 100).

L'esempio seguente legge i primi 1.000 byte di un file:

content = notebookutils.fs.head("Files/data/sample.txt", 1000)
print(content)

Annotazioni

Il valore predefinito di max_bytes differisce tra i linguaggi: i notebook Python e Scala usano 102400 (100 KB), mentre i notebook R usano 65535 (64 KB). In Scala questo parametro è denominato maxBytes.

Sposta file

Spostare un file o una directory tra file system.

notebookutils.fs.mv('source file or directory', 'destination directory', create_path=True, overwrite=True)

Importante

Il valore predefinito del create_path parametro varia in base al runtime:

  • Notebook Spark (PySpark, Scala, R): per impostazione predefinita False (false in Scala, FALSE in R). La directory principale deve esistere prima dell'operazione di spostamento.
  • Notebook Python: di default è True. La cartella principale viene creata automaticamente se non esiste.

Per garantire un comportamento coerente tra i runtime, impostare in modo esplicito il create_path parametro nel codice. In Scala questo parametro è denominato createPath.

Usare i parametri denominati se si vuole codice più chiaro:

notebookutils.fs.mv("Files/source.csv", "Files/new_folder/dest.csv", create_path=True, overwrite=True)

Scrivere il file

Scrivere una stringa UTF-8 in un file.

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

Accodare contenuto a un file

Aggiungere una stringa UTF-8 a un file.

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

Importante

notebookutils.fs.append() e notebookutils.fs.put() non supportano la scrittura simultanea nello stesso file a causa di una mancanza di garanzie di atomicità.

Quando si usa l'API notebookutils.fs.append in un for ciclo per scrivere nello stesso file, aggiungere un'istruzione sleep di circa 0,5 a 1 secondo tra le scritture ricorrenti. Questo suggerimento è dovuto al fatto che l'operazione interna notebookutils.fs.append dell'API flush è asincrona, quindi un breve ritardo aiuta a garantire l'integrità dei dati.

import time

for i in range(100):
    notebookutils.fs.append("Files/output/data.txt", f"Line {i}\n", True)
    time.sleep(0.5)  # Prevent data integrity issues

Eliminare un file o una directory

Rimuovere un file o una directory. Impostare recurse=True per rimuovere le directory in modo ricorsivo.

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

Controllare se esiste un file o una directory

Controllare se esiste un file o una directory nel percorso specificato. Restituisce True se il percorso esiste; in caso contrario, restituisce False.

notebookutils.fs.exists("Files/data/input.csv")

Suggerimento

Utilizzare exists() prima di eseguire operazioni sui file per evitare errori. Ad esempio, verificare che esista un file di origine prima di provare a copiarlo o spostarlo.

if notebookutils.fs.exists("Files/data/input.csv"):
    notebookutils.fs.cp("Files/data/input.csv", "Files/backup/input.csv")
    print("File copied successfully.")
else:
    print("Source file not found.")

Ottenere le proprietà di un file

Ottieni le proprietà di un percorso come una mappa di coppie nome-valore. È supportato solo per i percorsi di Archiviazione BLOB di Azure.

Annotazioni

Il getProperties metodo è disponibile solo nei notebook Python. Non è supportato nei notebook Spark (PySpark, Scala o R).

Parametri:

Parametro Tipo Obbligatorio Descrizione
path String Sì Percorso di accesso ABFS al file o alla directory.

Restituisce: Dizionario (mappa) contenente le proprietà dei metadati, ad esempio dimensioni del file, ora di creazione, ora dell'ultima modifica e tipo di contenuto.

properties = notebookutils.fs.getProperties("abfss://<container_name>@<storage_account_name>.dfs.core.windows.net/<path>")
print(properties)

Contenuti correlati

  • Last updated on