Gerenciar propriedades de contêiner e metadados com o Python

Artigo
12/26/2023

Os contêineres de blob dão suporte a propriedades do sistema e metadados definidos pelo usuário, além dos dados que eles contêm. Este artigo mostra como gerenciar as propriedades do sistema e os metadados definidos pelo usuário usando a Biblioteca de clientes do Armazenamento do Microsoft Azure para Python.

Para saber mais sobre como gerenciar propriedades e metadados usando APIs assíncronas, consulte Definir metadados de contêiner de maneira assíncrona.

Pré-requisitos

Este artigo pressupõe que você já tenha um projeto configurado para trabalhar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Python. Para saber mais sobre como configurar seu projeto, incluindo a instalação de pacote, a adição de instruções de import e a criação de um objeto de cliente autorizado, consulte Introdução ao Armazenamento de Blobs do Azure e Python.
O mecanismo de autorização deve ter permissões para trabalhar com propriedades ou metadados de contêiner. Para saber mais, confira as diretrizes de autorização para as seguintes operações de API REST:

Propriedades e metadados

Propriedades do sistema: existem propriedades do sistema em cada recurso de Armazenamento de Blobs. Algumas podem ser lidas ou definidas, enquanto outras são de somente leitura. Nos bastidores, algumas propriedades do sistema correspondem a certos cabeçalhos HTTP padrão. A biblioteca de clientes do Armazenamento do Microsoft Azure para Python mantém essas propriedades para você.
Metadados definidos pelo usuário: os metadados definidos pelo usuário consistem em um ou mais pares nome-valor que você especifica para um recurso de armazenamento de Blob. É possível usar os metadados para armazenar valores adicionais com o recurso. Os valores de metadados são apenas para serem usados para os objetivos que você desejar e não afetam o comportamento do recurso.

Os pares de nome/valor de metadados são cabeçalhos HTTP válidos e devem cumprir todas as restrições que regem os cabeçalhos HTTP. Para obter mais informações sobre os requisitos de nomenclatura de metadados, consulte Nomes de metadados.

Recuperar propriedades do contêiner

Para recuperar as propriedades do contêiner, use o seguinte método:

ContainerClient.get_container_properties

O exemplo de código a seguir busca as propriedades do sistema de um contêiner e grava os valores de propriedade em uma janela de console:

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}")

Definir e recuperar metadados

Você pode especificar os metadados como um ou mais pares de nome-valor em um recurso de contêiner ou blob. Para definir metadados, use o seguinte método:

ContainerClient.set_container_metadata

Definir metadados de contêiner substitui todos os metadados existentes associados ao contêiner. Não é possível alterar um par de nome-valor individual.

O exemplo de código a seguir define os metadados em um contêiner:

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)

Para recuperar metadados, chame o seguinte método:

ContainerClient.get_container_properties

O exemplo a seguir lê em valores de metadados:

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)

Definir metadados de contêiner de maneira assíncrona

A biblioteca de clientes do Armazenamento de Blobs do Azure para Python é compatível com o gerenciamento de propriedades de contêiner e metadados de maneira assíncrona. Para saber mais sobre os requisitos de instalação do projeto, confira Programação assíncrona.

Siga estas etapas para definir os metadados de um contêiner usando APIs assíncronas:

Adicione as seguintes instruções de importação:

import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient

Adicione o código para executar o programa usando asyncio.run. Essa função executa a corrotina passada, main() no nosso exemplo, e gerencia o loop de eventos asyncio. As corrotinas são declaradas com a sintaxe async/await. Nesse exemplo, a corrotina main() primeiro cria o BlobServiceClient de nível superior usando async with e, em seguida, chama o método que define os metadados de contêiner. Observe que somente o cliente de nível superior precisa usar async with, pois os outros clientes criados a partir dele compartilham o mesmo pool de conexões.
```
async def main():
    sample = ContainerSamples()

    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    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())
```

Adicione código para definir os metadados de contêiner. O código é igual ao exemplo síncrono, exceto que o método é declarado com a palavra-chave async e a palavra-chave await é usada ao chamar os métodos get_container_properties e set_container_metadata.

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)

Com essa configuração básica em vigor, você pode implementar outros exemplos neste artigo como corrotinas usando sintaxe a async/await.

Recursos

Para saber mais sobre como definir e recuperar propriedades e metadados do contêiner usando a biblioteca de clientes do Armazenamento de Blobs do Azure para Python, confira os recursos a seguir.

Operações da API REST

O SDK do Azure para Python contém bibliotecas que se baseiam na API REST do Azure, permitindo a interação com as operações da API REST por meio de paradigmas conhecidos do Python. Os métodos da biblioteca de clientes para definir e recuperar propriedades e metadados usam as seguintes operações da API REST:

Obter propriedades de contêiner (API REST)
Definir metadados do contêiner (API REST)
Obter metadados do contêiner (API REST)

O método get_container_properties recupera propriedades e metadados do contêiner chamando a operação Obter Propriedades de Contêiner e a operação Obter Metadados de Contêiner.

Exemplos de código

Exibir exemplos de código síncrono ou assíncrono deste artigo (GitHub)

Share via