Python を使用して BLOB を一覧表示する

この記事では、PythonのAzure Storageクライアントライブラリを使ってブロブをリストアップする方法を紹介しています。

非同期APIを使ったリストブロブについて学ぶには、「 List blobs asynchronously」をご覧ください。

前提条件

Azure サブスクリプション - 無料アカウントを作成する
Azure Storage アカウント - ストレージアカウントの作成
Python 3.8+

環境を設定する

既存のプロジェクトがない場合、Python 用 Azure Blob Storage クライアントライブラリを操作するためのプロジェクトをセットアップする方法についてこのセクションで説明します。詳細については、「Azure Blob Storage と Python で作業を開始する」を参照してください。

この記事のコード例を使用するには、次の手順に従ってプロジェクトを設定します。

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

pip install を使用して次のパッケージをインストールしてください。

pip install azure-storage-blob azure-identity

import ステートメントを追加する

次の import ステートメントを追加します。

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

認可

認可メカニズムには、BLOB を一覧表示するために必要なアクセス許可が必要です。 Microsoft Entra IDでの認証(推奨)には、Azure RBACの組み込みロールであるStorage Blob Data Reader以上のものが必要です。詳細については、List Blobs (REST API) の「認可」のガイダンスを参照してください。

クライアントオブジェクトの作成

アプリを Blob Storage に接続するには、 BlobServiceClientのインスタンスを作成します。次の例では、認可のために DefaultAzureCredential を使用してクライアントオブジェクトを作成する方法を示します。

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.windows.net"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

また、特定のコンテナーまたは BLOB 用のクライアントオブジェクトを、直接または BlobServiceClient オブジェクトから作成することもできます。クライアントオブジェクトの作成と管理の詳細については、「データリソースを操作するクライアントオブジェクトを作成および管理する」を参照してください。

Blob の一覧表示オプションについて

コードからブロブをリストアップする際、Azure Storageから結果の返り方を管理するための多くのオプションを指定できます。各結果セットで返す結果の数を指定し、後続のセットを取得できます。名前がその文字または文字列から始まる BLOB を返すようにプレフィックスを指定できます。ブロブはフラットなリスト構造でリストアップすることも、階層的にリストアップすることもできます。階層リストでは、フォルダーに整理されたかのように BLOB が返されます。

フラットリストリングを使ってコンテナ内のブロブをリストアップするには、以下のいずれかのメソッドを呼び出してください:

ContainerClient.list_blobs (名前とともに、必要に応じて各ブロブに関連するメタデータ、タグ、その他の情報を含めることも可能です)
ContainerClient.list_blob_names (BLOB 名のみを返します)

階層的リストングを使ってコンテナ内のブロブをリストアップするには、以下のメソッドを呼び出します:

ContainerClient.walk_blobs (名前とともに、各ブロブに関連するメタデータ、タグ、その他の情報を含めることも可能)

プレフィックスを使用して結果をフィルター処理する

BLOB の一覧をフィルター処理するには、name_starts_with キーワード引数の文字列を指定します。プレフィックス文字列には、1 つ以上の文字を含めることができます。 Azure Storageは、名前がその接頭辞で始まるブロブのみを返します。

フラットな一覧表示と階層的な一覧表示

Azure Storage の BLOB は、(従来のファイルシステムのような) 階層的なパラダイムではなく、フラットなパラダイムで組織化されます。ただし、フォルダ構造を模倣するためにブロブを 仮想ディレクトリ に整理することは可能です。仮想ディレクトリは BLOB 名の一部を形成し、区切り文字によって示されます。

BLOB を仮想ディレクトリに組織化するには、BLOB 名に区切り文字を使用します。既定の区切り文字はスラッシュ (/) ですが、区切り文字として任意の文字を指定できます。

区切り符を使ってブロブに名前を付ければ、階層的にリストアップすることができます。階層的な一覧表示操作の場合、Azure Storage は、親オブジェクトの下にあるすべての仮想ディレクトリと BLOB を返します。従来のファイルシステムをプログラムで走査するのと同じような方法で、一覧表示操作を再帰的に呼び出して階層を走査することができます。

フラットな一覧表示を使用する

既定では、一覧表示操作はフラットな一覧表示で BLOB を返します。フラットな一覧表示では、BLOB は仮想ディレクトリ別に整理されません。

以下の例は、指定されたコンテナ内のブロブをフラットリスト(フラットリスト)でリストアップしています:

def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

サンプル出力は次のようになります。

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

また、結果をリストアップしたり、追加情報を表示したりするオプションを指定することもできます。次の例では、BLOB と BLOB タグ一覧が表示されます:

def list_blobs_flat_options(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

サンプル出力は次のようになります。

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

注

次に示すサンプル出力では、フラット型名前空間を持つストレージアカウントがあることを前提としています。ストレージアカウントで階層的な名前空間機能を有効にすると、ディレクトリは仮想ではありません。むしろ、それらは具体的で独立したオブジェクトです。その結果、ディレクトリは長さ 0 の BLOB として一覧に表示されます。

階層型名前空間を使って作業する場合の別のリストオプションについては、「ディレクトリの内容を一覧表示する (Azure Data Lake Storage)」を参照してください。

階層的な一覧表示を使用する

一覧表示操作を階層的に呼び出すと、Azure Storage は、階層の最初のレベルに仮想ディレクトリと BLOB を返します。

BLOB を階層的に一覧表示するには、次のメソッドを使用します。

ContainerClient.walk_blobs

次の例では、階層的な一覧表示を使用して、指定されたコンテナー内の BLOB を一覧表示します。

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

サンプル出力は次のようになります。

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

注

ブロブスナップショットは階層的なリスト操作でリストすることはできません。

BLOB を非同期で一覧表示する

Python 用 Azure Blob Storage クライアントライブラリでは、BLOB の非同期一覧表示がサポートされています。プロジェクトのセットアップ要件の詳細については、非同期プログラミングに関する記事を参照してください。

非同期APIを使ってブロブをリストアップするには以下の手順に従ってください:

次の import ステートメントを追加します。

import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, ContainerClient, BlobPrefix

asyncio.runを使ってプログラムを実行するコードを追加してください。この関数は、この例で main() されるパスされたコルーチンを実行し、 asyncio イベントループを管理します。コルーチンはasync/wait構文を使って宣言されます。この例では、main()コルーチンがまずasync withを使って最上層BlobServiceClientを作成し、その後ブロブをリストアップするメソッドを呼び出します。最上位のクライアントのみで async with を使用する必要があります。ここから作成された他のクライアントでは同じ接続プールを共有するためです。
```
async def main():
    sample = BlobSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    credential = DefaultAzureCredential()

    async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
        await sample.list_blobs_flat(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())
```
BLOB を一覧表示するコードを追加します。以下のコード例は、フラットリストを使ってブロブを一覧化しています。コードは同期例と同じですが、メソッドはasyncキーワードを用いて宣言され、list_blobsメソッドを呼び出す際にはasync forが使われます。
```
async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    async for blob in container_client.list_blobs():
        print(f"Name: {blob.name}")
```

この基本的な設定があれば、async/await構文を使ってこの記事の他の例もコルーチンとして実装できます。

Apache Arrow形式のリストブロブ(プレビュー)

Important

Apache Arrow形式でのブロブ表示は現在 プレビュー中です。このシナリオでは、Python用のAzure Blob Storageクライアントライブラリのベータ(プレビュー版)が必要です(例:azure-storage-blob12.31.0b1以降のプレビューリリース)。プレビュー機能は、サービスレベルアグリーメントなしで提供され、運用環境のワークロードには推奨されません。一部の機能はサポートされていないか、機能が制限されている場合があります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

この機能は既存の List Blobs APIを基盤としています。デフォルトのXMLを使う代わりに、ワイヤー上のレスポンス形式としてコンパクトで列状の Apache Arrow 形式を使用しています。コンテナリスティングコールで単一のオプションを設定することで有効化できます。 Python SDKは裏でApache Arrowを復号し、同じBlobPropertiesオブジェクトを返します。この方法は、大規模なコンテナを列挙する際にリストスループットを向上させ、クライアント側のCPUを削減します。これは、アプリケーションが依存する応答契約を保持します。

Warning

階層的な名前空間(Azure Data Lake Storage)が有効になっているストレージアカウントでは、Apache Arrow形式でのブロブ表示はサポートされていません。

Apache Arrow形式の結果を要求するには、ContainerClient.list_blobsまたはContainerClient.list_blob_namesを呼び出す際にresponse_formatキーワード引数を"arrow"に設定してください。 Apache Arrow出力を使う場合、 start_from や end_before キーワード引数を設定して、返されるパスの範囲を制御することもできます。

注

response_format="arrow"を使うにはnanoarrowパッケージをインストールする必要があります。

以下の例はコンテナ内のブロブを一覧にし、Apache Arrow形式で結果をリクエストします:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

リソース

Python用のAzure Blob Storageクライアントライブラリを使ってブロブをリストアップする方法について詳しく知りたい方は、以下のリソースをご覧ください。

コードサンプル

この記事(GitHub)から同期または非同期のコードサンプルをご覧ください。

REST API の操作

Azure SDK for Pythonには、Azure REST APIの上に構築されたライブラリが含まれています。これらのライブラリを使うことで、馴染みのあるPythonパラダイムを通じてREST API操作とやり取りできます。 BLOB を一覧表示するためのクライアントライブラリメソッドは、次の REST API 操作を使用します。

BLOB の一覧表示 (REST API)

クライアントライブラリのリソース

こちらもご覧ください

この記事は、Python の Blob Storage 開発者ガイドの一部です。詳細については、「Python アプリの構築」にある開発者ガイドの記事の完全な一覧を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-27

Python を使用して BLOB を一覧表示する

前提条件

環境を設定する

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

import ステートメントを追加する

認可

クライアント オブジェクトの作成

Blob の一覧表示オプションについて

プレフィックスを使用して結果をフィルター処理する

フラットな一覧表示と階層的な一覧表示

フラットな一覧表示を使用する

階層的な一覧表示を使用する

BLOB を非同期で一覧表示する

Apache Arrow形式のリストブロブ(プレビュー)

リソース

コード サンプル

REST API の操作

クライアント ライブラリのリソース

こちらもご覧ください

関連するコンテンツ

フィードバック

その他のリソース

クライアントオブジェクトの作成

コードサンプル

クライアントライブラリのリソース