Python 用 Azure Storage ファイル共有クライアント ライブラリ - バージョン 12.15.0

  • [アーティクル]

Azure File Share Storage では、業界標準の サーバー メッセージ ブロック (SMB) プロトコルを介してアクセスできるフル マネージドのファイル共有がクラウドで提供されます。 Azure ファイル共有は、クラウドまたはオンプレミスにある Windows、macOS、および Linux に同時にマウントできます。 さらに、高速アクセスするため、Azure File Sync を使用して、データが使用されている場所の近くの Windows サーバーに Azure ファイル共有をキャッシュできます。

Azure ファイル共有は、以下の作業に使用できます。

  • オンプレミスのファイル サーバーの置換または補完。
  • "リフトアンドシフト" アプリケーション
  • 共有アプリケーション設定、診断共有、Dev/Test/Debug ツールを使用してクラウド開発を簡素化する

ソースコード | パッケージ (PyPI) | パッケージ (Conda) | API リファレンス ドキュメント | 製品ドキュメント | サンプル

作業の開始

前提条件

パッケージをインストールする

pip を使用して Python 用 Azure Storage ファイル共有クライアント ライブラリをインストールします。

pip install azure-storage-file-share

ストレージ アカウントの作成

新しいストレージ アカウントを作成する場合は、Azure Portal、Azure PowerShell、または Azure CLI を使用できます。

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

クライアントを作成する

Python 用 Azure Storage ファイル共有クライアント ライブラリを使用すると、ストレージ アカウント自体、ファイル共有、ディレクトリ、ファイルの 4 種類のリソースを操作できます。 これらのリソースとの対話は、 クライアントのインスタンスから始まります。 クライアント オブジェクトを作成するには、ストレージ アカウントのファイル サービス URL と、ストレージ アカウントにアクセスできる資格情報が必要です。

from azure.storage.fileshare import ShareServiceClient

service = ShareServiceClient(account_url="https://<my-storage-account-name>.file.core.windows.net/", credential=credential)

アカウントの URL を検索する

ストレージ アカウントのファイル サービス URL は、Azure Portal、Azure PowerShell、または Azure CLI を使用して確認できます。

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

資格情報の種類

パラメーターは credential 、使用する 承認 の種類に応じて、さまざまな形式で指定できます。

  1. Shared Access Signature (SAS) トークンを使用するには、トークンを文字列として指定します。 アカウント URL に SAS トークンが含まれている場合は、credential パラメーターを省略します。 Azure Portal の [共有アクセス署名] で SAS トークンを生成するか、いずれかの関数を generate_sas() 使用してストレージ アカウント、共有、またはファイルの sas トークンを作成できます。

    from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

  2. ストレージ アカウント 共有キー (アカウント キーまたはアクセス キー) を使用するには、キーを文字列として指定します。 これは、Azure Portal の [アクセス キー] セクションで、または次の Azure CLI コマンドを実行して確認できます。

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    資格情報パラメーターとしてキーを使用して、クライアントを認証します。

    from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")

接続文字列からクライアントを作成する

ユース ケースと承認方法によっては、アカウントの URL と資格情報を個別に指定するのではなく、ストレージ 接続文字列を使用してクライアント インスタンスを初期化することをお勧めします。 これを行うには、ストレージ 接続文字列をクライアントのfrom_connection_stringクラス メソッドに渡します。

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

ストレージ アカウントへの接続文字列は、Azure Portal の [アクセス キー] セクションで、または次の CLI コマンドを実行することによって確認できます。

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

主要な概念

Azure ファイル共有サービスを構成するコンポーネントは次のとおりです。

  • ストレージ アカウント自体
  • ストレージ アカウント内のファイル共有
  • ファイル共有内のディレクトリの省略可能な階層
  • ファイル共有内のファイルのサイズは最大 1 TiB です

Python 用 Azure Storage ファイル共有クライアント ライブラリを使用すると、専用のクライアント オブジェクトを使用してこれらの各コンポーネントを操作できます。

非同期クライアント

このライブラリには、Python 3.5 以降でサポートされている完全な非同期 API が含まれています。 これを使用するには、まず、 aiohttp などの非同期トランスポートをインストールする必要があります。 詳細については、 azure-core のドキュメント を参照してください。

非同期クライアントと資格情報は、不要になったら閉じる必要があります。 これらのオブジェクトは非同期コンテキスト マネージャーであり、非同期 close メソッドを定義します。

クライアント

ファイル共有サービスのさまざまなコンポーネントを操作するために、4 つの異なるクライアントが用意されています。

  1. ShareServiceClient - このクライアントは、Azure ストレージ アカウント自体との対話を表し、構成済みのクライアント インスタンスを取得して、 内のファイル共有にアクセスできるようにします。 アカウント内の共有の一覧表示、作成、削除に加えて、サービス のプロパティを取得および構成する操作を提供します。 特定の共有に対して操作を実行するには、 メソッドを使用してクライアントを取得します get_share_client 。
  2. ShareClient - このクライアントは、(まだ存在する必要がない) 特定のファイル共有との対話を表し、構成済みのクライアント インスタンスを取得して、 内のディレクトリとファイルにアクセスできるようにします。 共有のスナップショットを作成、削除、構成、または作成する操作が提供され、その中のディレクトリの内容を作成および列挙する操作が含まれます。 特定のディレクトリまたはファイルに対して操作を実行するには、 メソッドまたは get_file_client メソッドを使用してクライアントをget_directory_client取得します。
  3. ShareDirectoryClient - このクライアントは、特定のディレクトリとの対話を表します (まだ存在する必要はありません)。 これにより、イミディエイトまたは入れ子になったサブディレクトリの内容を作成、削除、または列挙する操作が提供され、その中にファイルを作成および削除する操作が含まれます。 特定のサブディレクトリまたはファイルに関連する操作の場合は、 関数と get_file_client 関数を使用してそのエンティティのget_subdirectory_clientクライアントを取得することもできます。
  4. ShareFileClient - このクライアントは、特定のファイルとの対話を表します (まだ存在する必要はありません)。 ファイルのアップロード、ダウンロード、作成、削除、コピーを行う操作が提供されます。

パスの名前付けの制限の詳細については、「 共有、ディレクトリ、ファイル、およびメタデータの名前付けと参照」を参照してください。

例

次のセクションでは、次のような最も一般的なストレージ ファイル共有タスクの一部をカバーするいくつかのコード スニペットを示します。

ファイル共有の作成

ファイルを保存するファイル共有を作成する

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

非同期クライアントを使用してファイル共有を作成する

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

ファイルのアップロード

ファイルを共有にアップロードする

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

ファイルを非同期的にアップロードする

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

ファイルのダウンロード

共有からファイルをダウンロードする

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

ファイルを非同期的にダウンロードする

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

ディレクトリの内容を一覧表示する

親ディレクトリのすべてのディレクトリとファイルを一覧表示する

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

ディレクトリの内容を非同期的に一覧表示する

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

オプションの構成

クライアントおよび操作ごとのレベルで渡すことができる省略可能なキーワード (keyword)引数。

再試行ポリシーの構成

再試行ポリシーを構成するには、クライアントをインスタンス化するときに、次のキーワード (keyword)引数を使用します。

  • retry_total (int): 許可する再試行の合計数。 他のカウントよりも優先されます。 要求時に retry_total=0 再試行しない場合は、 を渡します。 既定値は 10 です。
  • retry_connect (int): 再試行する接続関連エラーの数。 既定値は 3 です。
  • retry_read (int): 読み取りエラーで再試行する回数。 既定値は 3 です。
  • retry_status (int): 無効な状態コードで再試行する回数。 既定値は 3 です。
  • retry_to_secondary (bool): 要求をセカンダリに再試行する必要があるかどうか (可能な場合)。 これは、RA-GRS アカウントのみが使用され、古いデータを処理できる可能性がある場合にのみ有効にする必要があります。 既定値は False です。

その他のクライアント/操作ごとの構成

その他の省略可能な構成キーワード (keyword)クライアントまたは操作ごとに指定できる引数です。

クライアント キーワード (keyword)引数:

  • connection_timeout (int): クライアントがサーバーへの接続の確立を待機する秒数。 既定値は 20 秒です。
  • read_timeout (int): サーバーからの応答について、クライアントが連続する読み取り操作の間に待機する秒数。 これはソケット レベルのタイムアウトであり、全体的なデータ サイズの影響を受けません。 クライアント側の読み取りタイムアウトは自動的に再試行されます。 既定値は 60 秒です。
  • transport (Any): HTTP 要求を送信するためのユーザー指定のトランスポート。

操作ごとのキーワード (keyword)引数:

  • raw_response_hook (呼び出し可能): 指定されたコールバックは、サービスから返される応答を使用します。
  • raw_request_hook (呼び出し可能): 指定されたコールバックは、サービスに送信される前に要求を使用します。
  • client_request_id (str): 要求の省略可能なユーザー指定 ID。
  • user_agent (str): 要求と共に送信するユーザー エージェント ヘッダーにカスタム値を追加します。
  • logging_enable (bool): DEBUG レベルでログ記録を有効にします。 既定値は False です。 クライアント レベルで渡して、すべての要求に対して有効にすることもできます。
  • logging_body (bool): 要求本文と応答本文のログ記録を有効にします。 既定値は False です。 クライアント レベルで渡して、すべての要求に対して有効にすることもできます。
  • headers (dict): カスタム ヘッダーをキー、値のペアとして渡します。 例: headers={'CustomValue': value}

トラブルシューティング

全般

ストレージ ファイル クライアントでは 、Azure Core で定義されている例外が発生します。

このリストは、スローされた例外をキャッチするための参照に使用できます。 例外の特定のエラー コードを取得するには、 属性 ( error_code つまり) exception.error_codeを使用します。

ログの記録

このライブラリでは、ログ記録に標準 のログ ライブラリが使用されます。 HTTP セッションに関する基本情報 (URL、ヘッダーなど) は INFO レベルでログに記録されます。

要求/応答本文、未変換ヘッダーなど、詳細な DEBUG レベルのログは、 引数を使用してクライアントで logging_enable 有効にすることができます。

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = ShareServiceClient.from_connection_string("your_connection_string", logging_enable=True)

同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。

service_client.get_service_properties(logging_enable=True)

次のステップ

その他のサンプル コード

ファイル共有のサンプルを開始します。

SDK の GitHub リポジトリでは、いくつかの Storage File Share Python SDK サンプルを使用できます。 これらのサンプルでは、ストレージ ファイル共有の作業中に一般的に発生するその他のシナリオのコード例を示します。

その他のドキュメント

Azure File Share ストレージに関するより広範なドキュメントについては、docs.microsoft.com に関 する Azure File Share ストレージのドキュメントを参照してください 。

共同作成

このプロジェクトでは、共同作成と提案を歓迎しています。 ほとんどの共同作成では、共同作成者使用許諾契約書 (CLA) にご同意いただき、ご自身の共同作成内容を使用する権利を Microsoft に供与する権利をお持ちであり、かつ実際に供与することを宣言していただく必要があります。 詳細については、 https://cla.microsoft.com を参照してください。

pull request を送信すると、CLA を提供して PR (ラベル、コメントなど) を適宜装飾する必要があるかどうかを CLA ボットが自動的に決定します。 ボットによって提供される手順にそのまま従ってください。 この操作は、Microsoft の CLA を使用するすべてのリポジトリについて、1 回だけ行う必要があります。

このプロジェクトでは、Microsoft オープン ソースの倫理規定を採用しています。 詳しくは、「Code of Conduct FAQ (倫理規定についてよくある質問)」を参照するか、opencode@microsoft.com 宛てに質問またはコメントをお送りください。