Fabric 用 NotebookUtils ファイル システム ユーティリティ

notebookutils.fs には、Azure Data Lake Storage (ADLS) Gen2 や Azure Blob Storage など、さまざまなファイル システムを操作するためのユーティリティが用意されています。 Azure Data Lake Storage Gen2 および Azure Blob Storage へのアクセスを適切に構成するようにしてください。

次のコマンドを実行して、使用可能なメソッドの概要を取得します。

notebookutils.fs.help()

次の表に、使用可能なファイル システムメソッドの一覧を示します。

マウント操作とマウント解除操作については、「 ファイルのマウントとマウント解除」を参照してください。

NotebookUtils でファイル システムを操作する方法は、Spark API と同じです。 notebookutils.fs.mkdirs()と Lakehouse の使用例を次に示します。

• 既定の Lakehouse の場合、ファイル パスはノートブックにマウントされ、既定のファイル キャッシュ タイムアウトは 120 秒です。 これは、ファイルが Lakehouse から削除された場合でも、ノートブックのローカル一時フォルダーに 120 秒間キャッシュされることを意味します。 タイムアウト規則を変更する場合は、既定の Lakehouse ファイル パスのマウントを解除し、別の fileCacheTimeout 値で再度マウントできます。

• 既定以外の Lakehouse 構成の場合は、Lakehouse パスのマウント中に適切な fileCacheTimeout パラメーターを設定できます。 タイムアウトを 0 に設定すると、最新のファイルがレイクハウス サーバーから確実にフェッチされます。

ファイルを一覧表示する

ディレクトリの内容を一覧表示するには、 notebookutils.fs.ls('Your directory path')を使用します。 例えば次が挙げられます。

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

notebookutils.fs.ls() API は、ノートブックの種類に応じて、相対パスを使用する場合の動作が異なります。

• Spark ノートブック内: 相対パスは、既定のレイクハウスの ABFSS パスを基準とします。 たとえば、notebookutils.fs.ls("Files") は、既定の Lakehouse の Files ディレクトリをポイントします。

  例えば次が挙げられます。

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

• Python ノートブックの場合: 相対パスはローカル ファイル システムの作業ディレクトリに対する相対パスであり、既定では /home/trusted-service-user/work。 そのため、既定の Lakehouse の notebookutils.fs.ls("/lakehouse/default/Files") ディレクトリにアクセスするには、相対パス Files の代わりに完全パスを使用する必要があります。

  例えば次が挙げられます。

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

ファイルのプロパティを表示します

notebookutils.fs.ls()を使用して、ファイル名、ファイル パス、ファイル サイズ、項目がファイルとディレクトリのどちらであるかを調べます。

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

より読みやすい出力が必要な場合は、f 文字列を使用します。

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

新しいディレクトリの作成

ディレクトリが存在しない場合は、必要な親ディレクトリを含めて作成します。

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 

ファイルのコピー

ファイル システム間でファイルまたはディレクトリをコピーします。 ディレクトリを再帰的にコピーするように recurse=True を設定します。

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

次の例は、既定の Lakehouse から ADLS Gen2 アカウントへのクロスストレージ コピーを示しています。

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

パフォーマンスの高いコピー ファイル

fastcpを使用すると、特に大きなデータ ボリュームで、より効率的なコピー操作を行うことができます。 recurse パラメーターの既定値は True です。

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

以下の考慮事項に留意してください。

• notebookutils.fs.fastcp() では、リージョン間での OneLake でのファイルのコピーはサポートされていません。 この場合は、代わりに notebookutils.fs.cp() を使用できます。
• OneLake ショートカットの制限により、notebookutils.fs.fastcp()を使用して S3/GCS 型のショートカットからデータをコピーする必要がある場合は、abfss パスではなくマウントされたパスを使用することをお勧めします。

ファイル コンテンツのプレビュー

ファイルの最初の max_bytes バイトまで UTF-8 文字列として返します。

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

次の例では、ファイルの最初の 1,000 バイトを読み取ります。

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

ファイルの移動

ファイル システム間でファイルまたはディレクトリを移動します。

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

より明確なコードが必要な場合は、名前付きパラメーターを使用します。

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

ファイルを書き込む

UTF-8 文字列をファイルに書き込みます。

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

ファイルへのコンテンツの追加

UTF-8 文字列をファイルに追加します。

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

notebookutils.fs.append ループで for API を使用して同じファイルに書き込む場合は、定期的な書き込みの間に約 0.5 ~ 1 秒のsleepステートメントを追加します。 この推奨事項は、notebookutils.fs.append API の内部 flush 操作が非同期であるため、短い遅延がデータの整合性を確保するのに役立ちます。

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

ファイルまたはディレクトリの削除

ファイルまたはディレクトリを削除します。 ディレクトリを再帰的に削除するには、 recurse=True を設定します。

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

ファイルまたはディレクトリが存在するかどうかを確認する

指定したパスにファイルまたはディレクトリが存在するかどうかを確認します。 パスが存在する場合は True を返します。それ以外の場合は、 Falseを返します。

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

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

ファイルのプロパティの取得

名前と値のペアのマップとしてパスのプロパティを取得します。 Azure Blob Storage パスでのみサポートされます。

パラメーター:

返します： ファイル サイズ、作成時刻、最終変更時刻、コンテンツ タイプなどのメタデータ プロパティを含むディクショナリ (マップ)。

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

関連するコンテンツ

• NotebookUtils の概要
• NotebookUtils を使用したストレージのマウントとマウント解除