使用 Python 管理容器属性和元数据

项目
10/15/2024

除 Blob 容器包含的数据外，它们还支持系统属性和用户定义的元数据。本文介绍如何使用适用于 Python 的 Azure 存储客户端库管理系统属性和用户定义元数据。

若要了解如何使用异步 API 来管理属性和元数据，请参阅异步设置容器元数据。

先决条件

Azure 订阅 - 创建试用订阅。
Azure 存储帐户 - 创建存储帐户
Python 3.8+

设置你的环境

如果没有现有项目，请查看本部分，其中介绍如何设置项目来使用适用于 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

授权

授权机制必须具有处理容器属性或元数据所需的权限。若要使用 Microsoft Entra ID 进行授权（建议），需具有 Azure RBAC 内置角色“存储 Blob 数据读取者”或更高级别的角色以便能够执行获取操作，并具有“存储 Blob 数据参与者”或更高级别的角色以便能够执行设置操作。有关详细信息，请参阅获取容器属性 (REST API)、设置容器元数据 (REST API) 或获取容器元数据 (REST API) 的授权指南。

创建客户端对象

若要将应用连接到 Blob 存储，请创建 BlobServiceClient 的实例。以下示例演示如何使用 DefaultAzureCredential 创建客户端对象进行授权：

# TODO: Replace <storage-account-name> with your actual storage account name
account_url = "https://<storage-account-name>.blob.core.chinacloudapi.cn"
credential = DefaultAzureCredential()

# Create the BlobServiceClient object
blob_service_client = BlobServiceClient(account_url, credential=credential)

还可以为特定容器或 Blob 创建客户端对象，不管是直接创建还是通过 BlobServiceClient 对象创建。要详细了解如何创建和管理客户端对象，请参阅创建和管理与数据资源交互的客户端对象。

关于属性和元数据

系统属性：每个 Blob 存储资源上都存在系统属性。其中一些属性是可以读取或设置的，而另一些属性是只读的。部分系统属性在“幕后”是与某些标准 HTTP 标头对应的。适用于 Python 的 Azure 存储客户端库将维护这些属性。
用户定义的元数据：用户定义元数据包含一个或多个你为 Blob 存储资源指定的名称/值对对。可以使用元数据存储资源的其他值。元数据值仅用于你自己的目的，不会影响资源的行为方式。

元数据名称/值对是有效的 HTTP 标头，因此应当遵循所有控制 HTTP 标头的限制。有关元数据命名要求的详细信息，请参阅元数据名称。

检索容器属性

若要检索容器属性，请使用以下方法：

ContainerClient.get_container_properties

以下代码示例提取容器的系统属性，并将属性值写入到控制台窗口：

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 或容器资源上的一个或多个名称/值对。若要设置元数据，请使用以下方法：

ContainerClient.set_container_metadata

设置容器元数据将覆盖与容器关联的所有现有元数据。无法修改单个名称-值对。

以下代码示例设置容器上的元数据：

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)

若要检索元数据，请调用以下方法：

ContainerClient.get_container_properties

以下示例读取元数据值：

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 存储客户端库设置和检索容器属性和元数据，请参阅以下资源。

代码示例

查看本文中的同步或异步代码示例 (GitHub)

REST API 操作

Azure SDK for Python 包含基于 Azure REST API 而生成的库，允许你通过熟悉的 Python 范例与 REST API 操作进行交互。用于设置和检索属性和元数据的客户端库方法使用以下 REST API 操作：

get_container_properties 方法通过调用获取容器属性操作和获取容器元数据操作来检索容器属性和元数据。

客户端库资源

本文是 Python 版 Blob 存储开发人员指南的一部分。若要了解详细信息，请参阅生成 Python 应用中的开发人员指南文章的完整列表。

通过