Enumeración de blobs con Python

Este artículo muestra cómo listar blobs utilizando la biblioteca cliente de Azure Storage para Python.

Para aprender sobre listado de blobs mediante APIs asíncronas, consulte Listar blobs asíncronos.

Requisitos previos

• Una suscripción a Azure: cree una cuenta gratuita
• Una cuenta de Azure Storage: cree una cuenta de almacenamiento
• Python 3.8 y versiones posteriores

Configurar el entorno

Si no tiene un proyecto existente, en esta sección se muestra cómo configurar uno para que funcione con la biblioteca cliente de Azure Blob Storage para Python. Para más información, vea Introducción a Azure Blob Storage y Python.

Para trabajar con los ejemplos de código de este artículo, siga los pasos siguientes a fin de configurar el proyecto.

Instalar paquetes

Instale los siguientes paquetes mediante pip install:

pip install azure-storage-blob azure-identity

Añadir sentencias de importación

Agregue las siguientes sentencias import:

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

Autorización

El mecanismo de autorización debe tener los permisos necesarios para enumerar un blob. Para autorizar con Microsoft Entra ID (recomendado), necesitas el rol integrado de Azure RBAC Storage Blob Data Reader o superior. Para obtener más información, consulte la guía de autorización para List Blobs (API REST).

Creación de un objeto de cliente

Para conectar una aplicación a Blob Storage, cree una instancia de BlobServiceClient. En el ejemplo siguiente se muestra cómo crear un objeto de cliente mediante DefaultAzureCredential para la autorización:

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

También puede crear objetos de cliente para contenedores o blobs específicos ya sea directamente o desde el objeto BlobServiceClient. Para obtener más información sobre cómo crear y administrar objetos de cliente, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Información sobre las opciones de enumeración de blobs

Cuando listas blobs de tu código, puedes especificar muchas opciones para gestionar cómo regresan los resultados desde Azure Storage. Puede especificar el número de resultados que se van a devolver en cada conjunto de resultados y luego recuperar los conjuntos subsiguientes. Puede especificar un prefijo para devolver los blobs cuyos nombres comienzan por ese carácter o cadena. Puedes listar los blobs en una estructura plana o jerárquica. Una lista jerárquica devuelve los blobs como si estuvieran organizados en carpetas.

Para listar los blobs en un contenedor usando un listado plano, llama a uno de estos métodos:

• ContainerClient.list_blobs (junto con el nombre, opcionalmente incluye metadatos, etiquetas y otra información asociada a cada blob)
• ContainerClient.list_blob_names (solo devuelve el nombre del blob).

Para listar los blobs en un contenedor usando un listado jerárquico, llama al siguiente método:

• ContainerClient.walk_blobs (junto con el nombre, opcionalmente incluye metadatos, etiquetas y otra información asociada a cada blob)

Filtrado de los resultados con un prefijo

Para filtrar la lista de blobs, especifique una cadena para el argumento de palabra clavename_starts_with. La cadena de prefijo puede incluir uno o varios caracteres. Azure Storage solo devuelve los blobs cuyos nombres comienzan con ese prefijo.

Lista plana frente a lista jerárquica

Los blobs de Azure Storage están organizados en un paradigma plano, en lugar de un paradigma jerárquico (como un sistema de archivos clásico). Sin embargo, puedes organizar los blobs en directorios virtuales para imitar una estructura de carpetas. Un directorio virtual forma parte del nombre del blob y se indica mediante el carácter delimitador.

Para organizar los blobs en directorios virtuales, use un carácter delimitador en el nombre del blob. El carácter delimitador predeterminado es una barra diagonal (/), pero puede especificar cualquier carácter como delimitador.

Si nombras tus blobs usando un delimitador, puedes elegir listar los blobs jerárquicamente. En el caso de una operación de enumeración jerárquica, Azure Storage devuelve los directorios virtuales y los blobs que hay debajo del objeto primario. Puede llamar a la operación de enumeración de forma recursiva para recorrer la jerarquía, de manera similar a como se haría con un sistema de archivos clásico mediante programación.

Uso de una lista plana

De forma predeterminada, una operación de enumeración devuelve los blobs en una lista plana. En una lista plana, los blobs no se organizan por directorio virtual.

El siguiente ejemplo lista los blobs en el contenedor especificado usando una lista 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}")

La salida es parecida a esta:

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

También puedes especificar opciones para filtrar los resultados de la lista o mostrar más información. En el ejemplo siguiente se listan blobs y etiquetas de blobs:

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

La salida es parecida a esta:

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'}

Uso de una lista jerárquica

Cuando se realiza una operación de enumeración de forma jerárquica, Azure Storage devuelve los directorios virtuales y los blobs en el primer nivel de la jerarquía.

Para enumerar los blobs jerárquicamente, use el método siguiente:

• ContainerClient.walk_blobs

En el ejemplo siguiente se enumeran los blobs del contenedor especificado mediante una lista jerá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}")

La salida es parecida a esta:

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

Enumerar blobs de forma asincrónica

La biblioteca cliente de Azure Blob Storage para Python admite la enumeración de blobs de forma asincrónica. Para obtener más información sobre los requisitos de configuración del proyecto, consulte Programación asincrónica.

Sigue estos pasos para listar los blobs usando APIs asincrónicas:

1. Agregue las siguientes sentencias de importación:

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

2. Añadir código para ejecutar el programa usando asyncio.run. Esta función ejecuta la corutina pasada, main() en este ejemplo, y gestiona el asyncio bucle de eventos. Las corutinas se declaran usando la sintaxis async/await. En este ejemplo, la corrutina main() primero crea el objeto BlobServiceClient de nivel superior mediante async with y, a continuación, llama al método que enumera los blobs. Solo el cliente de nivel superior debe usar async with, ya que otros clientes creados a partir de él comparten el mismo grupo de conexiones.

   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. Agregue código para enumerar los blobs. El siguiente ejemplo de código lista los blobs usando una lista plana. El código es el mismo que el ejemplo síncrono, salvo que el método se declara usando la async palabra clave y async for se usa al llamar al método list_blobs .

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

Con esta configuración básica implementada, puedes implementar otros ejemplos en este artículo como corutinas usando la sintaxis async/await.

Lista de blobs en formato Apache Arrow (vista previa)

Esta capacidad se basa en la API existente List Blobs . En lugar de usar el XML por defecto, utiliza el formato compacto y columnar Apache Arrow como formato de respuesta en el cable. Lo activas configurando una única opción en la llamada para listar contenedores. El SDK de Python decodifica Apache Arrow entre bastidores y sigue devolviendo los mismos objetos BlobProperties. Este enfoque mejora el rendimiento de listados y reduce la CPU del lado del cliente al enumerar contenedores grandes. Preserva el contrato de respuesta en el que dependen las solicitudes.

Para solicitar resultados en formato Apache Arrow, establece el argumento de palabra clave response_format en "arrow" al llamar a ContainerClient.list_blobs o ContainerClient.list_blob_names. Al usar la salida de Apache Arrow, también puedes configurar los start_from argumentos clave y end_before para controlar el rango de rutas devueltas.

El siguiente ejemplo lista los blobs en un contenedor y solicita los resultados en 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 más sobre cómo listar blobs utilizando la biblioteca cliente de Azure Blob Storage para Python, consulta los siguientes recursos.

Ejemplos de código

• Consulta ejemplos de código síncrono o asincrónico de este artículo (GitHub).

Operaciones de API REST

El SDK de Azure para Python contiene bibliotecas que se construyen sobre la API REST de Azure. Al usar estas librerías, puedes interactuar con operaciones de la API REST mediante paradigmas familiares de Python. Los métodos de la biblioteca cliente para enumerar blobs usan la siguiente operación de API REST:

• Enumeración de blobs (API de REST)

Recursos de la biblioteca cliente

• Documentación de referencia de la biblioteca cliente
• Código fuente de la biblioteca del cliente
• Paquete (PyPi)

Consulte también

• Enumeración de recursos de blob
• Control de versiones de blobs

Contenido relacionado

• Este artículo forma parte de la guía para desarrolladores de Blob Storage para Python. Para más información, consulte la lista completa de artículos de la guía para desarrolladores en Compilación de la aplicación de Python.