使用 Python 列出 Blob 物件

本文說明如何使用 Python 的 Azure 儲存體用戶端函式庫來列出 blobs。

想了解如何使用非同步 API 來列出 blobs，請參見「 List blobs asynchronously」。

必要條件

Azure 訂用帳戶 - 建立免費帳戶
Azure 儲存體帳戶 - 建立儲存體帳戶
Python 3.8+

設定您的環境

如果沒有現有的專案，本章節會說明如何設定專案以使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫。如需詳細資訊，請參閱開始使用 Azure Blob 儲存體和 Python。

若要使用本文中的程式碼範例，請遵循下列步驟來設定您的專案。

安裝套件

使用 pip install 安裝下列套件：

pip install azure-storage-blob azure-identity

新增匯入陳述句

加入下列 import 陳述式：

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

授權

授權機制必須具有列出 Blob 的必要權限。若要使用 Microsoft Entra ID 進行授權（建議），您需要 Azure RBAC 內建角色 Storage Blob Data Reader 或更高層級的角色。若要深入了解，請參閱列出 Blob (REST API) 的授權指引。

建立用戶端物件

若要將應用程式連線至 Blob 儲存體，請建立 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 清單選項

當您在程式碼中列出 Blob 時，可以指定許多選項，以管理 Azure 儲存體傳回結果的方式。您可指定要在每一組結果中傳回的結果數目，然後擷取後續集合。您可以指定前置詞，以傳回名稱以該字元或字串開頭的 Blob。您可以用簡單清單結構列出 Blob，或以階層方式列出 Blob。階層式清單會透過將 Blob 組織成資料夾的方式傳回 Blob。

若要使用平面列表來列出容器中的斑點，請呼叫以下其中一種方法：

ContainerClient.list_blobs （除了名稱外，可選擇性地包含與每個 blob 相關的元資料、標籤及其他資訊）
ContainerClient.list_blob_names (只傳回 Blob 名稱)

要使用階層式列表來列出容器中的 blob，請呼叫以下方法：

ContainerClient.walk_blobs （除了名稱外，可選擇性地包含與每個 blob 相關的元資料、標籤及其他資訊）

使用前置詞篩選結果

若要篩選 Blob 清單，請指定 name_starts_with 關鍵字引數的字串。前置詞字串可包含一或多個字元。 Azure 儲存體只會回傳以該前綴開頭的 blob。

簡單列表與階層式清單

Azure 儲存體中的 Blob 是以簡單架構進行組織，而不是階層式架構 (例如傳統檔案系統)。不過，你可以將 blobs 組織成 虛擬目錄 ，模擬資料夾結構。虛擬目錄會形成 Blob 名稱的一部分，並以分隔符號表示。

若要將 Blob 組織成虛擬目錄，請在 Blob 名稱中使用分隔符號。預設的分隔符號是正斜線 (/)，但可指定任何字元作為分隔符號。

如果您使用分隔符號為 Blob 命名，則可以選擇以階層方式列出 Blob。對於階層式清單作業，Azure 儲存體會傳回父物件下方的任何虛擬目錄和 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'}

注意

所示的範例輸出是假設您有一個採用扁平命名空間的儲存體帳戶。如果你啟用了儲存帳號的階層命名空間功能，目錄就不是虛擬的。相反地，它們是具體且獨立的物件。因此，目錄會以零長度 Blob 的形式出現在清單中。

如需使用階層命名空間時的替代清單選項，請參閱列出目錄內容 (Azure Data Lake Storage)。

使用階層式清單

當以階層方式呼叫清單作業時，Azure 儲存體會傳回階層第一層級的虛擬目錄和 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 快照無法在階層式列出作業中列出。

以非同步方式列出 Blob

適用於 Python 的 Azure Blob 儲存體用戶端程式庫支援以非同步方式列出 Blob。若要深入了解專案設定需求，請參閱非同步程式設計。

請依照下列步驟，使用非同步 API 列出 Blob：

新增下列匯入陳述式：

import asyncio

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

新增可使用 asyncio.run 執行程式的程式碼。此函式會執行傳入的協程（在此範例中為 main()），並管理 asyncio 事件迴圈。協同程式是使用 async/await 語法宣告。在此範例中，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 ，呼叫 async for 時使用 list_blobs 。

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/wait 語法實作本文其他範例作為協程。

以 Apache Arrow 格式列出 Blob (預覽)

Important

Apache Arrow 格式的 blob 列表目前處於預覽階段。此情境需要 Python Azure Blob 儲存體用戶端函式庫的測試版（預覽版）（例如 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 格式列出 Blob。

若要要求 Apache Arrow 格式的結果，請在呼叫 ContainerClient.list_blobs 或 ContainerClient.list_blob_names 時，將關鍵字引數 response_format 設為 "arrow"。使用 Apache Arrow 輸出時，你也可以設定 start_from 和 end_before 關鍵字參數來控制回傳路徑的範圍。

注意

使用 response_format="arrow" 時必須安裝 nanoarrow 套件。

以下範例列出容器中的 blob，並以 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 儲存體用戶端函式庫來列出 blob，請參閱以下資源。

程式碼範例

可參考本文（GitHub）中的同步或非同步程式碼範例。

REST API 操作

Azure SDK for Python 包含建立在 Azure REST API 之上的函式庫。透過使用這些函式庫，你可以透過熟悉的 Python 範式與 REST API 操作互動。用來列出 Blob 的用戶端程式庫方法會使用下列 REST API 作業：

列出 Blob 清單 (REST API)

用戶端程式庫資源

另請參閱

本文是適用於 Python 的 Blob 儲存體開發人員指南的一部分。若要深入了解，請參閱建置 Python 應用程式中的開發人員指南文章完整清單。

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-09-02

使用 Python 列出 Blob 物件

必要條件

設定您的環境

安裝套件

新增匯入陳述句

授權

建立用戶端物件

關於 Blob 清單選項

使用前置詞篩選結果

簡單列表與階層式清單

使用簡單列表

使用階層式清單

以非同步方式列出 Blob

以 Apache Arrow 格式列出 Blob (預覽)

資源

程式碼範例

REST API 操作

用戶端程式庫資源

另請參閱

相關內容

意見反應

其他資源