Python 用 Azure Storage BLOB クライアント ライブラリ - バージョン 12.19.0

  • [アーティクル]

Azure Blob Storage は、Microsoft のクラウド用オブジェクト ストレージ ソリューションです。 BLOB ストレージは、テキスト データやバイナリ データなどの大量の非構造化データを格納するために最適化されています。

BLOB ストレージは、次の目的に最適です。

  • 画像またはドキュメントをブラウザーに直接配信する
  • 分散アクセス用のファイルの格納
  • ビデオやオーディオのストリーミング
  • バックアップと復元、ディザスター リカバリー、アーカイブのためのデータの格納
  • オンプレミス サービスまたは Azure ホステッド サービスによる分析のためのデータの格納

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

作業の開始

前提条件

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

pip を使用して Python 用の Azure Storage Blobs クライアント ライブラリをインストールします。

pip install azure-storage-blob

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

新しいストレージ アカウントを作成する場合は、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 BLOB クライアント ライブラリを使用すると、ストレージ アカウント自体、BLOB ストレージ コンテナー、BLOB の 3 種類のリソースを操作できます。 これらのリソースとの対話は、 クライアントのインスタンスから始まります。 クライアント オブジェクトを作成するには、ストレージ アカウントの BLOB サービス アカウント URL と、ストレージ アカウントにアクセスできる資格情報が必要です。

from azure.storage.blob import BlobServiceClient

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

アカウント URL を検索する

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

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

資格情報の種類

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

  1. Azure Active Directory (AAD) トークン資格情報を使用するには、azure-identity ライブラリから取得した目的の資格情報の種類のインスタンスを指定します。 たとえば、 DefaultAzureCredential を使用してクライアントを認証できます。

    これには、いくつかの初期セットアップが必要です。

    返されたトークン資格情報を使用してクライアントを認証します。

        from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )

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

    from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, 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)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

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

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

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

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

    カスタマイズされた URL (URL がこの形式<my_account_name>.blob.core.windows.netではないことを意味します) を使用している場合は、次の資格情報を使用してクライアントをインスタンス化してください。

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})

  4. 匿名パブリック読み取りアクセスを使用するには、単に credential パラメーターを省略します。

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

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

from azure.storage.blob import BlobServiceClient

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

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

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

主要な概念

Azure Blob Service を構成するコンポーネントは次のとおりです。

  • ストレージ アカウント自体
  • ストレージ アカウント内のコンテナー
  • コンテナー内の BLOB

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

クライアント

Blob Service のさまざまなコンポーネントを操作するために、次の 4 つの異なるクライアントが用意されています。

  1. BlobServiceClient - このクライアントは Azure ストレージ アカウント自体との対話を表し、構成済みのクライアント インスタンスを取得して、内のコンテナーと BLOB にアクセスできるようにします。 アカウントのプロパティの取得と構成、およびアカウント内のコンテナーの一覧表示、作成、削除を行う操作を提供します。 特定のコンテナーまたは BLOB に対して操作を実行するには、 メソッドまたは get_blob_client メソッドを使用してクライアントをget_container_client取得します。
  2. ContainerClient - このクライアントは、(まだ存在する必要がない) 特定のコンテナーとの対話を表し、構成済みのクライアント インスタンスを取得して内の BLOB にアクセスできるようにします。 コンテナーを作成、削除、または構成する操作が提供され、コンテナー内の BLOB の一覧表示、アップロード、削除を行う操作が含まれます。 コンテナー内の特定の BLOB に対して操作を実行するには、 メソッドを使用してクライアントを get_blob_client 取得します。
  3. BlobClient - このクライアントは、特定の BLOB との対話を表します (まだ存在する必要はありません)。 BLOB のスナップショットをアップロード、ダウンロード、削除、作成する操作と、BLOB の種類ごとの特定の操作が提供されます。
  4. BlobLeaseClient - このクライアントは、 または BlobClientとのリース操作をContainerClient表します。 指定したリソースのリースを取得、更新、リリース、変更、および中断する操作を提供します。

非同期クライアント

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

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

BLOB の種類

クライアントを初期化したら、さまざまな種類の BLOB から選択できます。

  • ブロック BLOB には 、最大約 4.75 TiB のテキストとバイナリ データが格納されます。 ブロック BLOB は、個別に管理できるデータのブロックで構成されます
  • 追加 BLOB は、ブロック BLOB と同様にブロックで構成されますが、追加操作用に最適化されています。 追加 BLOB は、仮想マシンからのデータのログ記録などのシナリオに最適です
  • ページ BLOB には、最大 8 TiB のランダム アクセス ファイルを格納できます。 ページ BLOB には仮想ハード ドライブ (VHD) ファイルが格納され、Azure 仮想マシンのディスクとして機能します

例

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

BLOB をアップロードまたはダウンロードするには、事前にコンテナーを作成する必要があることに注意してください。

コンテナーを作成する

BLOB をアップロードまたはダウンロードできるコンテナーを作成します。

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

非同期クライアントを使用して BLOB をアップロードする

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

BLOB のアップロード

コンテナーに BLOB をアップロードする

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

非同期クライアントを使用して BLOB をアップロードする

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

BLOB のダウンロード

コンテナーから BLOB をダウンロードする

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

BLOB を非同期的にダウンロードする

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

BLOB の列挙

コンテナー内の BLOB を一覧表示する

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

BLOB を非同期的に一覧表示する

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

オプションの構成

省略可能キーワード (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)引数を使用します。

  • require_encryption (bool): True に設定すると、オブジェクトが暗号化され、暗号化が解除されます。
  • encryption_version (str): 使用する暗号化のバージョンを指定します。 現在のオプションは または '2.0''1.0' で、既定値は です '1.0'。 バージョン 1.0 は非推奨であり、バージョン 2.0 を使用 することを強くお勧めします 。
  • key_encryption_key (オブジェクト): ユーザー指定のキー暗号化キー。 インスタンスは、次のメソッドを実装する必要があります。
    • wrap_key(key)--wraps the specified key using an algorithm of the user's choice.
    • get_key_wrap_algorithm()--は、指定された対称キーをラップするために使用されるアルゴリズムを返します。
    • get_kid()--は、このキー暗号化キーの文字列キー ID を返します。
  • key_resolver_function (呼び出し可能): ユーザー指定のキー リゾルバー。 kid 文字列を使用して、上記で定義したインターフェイスを実装するキー暗号化キーを返します。

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

その他の省略可能な構成キーワード (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}

トラブルシューティング

全般

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

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

ログの記録

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

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

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
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 = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

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

service_client.get_service_stats(logging_enable=True)

次のステップ

その他のサンプル コード

BLOB サンプルの使用を開始します。

SDK の GitHub リポジトリには、いくつかのストレージ BLOB Python SDK サンプルが用意されています。 これらのサンプルでは、ストレージ BLOB の操作中に一般的に発生するその他のシナリオのコード例を示します。

  • blob_samples_container_access_policy.py (非同期バージョン) - アクセス ポリシーを設定する例:

    • コンテナーのアクセス ポリシーを設定する

  • blob_samples_hello_world.py (非同期バージョン) - 一般的なストレージ BLOB タスクの例:

    • コンテナーを設定する
    • ブロック、ページ、または追加 BLOB を作成する
    • BLOB をアップロードする
    • BLOB をダウンロードする
    • BLOB を削除する

  • blob_samples_authentication.py (非同期バージョン) - クライアントの認証と作成の例:

    • 接続文字列から
    • 共有アクセス キーから
    • Shared Access Signature トークンから
    • Active Directory から

  • blob_samples_service.py (非同期バージョン) - BLOB サービスを操作する例:

    • アカウント情報の取得
    • サービス プロパティを取得および設定する
    • サービス統計を取得する
    • コンテナーの作成、一覧表示、削除
    • BLOB またはコンテナー クライアントを取得する

  • blob_samples_containers.py (非同期バージョン) - コンテナーを操作する例:

    • コンテナーを作成してコンテナーを削除する
    • コンテナーにメタデータを設定する
    • コンテナーのプロパティを取得する
    • コンテナーのリースを取得する
    • コンテナーにアクセス ポリシーを設定する
    • コンテナー内の BLOB をアップロード、一覧表示、削除する
    • 特定の BLOB と対話する BLOB クライアントを取得する

  • blob_samples_common.py (非同期バージョン) - すべての種類の BLOB に共通する例:

    • スナップショットの作成
    • BLOB スナップショットを削除する
    • BLOB を論理的に削除する
    • BLOB の削除を取り消す
    • BLOB のリースを取得する
    • URL から BLOB をコピーする

  • blob_samples_directory_interface.py - Blob Storage とファイルシステム上のディレクトリのように接続する例:

    • 1 つのファイルまたはディレクトリをコピー (アップロードまたはダウンロード) する
    • 1 つのレベルまたは再帰的にファイルまたはディレクトリを一覧表示する
    • 1 つのファイルを削除するか、ディレクトリを再帰的に削除する

その他のドキュメント

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

共同作成

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

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

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