使用 Python 管理 blob 属性和元数据

  • 项目

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

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

先决条件

关于属性和元数据

  • 系统属性：系统属性存在于每个 Blob 存储资源上。 其中一些属性是可以读取或设置的，而另一些属性是只读的。 事实上，有些系统属性与某些标准 HTTP 标头对应。 适用于 Python 的 Azure 存储客户端库将维护这些属性。

  • 用户定义的元数据：用户定义元数据包含一个或多个你为 Blob 存储资源指定的名称/值对对。 可以使用元数据存储资源的其他值。 元数据值仅用于你自己的目的，不会影响资源的行为方式。

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

注意

使用 Blob 索引标记，还可以将任意用户定义的键/值属性与 Azure Blob 存储资源一起存储。 虽然与元数据类似，但只会自动为 Blob 索引标记编制索引，并由本机的 blob 服务进行搜索。 除非使用了单独的服务（如 Azure 搜索），否则无法对元数据进行索引和查询。

若要详细了解此功能，请参阅通过 Blob 索引（预览版）管理和查找 Azure Blob 存储上的数据。

设置和检索属性

若要在 blob 上设置属性，请使用以下方法：

清除未显式设置的任何属性。 若要保留任何现有属性，可以先检索 Blob 属性，然后使用它们填充未更新的标头。

以下代码示例设置 Blob 上的 content_type 和 content_language 系统属性，同时保留现有属性：

def set_properties(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Get the existing blob properties
    properties = blob_client.get_blob_properties()

    # Set the content_type and content_language headers, and populate the remaining headers from the existing properties
    blob_headers = ContentSettings(content_type="text/plain",
                                   content_encoding=properties.content_settings.content_encoding,
                                   content_language="en-US",
                                   content_disposition=properties.content_settings.content_disposition,
                                   cache_control=properties.content_settings.cache_control,
                                   content_md5=properties.content_settings.content_md5)
    
    blob_client.set_http_headers(blob_headers)

若要检索 blob 上的属性，请使用以下方法：

以下代码示例获取 blob 的系统属性并显示一些值：

def get_properties(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    properties = blob_client.get_blob_properties()

    print(f"Blob type: {properties.blob_type}")
    print(f"Blob size: {properties.size}")
    print(f"Content type: {properties.content_settings.content_type}")
    print(f"Content language: {properties.content_settings.content_language}")

设置和检索元数据

可将元数据指定为 Blob 或容器资源上的一个或多个名称/值对。 若要设置元数据，请使用以下方法发送包含名称/值对的一个字典：

以下代码示例在 blob 上设置元数据：

def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    blob_metadata = blob_client.get_blob_properties().metadata

    more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
    blob_metadata.update(more_blob_metadata)

    # Set metadata on the blob
    blob_client.set_blob_metadata(metadata=blob_metadata)

要检索元数据，请对 blob 调用 get_blob_properties 方法以填充元数据集合，然后读取值，如下面的示例所示。 get_blob_properties 方法通过调用获取 Blob 属性操作和获取 Blob 元数据操作来检索 blob 属性和元数据。

下面的代码示例读取有关 blob 的元数据并打印每个键/值对：

def get_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    blob_metadata = blob_client.get_blob_properties().metadata

    for k, v in blob_metadata.items():
        print(k, v)

异步设置 blob 元数据

适用于 Python 的 Azure Blob 存储客户端库支持异步管理 blob 属性和元数据。 要详细了解项目设置要求，请参阅异步编程。

请按照以下步骤使用异步 API 设置 blob 元数据：

  1. 添加以下 import 语句：
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient
  1. 添加代码以使用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.set_metadata(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())
  1. 添加代码以设置 blob 元数据。 该代码与同步示例相同，不同之处在于：该方法是使用 async 关键字声明的，但在调用 get_blob_properties 和 set_blob_metadata 方法时使用 await 关键字。
async def set_metadata(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Retrieve existing metadata, if desired
    properties = await blob_client.get_blob_properties()
    blob_metadata = properties.metadata

    more_blob_metadata = {'docType': 'text', 'docCategory': 'reference'}
    blob_metadata.update(more_blob_metadata)

    # Set metadata on the blob
    await blob_client.set_blob_metadata(metadata=blob_metadata)

有了此基本设置，即可使用 async/await 语法将本文中的其他示例实现为协同例程。

资源

若要详细了解如何使用适用于 Python 的 Azure Blob 存储客户端库来管理系统属性和用户定义的元数据，请参阅以下资源。

REST API 操作

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

代码示例

客户端库资源