通过 Python 使用 Blob 索引标记来管理和查找数据

本文介绍如何使用 Blob 索引标记通过适用于 Python 的 Azure 存储客户端库来管理和查找数据。

若要了解如何使用异步 API 设置 blob 索引标记,请参阅异步设置 blob 索引标记

先决条件

设置你的环境

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

授权

授权机制必须具有使用 blob 索引标记所需的权限。 要使用 Microsoft Entra ID 进行授权(建议),需有 Azure RBAC 内置角色存储 Blob 数据所有者或更高级别的角色。 若要了解详细信息,请参阅获取 Blob 标记 (REST API)设置 Blob 标记 (REST API)按标记查找 Blob (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 索引标记

Blob 索引标记使用键值标记属性对存储帐户中的数据进行分类。 这些标记会自动索引,并作为可搜索的多维索引公开,便于你轻松查找数据。 本文介绍了如何使用 blob 索引标记来设置、获取和查找数据。

启用了分层命名空间的存储帐户不支持 Blob 索引标记。 若要详细了解 Blob 索引标记功能以及已知问题和限制,请参阅通过 Blob 索引标记管理和查找 Azure Blob 数据

设置标记

如果代码通过以下一种机制授权访问 Blob 数据,则可以设置索引标记:

有关详细信息,请参阅设置 Blob 索引标记

可以使用以下方法设置标记:

此方法中的指定标记将替换现有标记。 如果必须保留旧值,则必须下载这些值并将其包含在对此方法的调用中。 以下示例介绍如何设置标记:

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

    # Get any existing tags for the blob if they need to be preserved
    tags = blob_client.get_blob_tags()

    # Add or modify tags
    updated_tags = {'Sealed': 'false', 'Content': 'image', 'Date': '2022-01-01'}
    tags.update(updated_tags)

    blob_client.set_blob_tags(tags)

可以通过将空 dict 对象传递到 set_blob_tags 方法来删除所有标记:

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

    # Pass in empty dict object to clear tags
    tags = dict()
    blob_client.set_blob_tags(tags)

获取标记

如果代码通过以下一种机制授权访问 Blob 数据,则可以获取索引标记:

有关详细信息,请参阅获取和列出 Blob 索引标记

可以使用以下方法获取标记:

以下示例演示如何检索和循环访问 Blob 的标记:

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

    tags = blob_client.get_blob_tags()
    print("Blob tags: ")
    for k, v in tags.items():
        print(k, v)

通过 Blob 索引标记筛选和查找数据

如果代码通过以下一种机制授权访问 Blob 数据,则可以使用索引标记来查找和筛选数据:

有关详细信息,请参阅使用 Blob 索引标记查找数据

注意

不能使用索引标记来检索以前的版本。 以前版本的标记不会传递给 blob 索引引擎。 有关详细信息,请参阅条件和已知问题

你可以使用以下方法查找数据:

以下示例查找并列出了标记为图像的所有 Blob:

def find_blobs_by_tags(self, blob_service_client: BlobServiceClient, container_name):
    container_client = blob_service_client.get_container_client(container=container_name)

    query = "\"Content\"='image'"
    blob_list = container_client.find_blobs_by_tags(filter_expression=query)
    
    print("Blobs tagged as images")
    for blob in blob_list:
        print(blob.name)

异步设置 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_blob_tags(blob_service_client, "sample-container")

if __name__ == '__main__':
    asyncio.run(main())
  1. 添加代码以设置 Blob 索引标记。 该代码与同步示例相同,不同之处在于:该方法是使用 async 关键字声明的,但在调用 get_blob_tagsset_blob_tags 方法时使用 await 关键字。
async def set_blob_tags(self, blob_service_client: BlobServiceClient, container_name):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")

    # Get any existing tags for the blob if they need to be preserved
    tags = await blob_client.get_blob_tags()

    # Add or modify tags
    updated_tags = {'Sealed': 'false', 'Content': 'image', 'Date': '2022-01-01'}
    tags.update(updated_tags)

    await blob_client.set_blob_tags(tags)

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

资源

若要详细了解如何使用索引标记通过适用于 Python 的 Azure Blob 存储客户端库管理和查找数据,请参阅以下资源。

代码示例

REST API 操作

Azure SDK for Python 包含基于 Azure REST API 而生成的库,允许你通过熟悉的 Python 范例与 REST API 操作进行交互。 用于管理和使用 Blob 索引标记的客户端库方法使用以下 REST API 操作:

客户端库资源

请参阅

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