azure-storage-file-datalake-py

Python 用 Azure Data Lake Storage Gen2 SDK

ビッグデータ分析ワークロード向けの階層型ファイルシステムです。

インストール

pip install azure-storage-file-datalake azure-identity

環境変数

AZURE_STORAGE_ACCOUNT_URL=https://<account>.dfs.core.windows.net

認証

from azure.identity import DefaultAzureCredential
from azure.storage.filedatalake import DataLakeServiceClient

credential = DefaultAzureCredential()
account_url = "https://<account>.dfs.core.windows.net"

service_client = DataLakeServiceClient(account_url=account_url, credential=credential)

クライアントの階層

クライアント	用途
DataLakeServiceClient	アカウントレベルの操作
FileSystemClient	コンテナー（ファイルシステム）の操作
DataLakeDirectoryClient	ディレクトリの操作
DataLakeFileClient	ファイルの操作

これらは個別のコード断片であり、すべてを一度に実行するスクリプトではありません。書き込み、名前変更、再帰的な ACL の変更、削除を行う前に、アカウント、ファイルシステム、パスを確認し、既存データを保護してください。本番環境のプレースホルダーをクリーンアップ対象として使用しないでください。再帰的な一覧表示では取得範囲を制限し、ダウンロードするバイト数を制限するとともに、既存ファイルを上書きしないローカル出力を使用してください。再帰的な ACL の更新は一部失敗する可能性があります。カウンターと失敗の詳細を確認し、対象範囲を正確に把握したうえでのみ再開してください。失敗時の処理では、クライアントだけでなく非同期の認証情報も閉じてください。アップロードの成功だけでは、業務上の正しさは保証されません。

ファイルシステム操作

# Create file system (container)
file_system_client = service_client.create_file_system("myfilesystem")

# Get existing
file_system_client = service_client.get_file_system_client("myfilesystem")

# Delete
service_client.delete_file_system("myfilesystem")

# List file systems
for fs in service_client.list_file_systems():
    print(fs.name)

ディレクトリ操作

file_system_client = service_client.get_file_system_client("myfilesystem")

# Create directory
directory_client = file_system_client.create_directory("mydir")

# Create nested directories
directory_client = file_system_client.create_directory("path/to/nested/dir")

# Get directory client
directory_client = file_system_client.get_directory_client("mydir")

# Delete directory
directory_client.delete_directory()

# Rename/move directory
directory_client.rename_directory(new_name="myfilesystem/newname")

ファイル操作

ファイルのアップロード

# Get file client
file_client = file_system_client.get_file_client("path/to/file.txt")

# Upload from local file
with open("local-file.txt", "rb") as data:
    file_client.upload_data(data, overwrite=False)

# Upload bytes
file_client.upload_data(b"Hello, Data Lake!", overwrite=False)

# Separate append example: create an explicitly new empty file first.
file_client = file_system_client.create_file("disposable-append-example.txt")
file_client.append_data(data=b"chunk1", offset=0, length=6)
file_client.append_data(data=b"chunk2", offset=6, length=6)
file_client.flush_data(12)  # Commit the data

ファイルのダウンロード

file_client = file_system_client.get_file_client("path/to/file.txt")

# Download all content
download = file_client.download_file()
content = download.readall()

# Download to file
with open("downloaded.txt", "wb") as f:
    download = file_client.download_file()
    download.readinto(f)

# Download range
download = file_client.download_file(offset=0, length=100)

ファイルの削除

file_client.delete_file()

コンテンツの一覧表示

# List paths (files and directories)
for path in file_system_client.get_paths():
    print(f"{'DIR' if path.is_directory else 'FILE'}: {path.name}")

# List paths in directory
for path in file_system_client.get_paths(path="mydir"):
    print(path.name)

# Recursive listing
for path in file_system_client.get_paths(path="mydir", recursive=True):
    print(path.name)

ファイル／ディレクトリのプロパティ

# Get properties
properties = file_client.get_file_properties()
print(f"Size: {properties.size}")
print(f"Last modified: {properties.last_modified}")

# Set metadata
file_client.set_metadata(metadata={"processed": "true"})

アクセス制御（ACL）

# Get ACL
acl = directory_client.get_access_control()
print(f"Owner: {acl['owner']}")
print(f"Permissions: {acl['permissions']}")

# Set ACL
directory_client.set_access_control(
    owner="user-id",
    permissions="rwxr-x---"
)

# Update ACL entries
from azure.storage.filedatalake import AccessControlChangeResult
directory_client.update_access_control_recursive(
    acl="user:user-id:rwx"
)

非同期クライアント

from azure.storage.filedatalake.aio import DataLakeServiceClient
from azure.identity.aio import DefaultAzureCredential

async def datalake_operations():
    credential = DefaultAzureCredential()
    
    async with DataLakeServiceClient(
        account_url="https://<account>.dfs.core.windows.net",
        credential=credential
    ) as service_client:
        file_system_client = service_client.get_file_system_client("myfilesystem")
        file_client = file_system_client.get_file_client("test.txt")
        
        await file_client.upload_data(b"async content", overwrite=False)
        
        download = await file_client.download_file()
        content = await download.readall()

import asyncio
asyncio.run(datalake_operations())

ベストプラクティス

1. ファイルシステムのセマンティクスには、階層型名前空間を使用します
2. 大きなファイルのアップロードには、append_data と flush_data を使用します
3. ACL の適用範囲を確認します：デフォルト ACL は新しい子孫に適用されます。既存の子孫には、別途承認された再帰的な操作が必要です
4. 高スループットのシナリオでは、非同期クライアントを使用します
5. ディレクトリ全体を一覧表示するには、recursive=True を指定して get_paths を使用します
6. カスタムのファイル属性には、メタデータを設定します
7. シンプルなオブジェクトストレージのユースケースには、Blob API の利用を検討します

使用する場面

このスキルは、概要に記載されたワークフローまたはアクションを実行する際に適用できます。

制限事項

• このスキルは、タスクが上記の範囲に明確に該当する場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、停止して確認してください。