Listar blobs com Python

Este artigo mostra como listar blobs usando a biblioteca cliente Armazenamento do Azure para Python.

Para saber mais sobre como listar blobs ao utilizar APIs assíncronas, veja Listar blobs de forma assíncrona.

Pré-requisitos

• Subscrição do Azure - crie uma gratuitamente
• Conta de armazenamento do Azure - criar uma conta de armazenamento
• Python 3,8+

Configurar o ambiente

Se você não tiver um projeto existente, esta seção mostra como configurar um projeto para trabalhar com a biblioteca de cliente do Armazenamento de Blobs do Azure para Python. Para obter mais detalhes, consulte Introdução ao Armazenamento de Blobs do Azure e Python.

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

Instalar pacotes

Instale os seguintes pacotes usando pip install:

pip install azure-storage-blob azure-identity

Adicionar instruções de importação

Adicione as seguintes instruções import:

from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobPrefix

Autorização

O mecanismo de autorização deve ter as permissões necessárias para listar um blob. Para a autorização com o Microsoft Entra ID (recomendada), precisa da função incorporada do Azure RBAC Storage Blob Data Reader ou superior. Para saber mais, consulte as diretrizes de autorização para Listar Blobs (API REST).

Criar um objeto cliente

Para conectar um aplicativo ao Armazenamento de Blob, crie uma instância de 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 de cliente para contêineres ou blobs específicos, diretamente ou a partir do BlobServiceClient objeto. Para saber mais sobre como criar e gerenciar objetos de cliente, consulte Criar e gerenciar objetos de cliente que interagem com recursos de dados.

Sobre as opções de listagem de blobs

Quando lista blobs do seu código, pode especificar várias opções para gerir como os resultados retornam do Armazenamento do Azure. Você pode especificar o número de resultados a serem retornados em cada conjunto de resultados e, em seguida, recuperar os conjuntos subsequentes. Você pode especificar um prefixo para retornar blobs cujos nomes comecem com esse caractere ou cadeia de caracteres. Podes listar blobs numa estrutura de listagem plana, ou hierarquicamente. Uma listagem hierárquica retorna blobs como se estivessem organizados em pastas.

Para listar os blobs num contentor usando uma listagem plana, chame a um destes métodos:

• ContainerClient.list_blobs (juntamente com o nome, opcionalmente inclui metadados, etiquetas e outras informações associadas a cada blob)
• ContainerClient.list_blob_names (retorna apenas o nome do blob)

Para listar os blobs num contentor usando uma listagem hierárquica, chame o seguinte método:

• ContainerClient.walk_blobs (juntamente com o nome, inclui opcionalmente metadados, etiquetas e outras informações associadas a cada blob)

Filtrar resultados com um prefixo

Para filtrar a lista de blobs, especifique uma string para o argumento de palavra-chave name_starts_with. A cadeia de caracteres de prefixo pode incluir um ou mais caracteres. O Armazenamento do Azure devolve apenas os blobs cujos nomes começam com esse prefixo.

Listagem simples versus listagem hierárquica

Os blobs no Armazenamento do Azure são organizados em um paradigma simples, em vez de um paradigma hierárquico (como um sistema de arquivos clássico). No entanto, podes organizar blobs em diretórios virtuais para imitar uma estrutura de pastas. Um diretório virtual faz parte do nome do blob e é indicado pelo caractere delimitador.

Para organizar blobs em diretórios virtuais, use um caractere delimitador no nome do blob. O caractere delimitador padrão é uma barra (/), mas você pode especificar qualquer caractere como o delimitador.

Se nomeares os teus blobs usando um delimitador, podes escolher listar os blobs hierarquicamente. Para uma operação de listagem hierárquica, o Armazenamento do Azure retorna todos os diretórios virtuais e blobs abaixo do objeto pai. Você pode chamar a operação de listagem recursivamente para percorrer a hierarquia, semelhante a como você atravessaria um sistema de arquivos clássico programaticamente.

Usar uma listagem simples

Por padrão, uma operação de listagem retorna blobs em uma listagem simples. Em uma listagem simples, os blobs não são organizados por diretório virtual.

O exemplo seguinte lista os blobs no contentor especificado usando uma listagem plana:

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

    blob_list = container_client.list_blobs()

    for blob in blob_list:
        print(f"Name: {blob.name}")

A saída da amostra é semelhante a:

List blobs flat:
Name: file4.txt
Name: folderA/file1.txt
Name: folderA/file2.txt
Name: folderA/folderB/file3.txt

Também pode especificar opções para filtrar resultados da lista ou mostrar mais informações. O exemplo seguinte lista blobs e respetivas tags:

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

    blob_list = container_client.list_blobs(include=['tags'])

    for blob in blob_list:
        print(f"Name: {blob['name']}, Tags: {blob['tags']}")

A saída da amostra é semelhante a:

List blobs flat:
Name: file4.txt, Tags: None
Name: folderA/file1.txt, Tags: None
Name: folderA/file2.txt, Tags: None
Name: folderA/folderB/file3.txt, Tags: {'tag1': 'value1', 'tag2': 'value2'}

Usar uma listagem hierárquica

Quando você chama uma operação de listagem hierarquicamente, o Armazenamento do Azure retorna os diretórios virtuais e blobs no primeiro nível da hierarquia.

Para listar blobs hierarquicamente, use o seguinte método:

• ContainerClient.walk_blobs

O exemplo a seguir lista os blobs no contêiner especificado usando uma listagem hierárquica:

depth = 0
indent = "  "
def list_blobs_hierarchical(self, container_client: ContainerClient, prefix):
    for blob in container_client.walk_blobs(name_starts_with=prefix, delimiter='/'):
        if isinstance(blob, BlobPrefix):
            # Indentation is only added to show nesting in the output
            print(f"{self.indent * self.depth}{blob.name}")
            self.depth += 1
            self.list_blobs_hierarchical(container_client, prefix=blob.name)
            self.depth -= 1
        else:
            print(f"{self.indent * self.depth}{blob.name}")

A saída da amostra é semelhante a:

folderA/
  folderA/folderB/
    folderA/folderB/file3.txt
  folderA/file1.txt
  folderA/file2.txt
file4.txt

Listar blobs de forma assíncrona

A biblioteca de cliente do Armazenamento de Blobs do Azure para Python dá suporte à listagem de blobs de forma assíncrona. Para saber mais sobre os requisitos de configuração do projeto, consulte Programação assíncrona.

Siga estes passos para listar blobs 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, ContainerClient, BlobPrefix
   

2. Adicione código para executar o programa usando asyncio.run. Esta função executa a corrotina passada, main() neste exemplo, e gere o ciclo de eventos asyncio. As corrotinas são declaradas usando a sintaxe async/await. Neste exemplo, a corrotina main() começa por criar o nível superior BlobServiceClient utilizando async with e, em seguida, chama o método que lista os blobs. Somente o cliente de nível superior precisa usar async with, pois outros clientes criados a partir dele partilham 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.list_blobs_flat(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

3. Adicione código para listar os blobs. O exemplo de código seguinte lista blobs usando uma listagem plana. O código é o mesmo do exemplo síncrono, exceto que o método é declarado usando a async palavra-chave e async for é usado ao chamar o list_blobs método.

   async def list_blobs_flat(self, blob_service_client: BlobServiceClient, container_name):
       container_client = blob_service_client.get_container_client(container=container_name)
   
       async for blob in container_client.list_blobs():
           print(f"Name: {blob.name}")
   

Com esta configuração básica pronta, pode implementar outros exemplos deste artigo sob a forma de corrotinas, utilizando a sintaxe async/await.

Listar blobs no formato Apache Arrow (pré-visualização)

Esta funcionalidade baseia-se na API existente List Blobs . Em vez de usar o XML predefinido, utiliza o formato Apache Arrow, compacto e colunar, como formato de resposta na transmissão. Ativa-o definindo uma única opção na chamada de listagem de contentores. O SDK Python decodifica o Apache Arrow nos bastidores e ainda assim devolve os mesmos BlobProperties objetos. Esta abordagem melhora o desempenho da listagem e reduz a utilização da CPU no cliente durante a enumeração de contentores de grande dimensão. Preserva o contrato de resposta em que as candidaturas dependem.

Para solicitar resultados no formato Apache Arrow, defina o response_format argumento da palavra-chave para "arrow" quando chamar ContainerClient.list_blobs ou ContainerClient.list_blob_names. Ao utilizar a saída do Apache Arrow, também pode definir os argumentos nomeados start_from e end_before para controlar o intervalo de caminhos devolvido.

O exemplo seguinte lista os blobs num contentor e solicita os resultados no formato Apache Arrow:

# response_format="arrow" requires the nanoarrow package to be installed
blob_list = container_client.list_blobs(
    name_starts_with="folderA/",
    response_format="arrow",
)

for blob in blob_list:
    print("Name: " + blob.name)

Recursos

Para saber mais sobre como listar blobs usando a biblioteca cliente Armazenamento de Blobs do Azure para Python, consulte os seguintes recursos.

Amostras de código

• Veja exemplos de código síncrono ou assíncrono deste artigo (GitHub).

Operações da API REST

O SDK do Azure para Python contém bibliotecas que se baseiam na API REST do Azure. Ao utilizar estas bibliotecas, pode interagir com operações da API REST através de paradigmas Python familiares. Os métodos de biblioteca de cliente para listar blobs usam a seguinte operação de API REST:

• Listar Blobs (API REST)

Recursos da biblioteca do cliente

• Documentação de referência da biblioteca cliente
• Código fonte da biblioteca cliente
• Pacote (PyPi)

Consulte também

• Enumerando recursos de Blob
• Versionamento de Blob

Conteúdos relacionados

• Este artigo faz parte do guia do desenvolvedor do Armazenamento de Blobs para Python. Para saber mais, consulte a lista completa de artigos do guia do desenvolvedor em Build your Python app.