使用 Python 列出 Blob
本文說明如何使用適用於 Python 的 Azure 儲存體用戶端程式庫來列出 Blob。
若要了解如何使用非同步 API 列出 Blob,請參閱以非同步方式列出 Blob。
必要條件
- 本文假設您已有專案設定為使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫。 若要了解如何設定您的專案,包括安裝套件、新增
import
陳述式,以及建立授權的用戶端物件,請參閱開始使用 Azure Blob 儲存體和 Python。 - 若要在程式代碼中使用非同步 API,請參閱非同步程式設計一節中的需求。
- 授權機制必須具有列出 Blob 的權限。 若要深入了解,請參閱下列 REST API 作業的授權指引:
關於 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 是以簡單架構進行組織,而不是階層式架構 (例如傳統檔案系統)。 不過,您可將 Blob 組織成「虛擬目錄」,以便模擬資料夾結構。 虛擬目錄會形成 Blob 名稱的一部分,並以分隔符號表示。
若要將 Blob 組織成虛擬目錄,請在 Blob 名稱中使用分隔符號。 預設的分隔符號是正斜線 (/),但可指定任何字元作為分隔符號。
如果使用分隔符號來命名 Blob,則可選擇以階層方式列出 Blob。 針對階層式清單作業,Azure 儲存體會傳回父物件底下的任何虛擬目錄和 Blob。 您可遞迴呼叫清單作業來周遊階層,類似於以程式設計方式周遊傳統檔案系統的方式。
使用簡單列表
根據預設,清單作業會以簡單列表傳回 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 Gen2)。
使用階層式清單
當以階層方式呼叫清單作業時,Azure 儲存體會在階層的第一個層級傳回虛擬目錄和 Blob。
若要以階層方式列出 Blob,請使用下列方法:
下列範例使用階層式清單列出所指定容器中的 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
,然後呼叫列出 Blob 的方法。 請注意,只有最上層用戶端需要使用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。 下列程式碼範例會使用簡單列表列出 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/await 語法,將本文中的其他範例實作為協同程式。
資源
若要深入了解如何使用適用於 Python 的 Azure Blob 儲存體用戶端程式庫列出 Blob,請參閱下列資源。
REST API 操作
Azure SDK for Python 包含建置在 Azure REST API 之上的程式庫,可讓您透過熟悉的 Python 範例與 REST API 作業進行互動。 用來列出 Blob 的用戶端程式庫方法會使用下列 REST API 作業:
- 列出 Blob (REST API)