Compartilhar via

Gerenciar propriedades e metadados de blob com Python

  • Artigo

Além dos dados que eles contêm, os blobs suportam as propriedades do sistema e os metadados definidos pelo usuário. 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 blob de maneira assíncrona.

Pré-requisitos

Configure seu ambiente

Se você não tiver um projeto existente, esta seção mostrará como configurar um projeto para funcionar com a biblioteca de clientes do Armazenamento de Blobs do Azure para Python. Para obter mais detalhes, confira Introdução ao Armazenamento de Blobs do Azure e ao Python.

Para trabalhar com os exemplos de código neste artigo, siga estas etapas para configurar seu projeto.

Instalar Pacotes

Instale os seguintes pacotes por meio de pip install:

pip install azure-storage-blob azure-identity

Adicionar instruções de importação

Adicione as seguintes declarações de import :

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContentSettings

Autorização

O mecanismo de autorização precisa ter as permissões necessárias para trabalhar com metadados ou propriedades de contêiner. Para autorização com o Microsoft Entra ID (recomendado), você precisa da função interna do RBAC do Azure Leitor de Dados de Blob de Armazenamento ou superior para operações get e Colaborador de Dados de Blob de Armazenamento ou superior para as operações set. Para saber mais, confira as diretrizes de autorização para Definir Propriedades de Blob (API REST), Obter Propriedades de Blob (API REST), Definir Metadados de Blob (API REST) ou Obter Metadados de Blob (API REST).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blobs, crie uma instância do BlobServiceClient. O exemplo a seguir mostra como criar um objeto cliente usando DefaultAzureCredential para autorização:

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

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

Você também pode criar objetos cliente para contêineres ou blobs específicos, diretamente ou do objeto BlobServiceClient. Para saber mais sobre como criar e gerenciar objetos clientes, confira Criar e gerenciar objetos clientes que interagem com recursos de dados.

Propriedades e metadados

  • Propriedades do sistema: existem propriedades do sistema em cada recurso de armazenamento de Blob. Algumas podem ser lidas ou definidas, enquanto outras são de somente leitura. Internamente, 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.

Observação

As marcas de índice de blob também fornecem a capacidade de armazenar atributos de chave/valor arbitrários definidos pelo usuário junto com o recurso de armazenamento de Blobs do Azure. Embora seja semelhante aos metadados, somente as marcas de índice de blob são indexadas automaticamente e tornam-se pesquisáveis pelo serviço de blob nativo. Os metadados não podem ser indexados e consultados a menos que você utilize um serviço separado, como o Azure Search.

Para saber mais sobre esse recurso, confira Gerenciar e localizar dados no Armazenamento de Blobs do Azure usando o índice de blobs (versão prévia).

Definir e recuperar propriedades

Para definir propriedades em um blob, use o seguinte método:

Todas as propriedades não explicitamente definidas são limpas. Para preservar as propriedades existentes, primeiro você pode recuperar as propriedades do blob e usá-las para preencher os cabeçalhos que não estão sendo atualizados.

O exemplo de código a seguir define as propriedades do sistema content_type e content_language em um blob, preservando as propriedades existentes:

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)

Para recuperar propriedades em um blob, use o seguinte método:

O exemplo de código a seguir obtém as propriedades de sistema de um blob e exibe alguns dos valores:

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

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, envie um dicionário contendo pares nome-valor usando o seguinte método:

O exemplo de código a seguir define os metadados em um 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)

Para recuperar os metadados, chame o método get_blob_properties no blob para preencher a coleção metadados, em seguida, leia os valores, conforme mostrado no exemplo abaixo. O método get_blob_properties recupera propriedades e metadados de blob chamando a operação Obter Propriedades do Blob e a operação Obter Metadados de Blob.

O exemplo de código a seguir lê metadados em um blob e imprime cada par chave/valor:

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)

Definir metadados de blob de maneira assíncrona

A biblioteca de clientes do Armazenamento de Blobs do Azure para Python é compatível com o gerenciamento de propriedades de blob 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 blob usando APIs assíncronas:

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

    import asyncio

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

  2. 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 blob. 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 = BlobSamples()

    # 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())

  3. Adicione código para definir os metadados de blob. 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_blob_properties e set_blob_metadata.

    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)

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 gerenciar propriedades do sistema e metadados definidos pelo usuário usando a biblioteca de clientes do Armazenamento de Blobs do Azure para Python, confira os recursos a seguir.

Exemplos de código

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 gerenciar propriedades do sistema e metadados definidos pelo usuário usam as seguintes operações de API REST:

Recursos da biblioteca de clientes

Conteúdo relacionado

  • Este artigo faz parte do guia para desenvolvedores do Armazenamento de Blobs para Python. Para saber mais, veja a lista completa de artigos do guia do desenvolvedor em Criar seu aplicativo Python.