分享方式：

使用 Python 列出 Blob 容器

  • 文章

當您從程式碼列出 Azure 儲存體中的容器時，可以指定數個選項來管理從 Azure 儲存體傳回結果的方式。 本文說明如何使用適用於 Python 的 Azure 儲存體用戶端程式庫列出容器。

若要了解如何使用非同步 API 列出 Blob 容器，請參閱以非同步方式列出容器。

必要條件

設定您的環境

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

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

安裝套件

使用 pip install 安裝下列套件：

pip install azure-storage-blob azure-identity

新增 import 陳述式

加入下列 import 陳述式：

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient

授權

授權機制必須具有列出 Blob 容器的必要權限。 如需使用 Microsoft Entra ID 授權 (建議使用)，您需要 Azure RBAC 內建角色儲存體 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)

您也可以直接或從 BlobServiceClient 物件建立特定容器或 Blob 的用戶端物件。 若要深入了解如何建立及管理用戶端物件，請參閱建立和管理與資料資源互動的用戶端端物件 (部分機器翻譯)。

關於容器清單選項

從程式碼列出容器時，可以指定若干選項來管理從 Azure 儲存體傳回結果的方式。 您可指定要在每一組結果中傳回的結果數目，然後擷取後續集合。 您也可以按前置詞篩選結果，在結果中傳回容器中繼資料。 下列各節描述這些選項。

若要列出儲存體帳戶中的容器，請呼叫下列方法：

此方法會傳回可反覆執行的類型 ContainerProperties。 容器會依名稱按字典順序排序。

管理傳回的結果數目

根據預設，清單作業一次最多會傳回 5000 個結果。 若要傳回較小的結果集，請為 results_per_page 關鍵字引數提供非零值。

使用前置詞篩選結果

若要篩選容器清單，請為 name_starts_with 關鍵字引數指定字串或字元。 前置詞字串可包含一或多個字元。 Azure 儲存體接著只會傳回名稱開頭為該前置詞的容器。

包含容器中繼資料

若要在結果中包含容器中繼資料，請將 include_metadata 關鍵字引數設為 True。 Azure 儲存體包含中繼資料與每個傳回的容器，因此您無須個別擷取容器中繼資料。

包含已刪除的容器

若要在結果中包含虛刪除的容器，請將 include_deleted 關鍵字引數設為 True。

程式碼範例

下列範例會列出所有容器和中繼資料。 您可以將 include_metadata 設為 True，以包含容器中繼資料：

def list_containers(self, blob_service_client: BlobServiceClient):
    containers = blob_service_client.list_containers(include_metadata=True)
    for container in containers:
        print(container['name'], container['metadata'])

下列範例只會列出以 name_starts_with 參數中指定的前置詞為開頭的容器：

def list_containers_prefix(self, blob_service_client: BlobServiceClient):
    containers = blob_service_client.list_containers(name_starts_with='test-')
    for container in containers:
        print(container['name'])

您也可以為每個頁面的結果數目指定限制。 此範例會傳入 results_per_page 並將結果分頁：

def list_containers_pages(self, blob_service_client: BlobServiceClient):
    i=0
    all_pages = blob_service_client.list_containers(results_per_page=5).by_page()
    for container_page in all_pages:
        i += 1
        print(f"Page {i}")
        for container in container_page:
            print(container['name'])

以非同步方式列出容器

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

依照下列步驟，使用非同步 API 列出容器：

  1. 新增下列匯入陳述式：

    import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient

  2. 新增程式碼以使用 asyncio.run 執行程式。 此函式會執行傳遞的協同程式 (在我們的範例中為 main())，並管理 asyncio 事件迴圈。 協同程式會以 async/await 語法宣告。 在此範例中，main() 協同程式會先使用 async with 建立最上層 BlobServiceClient，然後呼叫列出容器的方法。 請注意，只有最上層用戶端需要使用 async with，因為從中建立的其他用戶端會共用相同的連線集區。

    async def main():
    sample = ContainerSamples()

    # 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_containers(blob_service_client)

if __name__ == '__main__':
    asyncio.run(main())

  3. 新增程式碼以列出容器。 該程式碼與同步範例相同，不同之處在於該方法是以 async 關鍵字宣告的，而 async for 是在呼叫 list_containers 方法時使用的。

    async def list_containers(self, blob_service_client: BlobServiceClient):
    async for container in blob_service_client.list_containers(include_metadata=True):
        print(container['name'], container['metadata'])

完成這個基本設定後，您可以使用 async/await 語法，將本文中的其他範例實作為協同程式。

資源

若要深入了解如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫列出容器，請參閱下列資源。

程式碼範例

REST API 操作

Azure SDK for Python 包含建置在 Azure REST API 之上的程式庫，可讓您透過熟悉的 Python 範例與 REST API 作業進行互動。 用來列出容器的用戶端程式庫方法會使用下列 REST API 作業：

用戶端程式庫資源

另請參閱

相關內容

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