Saltar a contenido

Azure Blob Storage

Una cuenta de Azure Storage o, lo habitual, un container como raíz, sobre el SDK oficial.

pip install "tai-storage[azure]"              # con connection string o con clave
pip install "tai-storage[azure-identity]"     # con una identidad de Azure AD, sin clave
from tai_storage import StorageFactory

origin = StorageFactory.create_azure(container="backups")                          # connection string del entorno
origin = StorageFactory.create_azure(container="backups", create_container=True)   # lo crea si no existe
origin = StorageFactory.create_azure()                                             # la cuenta entera

Credenciales

Por orden de preferencia:

Cómo Argumentos Variables
Connection string connection_string AZURE_STORAGE_CONNECTION_STRING
Cuenta y clave account_name, account_key AZURE_STORAGE_ACCOUNT_NAME, AZURE_STORAGE_ACCOUNT_KEY
Identidad de Azure AD account_url, opcional credential —

container también puede venir de AZURE_STORAGE_CONTAINER.

Sin clave, con la identidad de la aplicación

En una Web App o una Function de Azure con identidad administrada, o en local con az login:

origin = StorageFactory.create_azure(
    account_url="https://micuenta.blob.core.windows.net",
    container="backups",
)

Sin credential, se usa DefaultAzureCredential de azure-identity, que prueba la identidad administrada, las variables de entorno y la sesión de az login. La identidad necesita el rol Storage Blob Data Contributor sobre la cuenta o el container.

El container como raíz

  • Con container=, ese container es la raíz del origen, como la biblioteca en SharePoint: origin.get_file("2026/10/db.dump") es el blob 2026/10/db.dump de ese container. Es lo que necesita un backup_storage de tai-sql.
  • Sin container=, el primer segmento de cada ruta es el container: origin.get_file("backups/2026/db.dump"). La raíz solo lista containers, y escribir en ella es un InvalidPathError.

No hay carpetas vacías

En Azure las «carpetas» son prefijos de los nombres de los blobs. Una carpeta existe mientras tenga algún fichero:

origin.capabilities.empty_folders        # False
origin.get_folder("nueva").create()      # no deja nada: no hay nada que crear
origin.get_file("nueva/a.txt").write(b"1")
origin.get_folder("nueva").exists()      # True, a partir de ahora

Es la única diferencia de semántica con el resto de orígenes.

Lo que hace por ti

  • overwrite=False es atómico: lo comprueba el propio servicio (If-None-Match: *). Dos procesos no pueden crear el mismo blob a la vez.
  • Ficheros grandes por bloques, con trozos acotados: con los valores por defecto del SDK, subir 1 GB hacía crecer la memoria unos 90 MB. Con los de tai-storage, unos 20 MB.
  • copy_to() dentro de la misma cuenta usa la copia del servicio y espera a que acabe. move_to() copia, comprueba el tamaño y solo entonces borra el original. En la 0.1 borraba sin esperar a que terminara la copia.
  • Los errores del SDK se traducen a los de tai-storage: una clave mal puesta es AuthenticationError, no «no existe».

Cuánto cuesta cada operación

Operación Peticiones
metadatos, exists() 1 (0 si el fichero viene de un listado)
list_files() / list_folders() 1 por cada 5.000 blobs (solo ese nivel)
list_files(recursive=True) 1 por cada 5.000 blobs por debajo
open_read() 1 por cada trozo de 4 MiB
escribir 1 hasta 64 MiB; por encima, 1 por bloque de 4 MiB + 1 para confirmarlos
copy_to() en la misma cuenta 1 + 1 cada medio segundo hasta que acaba
folder.delete(recursive=True) 1 para listar + 1 por blob

Probar contra Azurite

Azurite es el emulador oficial de Azure Storage. Con él se prueba sin cuenta:

docker run -d -p 10000:10000 mcr.microsoft.com/azure-storage/azurite \
  azurite-blob --blobHost 0.0.0.0 --skipApiVersionCheck --loose
AZURITE = (
    "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;"
    "AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;"
    "BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
)
origin = StorageFactory.create_azure(connection_string=AZURITE, container="pruebas", create_container=True)

La clave es la pública de Azurite, documentada por Microsoft: no sirve fuera del emulador.