Inicio rápido: Biblioteca cliente de Azure Blob Storage para Python

  • Artículo

Nota:

La opción Compilar desde cero le guía paso a paso por el proceso de crear un nuevo proyecto, instalar los paquetes, escribir el código y ejecutar una aplicación de consola básica. Este enfoque se recomienda si quiere comprender todos los detalles implicados en la creación de una aplicación que se conecta a Azure Blob Storage. Si prefiere automatizar las tareas de implementación y empezar con un proyecto completado, elija Iniciar con una plantilla.

Nota:

La opción Iniciar con una plantilla usa Azure Developer CLI para automatizar las tareas de implementación y comienza con un proyecto completado. Este enfoque se recomienda si quiere explorar el código lo más rápido posible sin pasar por las tareas de configuración. Si prefiere instrucciones paso a paso para compilar la aplicación, elija Compilar desde cero.

Introducción a la biblioteca cliente de Azure Blob Storage para que Python gestione blobs y contenedores.

En este artículo, siga los pasos para instalar el paquete y probar el código de ejemplo para tareas básicas.

En este artículo, se usa Azure Developer CLI para implementar recursos de Azure y ejecutar una aplicación de consola completa con solo unos cuantos comandos.

Documentación de referencia sobre la API | Código fuente de la biblioteca | Paquete (PyPI) | Ejemplos

En este vídeo se muestra cómo empezar a usar la biblioteca cliente de Azure Blob Storage para Python.

Los pasos del vídeo también se describen en las secciones siguientes.

Requisitos previos

Instalación

En esta sección se explica cómo preparar un proyecto para que funcione con la biblioteca cliente de Azure Blob Storage para Python.

Creación del proyecto

Cree una aplicación de Python llamada blob-quickstart.

  1. En una ventana de la consola (como PowerShell o Bash), cree un directorio para el proyecto:

    mkdir blob-quickstart

  2. Cambie al directorio blob-quickstart recién creado:

    cd blob-quickstart

Instalación de los paquetes

En el directorio del proyecto, instale los paquetes para las bibliotecas cliente de Azure Blob Storage y Azure Identity mediante el comando pip install. El paquete azure-identity es necesario para las conexiones sin contraseña a los servicios de Azure.

pip install azure-storage-blob azure-identity

Instalación del marco de la aplicación

En el directorio del proyecto, siga los pasos para crear la estructura básica de la aplicación:

  1. Abra un nuevo archivo de texto en el editor de código.
  2. Agregue las instrucciones import, cree la estructura del programa e incluya el control de excepciones básico, como se muestra a continuación.
  3. Guarde el nuevo archivo como blob-quickstart.py en el directorio blob-quickstart.
import os, uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, BlobClient, ContainerClient

try:
    print("Azure Blob Storage Python quickstart sample")

    # Quickstart code goes here

except Exception as ex:
    print('Exception:')
    print(ex)

Con Azure Developer CLI instalado, puede crear una cuenta de almacenamiento y ejecutar el código de ejemplo con solo unos cuantos comandos. Puede ejecutar el proyecto en el entorno de desarrollo local o en DevContainer.

Inicialización de la plantilla de Azure Developer CLI e implementación de recursos

En un directorio vacío, siga estos pasos para inicializar la plantilla azd, aprovisionar recursos de Azure y empezar a trabajar con el código:

  • Clone los recursos del repositorio de inicio rápido de GitHub e inicialice la plantilla localmente:

    azd init --template blob-storage-quickstart-python

    Se le pedirá la siguiente información:

    • Nombre del entorno: este valor se usa como prefijo para todos los recursos de Azure creados por Azure Developer CLI. El nombre debe ser único en todas las suscripciones de Azure y tener entre 3 y 24 caracteres. El nombre solo puede contener números y letras minúsculas.

  • Inicie sesión en Azure:

    azd auth login

  • Aprovisione e implemente los recursos en Azure:

    azd up

    Se le pedirá la siguiente información:

    • Suscripción: la suscripción de Azure en la que se implementan los recursos.
    • Ubicación: la región de Azure donde se implementan los recursos.

    La implementación puede tardar unos minutos en finalizar. La salida del comando azd upincluye el nombre de la cuenta de almacenamiento recién creada, que necesitará más adelante para ejecutar el código.

Ejecución del código de ejemplo

En este momento, los recursos están implementados en Azure y el código está casi listo para ejecutarse. Siga estos pasos para instalar los paquetes, actualizar el nombre de la cuenta de almacenamiento en el código y ejecutar la aplicación de consola de ejemplo:

  • Instalación de paquetes: en el directorio local, instale paquetes para las bibliotecas cliente de Azure Blob Storage y de Azure Identity mediante el siguiente comando: pip install azure-storage-blob azure-identity
  • Actualización del nombre de la cuenta de almacenamiento: en el directorio local, edite el archivo denominado blob_quickstart.py. Busque el marcador de posición <storage-account-name> y reemplácelo por el nombre real de la cuenta de almacenamiento creada por el comando azd up. Guarde los cambios.
  • Ejecución del proyecto: ejecute el siguiente comando para ejecutar la aplicación: python blob_quickstart.py.
  • Observar la salida: esta aplicación crea un archivo de prueba en la carpeta de datos local y lo carga en un contenedor de la cuenta de almacenamiento. Después, en el ejemplo se enumeran los blobs del contenedor y se descarga el archivo con un nombre nuevo para que pueda comparar los archivos antiguo y nuevo.

Para más información sobre cómo funciona el código de ejemplo, consulte Ejemplos de código.

Cuando haya terminado de probar el código, consulte la sección Limpieza de recursos para eliminar los recursos creados por el comando azd up.

Modelo de objetos

Azure Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados. Los datos no estructurados son datos que no se ciñen a ningún un modelo de datos o definición concretos, como texto o datos binarios. Blob Storage ofrece tres tipos de recursos:

  • La cuenta de almacenamiento
  • Un contenedor en la cuenta de almacenamiento
  • Un blob en el contenedor

En el siguiente diagrama se muestra la relación entre estos recursos:

Diagram of Blob storage architecture

Use las siguientes clases de Python para interactuar con estos recursos:

  • BlobServiceClient: La clase BlobServiceClient permite manipular recursos de Azure Storage y contenedores de blobs.
  • ContainerClient: La clase ContainerClient permite manipular contenedores de Azure Storage y sus blobs.
  • BlobClient: La clase BlobClient permite manipular los blobs de Azure Storage.

Ejemplos de código

Estos fragmentos de código de ejemplo muestran cómo realizar las siguientes tareas con la biblioteca cliente de Azure Blob Storage para Python:

Nota:

La plantilla de Azure Developer CLI incluye un archivo con código de ejemplo ya implementado. En los ejemplos siguientes se proporcionan detalles para cada parte del código de ejemplo. La plantilla implementa el método de autenticación sin contraseña recomendado, como se describe en la sección Autenticación en Azure. El método de cadena de conexión se muestra como una alternativa, pero no se usa en la plantilla y no se recomienda para el código de producción.

Autenticación en Azure y autorización del acceso a datos de blobs

Las solicitudes de aplicación a Azure Blob Storage deben estar autorizadas. El uso de la clase DefaultAzureCredential que proporciona la biblioteca cliente de Azure.Identity es el enfoque recomendado para implementar conexiones sin contraseña a los servicios de Azure en el código, incluido Blob Storage.

También puede autorizar las solicitudes a Azure Blob Storage mediante la clave de acceso de la cuenta. Sin embargo, este enfoque debe usarse con precaución. Los desarrolladores deben ser diligentes para no exponer nunca las claves de acceso en una ubicación que no sea segura. Cualquier persona que tenga la clave de acceso puede autorizar las solicitudes en la cuenta de almacenamiento y tiene acceso eficaz a todos los datos. DefaultAzureCredential ofrece ventajas de seguridad y administración mejoradas con respecto la clave de cuenta para permitir la autenticación sin contraseña. Ambas opciones se muestran en el ejemplo siguiente.

DefaultAzureCredential admite varios métodos de autenticación y determina el que se debe usar en tiempo de ejecución. Este enfoque permite que la aplicación use diferentes métodos de autenticación en distintos entornos (local frente a producción) sin implementar código específico del entorno.

El orden y las ubicaciones en las que DefaultAzureCredential busca credenciales se pueden encontrar en la información general de la biblioteca de Azure Identity.

Por ejemplo, la aplicación puede autenticarse con las credenciales de inicio de sesión de la CLI de Azure cuando se desarrolla en el entorno local. A continuación, la aplicación puede usar una identidad administrada una vez se haya implementado en Azure. No se necesitan cambios de código para esta transición.

Asignación de roles a la cuenta de usuario de Microsoft Entra

Al desarrollar localmente, asegúrese de que la cuenta de usuario que accede a los datos de blob tenga los permisos correctos. Necesitará el Colaborador de datos de blobs de almacenamiento para leer y escribir datos de blob. Para asignarse este rol a sí mismo, necesitará que se le asigne el rol Administrador de acceso de usuario u otro rol que incluya la acción Microsoft.Authorization/roleAssignments/write. Puede asignar roles RBAC de Azure a un usuario mediante Azure Portal, la CLI de Azure o Azure PowerShell. Puede obtener más información sobre los ámbitos disponibles para las asignaciones de roles en la página de información general del ámbito.

En este escenario, asignará permisos a la cuenta de usuario, cuyo ámbito es la cuenta de almacenamiento, a fin de seguir el principio de privilegios mínimos. Esta práctica solo proporciona a los usuarios los permisos mínimos necesarios y crea entornos de producción más seguros.

En el ejemplo siguiente se asignará el rol Colaborador de datos de blobs de almacenamiento a la cuenta de usuario, que proporciona acceso de lectura y escritura a los datos de blobs de la cuenta de almacenamiento.

Importante

En la mayoría de los casos, la asignación de roles tardará un minuto o dos en propagarse en Azure, pero en casos excepcionales puede tardar hasta ocho minutos. Si recibe errores de autenticación al ejecutar por primera vez el código, espere unos instantes e inténtelo de nuevo.

  1. En Azure Portal, busque la cuenta de almacenamiento mediante la barra de búsqueda principal o el panel de navegación de la izquierda.

  2. En la página de información general de la cuenta de almacenamiento, seleccione Control de acceso (IAM) en el menú de la izquierda.

  3. En la página Control de acceso (IAM), seleccione la pestaña Asignación de roles.

  4. Seleccione + Agregar en el menú superior y, a continuación, Agregar asignación de roles en el menú desplegable resultante.

    A screenshot showing how to assign a role.

  5. Puede usar el cuadro de búsqueda para filtrar los resultados por el rol deseado. En este ejemplo, busque Colaborador de datos de blobs de almacenamiento y seleccione el resultado coincidente y, a continuación, elija Siguiente.

  6. En la pestaña Asignar acceso a, seleccione Usuario, grupo o entidad de servicio y, a continuación, elija + Seleccionar miembros.

  7. En el cuadro de diálogo, busque el nombre de usuario de Microsoft Entra (normalmente su dirección de correo electrónico de user@domain) y, a continuación, elija Seleccionar en la parte inferior del cuadro de diálogo.

  8. Seleccione Revisar y asignar para ir a la página final y, a continuación, de nuevo Revisar y asignar para completar el proceso.

Inicio de sesión y conexión del código de la aplicación a Azure mediante DefaultAzureCredential

Puede autorizar el acceso a los datos de la cuenta de almacenamiento mediante los siguientes pasos:

  1. Asegúrese de que esté autenticado con la misma cuenta de Microsoft Entra a la que asignó el rol en la cuenta almacenamiento. Puede autenticarse a través de la CLI de Azure, Visual Studio Code o Azure PowerShell.

    Inicie sesión en Azure a través de la CLI de Azure mediante el siguiente comando:

    az login

  2. Para usar DefaultAzureCredential, asegúrese de que el paquete azure-identity está instalado y de que la clase se importa:

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

  3. Agregue este código dentro del bloque try. Cuando el código se ejecute en la estación de trabajo local, DefaultAzureCredential usará las credenciales de desarrollador de la herramienta con prioridad en la que haya iniciado sesión para autenticarse en Azure. Algunos ejemplos de estas herramientas son la CLI de Azure o Visual Studio Code.

    account_url = "https://<storageaccountname>.blob.core.windows.net"
default_credential = DefaultAzureCredential()

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

  4. Asegúrese de actualizar el nombre de la cuenta de almacenamiento en el URI del objeto BlobServiceClient. El nombre de la cuenta de almacenamiento se puede encontrar en la página de información general de Azure Portal.

    A screenshot showing how to find the storage account name.

    Nota:

    Cuando se implementa en Azure, se puede usar este mismo código para autorizar solicitudes a Azure Storage desde una aplicación que se ejecute en Azure. Sin embargo, deberá habilitar la identidad administrada en la aplicación en Azure. A continuación, configure la cuenta almacenamiento para permitir que esa identidad administrada se conecte. Para obtener instrucciones detalladas sobre la configuración de esta conexión entre los servicios de Azure, consulte el tutorial Autenticación desde aplicaciones hospedadas en Azure.

Crear un contenedor

Cree un nuevo contenedor en su cuenta de almacenamiento llamando al método create_container en el objeto blob_service_client. En este ejemplo, el código añade un valor GUID al nombre del contenedor para asegurarse de que es único.

Agregue este código al final del bloque try:

# Create a unique name for the container
container_name = str(uuid.uuid4())

# Create the container
container_client = blob_service_client.create_container(container_name)

Para más información sobre cómo crear un contenedor y explorar más ejemplos de código, consulte Creación de un contenedor de blobs con Python.

Importante

Los nombres de contenedor deben estar en minúsculas. Para más información acerca de los contenedores de nomenclatura y los blobs, consulte Naming and Referencing Containers, Blobs, and Metadata (Asignación de nombres y realización de referencias a contenedores, blobs y metadatos).

Carga de los blobs en un contenedor

Cargue un blob en un contenedor mediante upload_blob. El código del ejemplo crea un archivo de texto en el directorio local de datos para cargarlo en el contenedor.

Agregue este código al final del bloque try:

# Create a local directory to hold blob data
local_path = "./data"
os.mkdir(local_path)

# Create a file in the local data directory to upload and download
local_file_name = str(uuid.uuid4()) + ".txt"
upload_file_path = os.path.join(local_path, local_file_name)

# Write text to the file
file = open(file=upload_file_path, mode='w')
file.write("Hello, World!")
file.close()

# Create a blob client using the local file name as the name for the blob
blob_client = blob_service_client.get_blob_client(container=container_name, blob=local_file_name)

print("\nUploading to Azure Storage as blob:\n\t" + local_file_name)

# Upload the created file
with open(file=upload_file_path, mode="rb") as data:
    blob_client.upload_blob(data)

Para más información sobre cómo cargar blobs y explorar más ejemplos de código, consulte Carga de un blob con Python.

Enumerar los blobs de un contenedor

Enumere los blobs en el contenedor llamando al método list_blobs. En este caso, solo se ha agregado un blob al contenedor, por lo que la operación de enumeración devuelve simplemente dicho blob.

Agregue este código al final del bloque try:

print("\nListing blobs...")

# List the blobs in the container
blob_list = container_client.list_blobs()
for blob in blob_list:
    print("\t" + blob.name)

Para más información sobre cómo enumerar blobs y explorar más ejemplos de código, consulte Enumeración de blobs con Python.

Descargar blobs

Descargue el blob creado previamente llamando al método download_blob. El código de ejemplo agrega el sufijo "DOWNLOAD" al nombre de archivo para que pueda ver ambos archivos en el sistema de archivos local.

Agregue este código al final del bloque try:

# Download the blob to a local file
# Add 'DOWNLOAD' before the .txt extension so you can see both files in the data directory
download_file_path = os.path.join(local_path, str.replace(local_file_name ,'.txt', 'DOWNLOAD.txt'))
container_client = blob_service_client.get_container_client(container= container_name) 
print("\nDownloading blob to \n\t" + download_file_path)

with open(file=download_file_path, mode="wb") as download_file:
 download_file.write(container_client.download_blob(blob.name).readall())

Para más información sobre cómo descargar blobs y explorar más ejemplos de código, consulte Descarga de un blob con Python.

Eliminación de un contenedor

El código siguiente limpia los recursos que creó la aplicación; para ello, quita todo el contenedor con el método delete_container. Si lo desea, también puede eliminar los archivos locales.

La aplicación se detiene para la entrada del usuario mediante una llamada a input() antes de eliminar el blob, el contenedor y los archivos locales. Compruebe que los recursos se crearon correctamente antes de su eliminación.

Agregue este código al final del bloque try:

# Clean up
print("\nPress the Enter key to begin clean up")
input()

print("Deleting blob container...")
container_client.delete_container()

print("Deleting the local source and downloaded files...")
os.remove(upload_file_path)
os.remove(download_file_path)
os.rmdir(local_path)

print("Done")

Para más información sobre cómo eliminar un contenedor y explorar más ejemplos de código, consulte Eliminación y restauración de un contenedor de blobs con Python.

Ejecución del código

Esta aplicación crea un archivo de prueba en la carpeta local y lo carga en Azure Blob Storage. A continuación, el ejemplo enumera los blobs del contenedor y descarga el archivo con otro nombre. Se pueden comparar los archivos antiguos y nuevos.

Vaya al directorio que contiene el archivo blob-quickstart.py y ejecute el siguiente comando de python para ejecutar la aplicación:

python blob_quickstart.py

La salida de la aplicación es similar al ejemplo siguiente (se omiten los valores UUID para mejorar la legibilidad):

Azure Blob Storage Python quickstart sample

Uploading to Azure Storage as blob:
        quickstartUUID.txt

Listing blobs...
        quickstartUUID.txt

Downloading blob to
        ./data/quickstartUUIDDOWNLOAD.txt

Press the Enter key to begin clean up

Deleting blob container...
Deleting the local source and downloaded files...
Done

Antes de comenzar el proceso de limpieza, compruebe la carpeta data para ver si están los dos archivos. Puede compararlos y comprobar que son idénticos.

Limpieza de recursos

Después de comprobar los archivos y finalizar las pruebas, presione la tecla ENTRAR para eliminar los archivos de prueba junto con el contenedor que creó en la cuenta de almacenamiento. También puede usar la CLI de Azure para eliminar recursos.

Cuando haya terminado con el inicio rápido, puede limpiar los recursos que creó con el siguiente comando:

azd down

Se le pedirá que confirme la eliminación de los recursos. Escriba y para confirmar.

Pasos siguientes

En esta guía de inicio rápido, ha aprendido a cargar, descargar y enumerar blobs mediante Python.

Para ver las aplicaciones de ejemplo de Blob Storage, siga estos pasos:

Ejemplos de biblioteca de Azure Blob Storage para Python