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

[アーティクル]
11/09/2023

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

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

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

作業の開始

前提条件

このパッケージを使用するには、Python 3.7 以降が必要です。詳細については、 Azure SDK for Python バージョンのサポートポリシーに関するページを参照してください。
このパッケージを使用するには、 Azure サブスクリプションと Azure ストレージアカウントが必要です。

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

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 、使用する承認の種類に応じて、さまざまな形式で指定できます。

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

これには、いくつかの初期セットアップが必要です。
- azure-identity をインストールする
- 新しい AAD アプリケーションを登録し、Azure Storage にアクセスするためのアクセス許可を付与する
- Azure Portal で RBAC を使用して Azure BLOB データへのアクセスを許可する
- AAD アプリケーションのクライアント ID、テナント ID、クライアントシークレットの値を環境変数として設定します(AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET
返されたトークン資格情報を使用してクライアントを認証します。
```
    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
    )
```

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)

ストレージアカウント共有キー (アカウントキーまたはアクセスキーとも呼ばれます) を使用するには、キーを文字列として指定します。これは、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>"})
```
匿名パブリック読み取りアクセスを使用するには、単に 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 つの異なるクライアントが用意されています。

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

次の方法で共有

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

作業の開始

前提条件

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

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

クライアントを作成する

アカウント URL を検索する

資格情報の種類

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

主要な概念

クライアント

非同期クライアント

BLOB の種類

例

コンテナーを作成する

BLOB のアップロード

BLOB のダウンロード

BLOB の列挙

オプションの構成

再試行ポリシーの構成

暗号化の構成

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

トラブルシューティング

全般

ログの記録

次のステップ

その他のサンプルコード

その他のドキュメント

共同作成

その他のリソース

次の方法で共有

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

作業の開始

前提条件

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

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

クライアントを作成する

アカウント URL を検索する

資格情報の種類

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

主要な概念

クライアント

非同期クライアント

BLOB の種類

例

コンテナーを作成する

BLOB のアップロード

BLOB のダウンロード

BLOB の列挙

オプションの構成

再試行ポリシーの構成

暗号化の構成

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

トラブルシューティング

全般

ログの記録

次のステップ

その他のサンプル コード

その他のドキュメント

共同作成

その他のリソース

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

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

その他のサンプルコード