使用 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 语句:
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.chinacloudapi.cn"
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
关键字,调用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 语法将本文中的其他示例实现为协同例程。
资源
若要详细了解如何使用适用于 Python 的 Azure Blob 存储客户端库来列出 blob,请参阅以下资源。
REST API 操作
Azure SDK for Python 包含基于 Azure REST API 而生成的库,允许你通过熟悉的 Python 范例与 REST API 操作进行交互。 用于列出 blob 的客户端库方法使用以下 REST API 操作:
- 列出 Blob (REST API)