azure-storage-file-share-py

Azure Storage File Share SDK for Python

クラウドネイティブおよびリフトアンドシフトのシナリオ向けに、SMB ファイル共有を管理します。

インストール

pip install azure-storage-file-share

環境変数

AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...;AccountKey=...
# Or
AZURE_STORAGE_ACCOUNT_URL=https://<account>.file.core.windows.net

認証

接続文字列

import os
from azure.storage.fileshare import ShareServiceClient

service = ShareServiceClient.from_connection_string(
    os.environ["AZURE_STORAGE_CONNECTION_STRING"]
)

Entra ID

from azure.storage.fileshare import ShareServiceClient
from azure.identity import DefaultAzureCredential

service = ShareServiceClient(
    account_url=os.environ["AZURE_STORAGE_ACCOUNT_URL"],
    credential=DefaultAzureCredential(),
    token_intent="backup",
)

OAuth については、token_intent and backup permissions を確認してください。バックアップ インテントはファイル／ディレクトリの ACL チェックを回避でき、明示的に認可されたロールが必要です。例はそれぞれ独立した断片であり、account_url、os、および互換性のあるパッケージが必要です。書き込み／アップロードによってコンテンツが置き換えられる可能性があります。対象の共有／パスを正確に確認し、既存のファイルを保護し、ダウンロードするバイト数を制限し、破棄可能なリソースのみを削除してください。接続文字列や SAS URL を出力しないでください。コピーの開始は非同期です。成功を報告する前に、コピー先のコピー状態をポーリングしてください。失敗時にもクライアント／資格情報を閉じるため、try/finally または非同期コンテキストマネージャーを使用してください。

共有操作

共有の作成

share = service.create_share("my-share")

共有の一覧表示

for share in service.list_shares():
    print(f"{share.name}: {share.quota} GB")

共有クライアントの取得

share_client = service.get_share_client("my-share")

共有の削除

service.delete_share("my-share")

ディレクトリ操作

ディレクトリの作成

share_client = service.get_share_client("my-share")
share_client.create_directory("my-directory")

# Nested directory
share_client.create_directory("my-directory/sub-directory")

ディレクトリとファイルの一覧表示

directory_client = share_client.get_directory_client("my-directory")

for item in directory_client.list_directories_and_files():
    if item["is_directory"]:
        print(f"[DIR] {item['name']}")
    else:
        print(f"[FILE] {item['name']} ({item['size']} bytes)")

ディレクトリの削除

share_client.delete_directory("my-directory")

ファイル操作

ファイルのアップロード

file_client = share_client.get_file_client("my-directory/file.txt")

# From string
file_client.upload_file("Hello, World!")

# From file
with open("local-file.txt", "rb") as f:
    file_client.upload_file(f)

# From bytes
file_client.upload_file(b"Binary content")

ファイルのダウンロード

file_client = share_client.get_file_client("my-directory/file.txt")

# To bytes
data = file_client.download_file().readall()

# To file
with open("downloaded.txt", "wb") as f:
    data = file_client.download_file()
    data.readinto(f)

# Stream chunks
download = file_client.download_file()
for chunk in download.chunks():
    process(chunk)

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

properties = file_client.get_file_properties()
print(f"Size: {properties.size}")
print(f"Content type: {properties.content_settings.content_type}")
print(f"Last modified: {properties.last_modified}")

ファイルの削除

file_client.delete_file()

ファイルのコピー

source_url = "https://account.file.core.windows.net/share/source.txt"
dest_client = share_client.get_file_client("destination.txt")
dest_client.start_copy_from_url(source_url)

範囲操作

範囲のアップロード

# Upload to specific range
file_client.upload_range(data=b"content", offset=0, length=7)

範囲のダウンロード

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

スナップショット操作

スナップショットの作成

snapshot = share_client.create_snapshot()
print(f"Snapshot: {snapshot['snapshot']}")

スナップショットへのアクセス

snapshot_client = service.get_share_client(
    "my-share",
    snapshot=snapshot["snapshot"]
)

非同期クライアント

from azure.storage.fileshare.aio import ShareServiceClient
from azure.identity.aio import DefaultAzureCredential

async def upload_file():
    credential = DefaultAzureCredential()
    service = ShareServiceClient(account_url, credential=credential, token_intent="backup")
    
    share = service.get_share_client("my-share")
    file_client = share.get_file_client("test.txt")
    
    await file_client.upload_file("Hello!")
    
    await service.close()
    await credential.close()

クライアントの種類

クライアント	目的
ShareServiceClient	アカウントレベルの操作
ShareClient	共有操作
ShareDirectoryClient	ディレクトリ操作
ShareFileClient	ファイル操作

ベストプラクティス

1. サポートされている場合は、スコープを限定した ID を優先してください。接続文字列にはアカウントの資格情報が含まれます
2. 本番環境では RBAC を使用して Entra ID を使ってください
3. メモリの問題を避けるため、chunks() を使って大きなファイルをストリーミングしてください
4. 大きな変更の前にスナップショットを作成してください
5. 予期しないストレージコストを防ぐため、クォータを設定してください
6. ファイルの一部を更新するには範囲を使用してください
7. 非同期クライアントを明示的に閉じてください

使用する場合

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

制限事項

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