使用 Python 管理容器属性和元数据
除 Blob 容器包含的数据外,它们还支持系统属性和用户定义的元数据。 本文介绍如何使用适用于 Python 的 Azure 存储客户端库管理系统属性和用户定义元数据。
若要了解如何使用异步 API 来管理属性和元数据,请参阅异步设置容器元数据。
先决条件
- 本文假设已经设置了项目来使用适用于 Python 的 Azure Blob 存储客户端库。 若要了解如何设置项目(包括安装包、添加
import
语句和创建授权客户端对象),请参阅开始使用 Azure Blob 存储和 Python。 - 授权机制必须具有使用容器属性或元数据的权限。 若要了解详细信息,请参阅以下 REST API 操作的授权指南:
关于属性和元数据
系统属性:每个 Blob 存储资源上都存在系统属性。 其中一些属性是可以读取或设置的,而另一些属性是只读的。 部分系统属性在“幕后”是与某些标准 HTTP 标头对应的。 适用于 Python 的 Azure 存储客户端库将维护这些属性。
用户定义的元数据:用户定义元数据包含一个或多个你为 Blob 存储资源指定的名称/值对对。 可以使用元数据存储资源的其他值。 元数据值仅用于你自己的目的,不会影响资源的行为方式。
元数据名称/值对是有效的 HTTP 标头,因此应当遵循所有控制 HTTP 标头的限制。 有关元数据命名要求的详细信息,请参阅元数据名称。
检索容器属性
若要检索容器属性,请使用以下方法:
以下代码示例提取容器的系统属性,并将属性值写入到控制台窗口:
def get_properties(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
properties = container_client.get_container_properties()
print(f"Public access type: {properties.public_access}")
print(f"Lease status: {properties.lease.status}")
print(f"Lease state: {properties.lease.state}")
print(f"Has immutability policy: {properties.has_immutability_policy}")
设置和检索元数据
可将元数据指定为 Blob 或容器资源上的一个或多个名称/值对。 若要设置元数据,请使用以下方法:
设置容器元数据将覆盖与容器关联的所有现有元数据。 无法修改单个名称-值对。
以下代码示例设置容器上的元数据:
def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
# Retrieve existing metadata, if desired
metadata = container_client.get_container_properties().metadata
more_metadata = {'docType': 'text', 'docCategory': 'reference'}
metadata.update(more_metadata)
# Set metadata on the container
container_client.set_container_metadata(metadata=metadata)
若要检索元数据,请调用以下方法:
以下示例读取元数据值:
def get_metadata(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
# Retrieve existing metadata, if desired
metadata = container_client.get_container_properties().metadata
for k, v in metadata.items():
print(k, v)
异步设置容器元数据
适用于 Python 的 Azure Blob 存储客户端库支持异步管理容器属性和元数据。 要详细了解项目设置要求,请参阅异步编程。
请按照以下步骤使用异步 API 设置容器元数据:
- 添加以下 import 语句:
import asyncio
from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient
- 添加代码以使用
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.chinacloudapi.cn"
credential = DefaultAzureCredential()
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
await sample.set_metadata(blob_service_client, "sample-container")
if __name__ == '__main__':
asyncio.run(main())
- 添加代码以设置容器元数据。 该代码与同步示例相同,不同之处在于:该方法是使用
async
关键字声明的,但在调用get_container_properties
和set_container_metadata
方法时使用await
关键字。
async def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
container_client = blob_service_client.get_container_client(container=container_name)
# Retrieve existing metadata, if desired
metadata = (await container_client.get_container_properties()).metadata
more_metadata = {'docType': 'text', 'docCategory': 'reference'}
metadata.update(more_metadata)
# Set metadata on the container
await container_client.set_container_metadata(metadata=metadata)
有了此基本设置,即可使用 async/await 语法将本文中的其他示例实现为协同例程。
资源
若要详细了解如何使用适用于 Python 的 Azure Blob 存储客户端库设置和检索容器属性和元数据,请参阅以下资源。
REST API 操作
Azure SDK for Python 包含基于 Azure REST API 而生成的库,允许你通过熟悉的 Python 范例与 REST API 操作进行交互。 用于设置和检索属性和元数据的客户端库方法使用以下 REST API 操作:
get_container_properties
方法通过调用获取容器属性操作和获取容器元数据操作来检索容器属性和元数据。