Comenzar con Azure Blob Storage y Python

Artículo
10/02/2024

En este artículo se muestra cómo conectarse a Azure Blob Storage mediante la biblioteca cliente Azure Blob Storage para Python. Una vez que se haya conectado, use las guías para desarrolladores a fin de obtener información sobre cómo el código puede realizar operaciones con contenedores, blobs y características del servicio Blob Storage.

Si quiere empezar con un ejemplo completo, consulte Inicio rápido: Biblioteca cliente de Azure Blob Storage para Python.

Referencia de API | Paquete (PyPi) | Código fuente de la biblioteca | Muestras | Enviar comentarios

Prerrequisitos

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

Configuración del proyecto

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

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

A continuación, abra el archivo de código y agregue las instrucciones de importación necesarias. En este ejemplo, agregamos lo siguiente al archivo .py:

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

Información de la biblioteca cliente de blobs:

azure.storage.blob: contiene las clases principales (objetos de cliente) que puede usar para operar en el servicio, los contenedores y los blobs.

Programación asincrónica

La biblioteca cliente de Azure Blob Storage para Python admite API sincrónicas y asincrónicas. Las API asincrónicas se basan en la biblioteca asincrónica de Python.

Siga estos pasos para usar las API asincrónicas del proyecto:

Instale un transporte asincrónico, como aiohttp. Puede instalar aiohttp junto con azure-storage-blob mediante un comando opcional de instalación de dependencias. En este ejemplo, usamos el siguiente comando pip install:
```
pip install azure-storage-blob[aio]
```
Abra el archivo de código y agregue las instrucciones de importación necesarias. En este ejemplo, agregamos lo siguiente al archivo .py:
```
import asyncio

from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient, BlobClient, ContainerClient
```
La instrucción import asyncio solo es necesaria si usa la biblioteca en el código. Aquí se agrega para mayor claridad, ya que los ejemplos de los artículos de la guía para desarrolladores usan la biblioteca asyncio.
Cree un objeto de cliente mediante async with para empezar a trabajar con recursos de datos. 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. En este ejemplo, se crea un objeto BlobServiceClient mediante async with y, a continuación, se crea un objeto ContainerClient:
```
async with BlobServiceClient(account_url, credential=credential) as blob_service_client:
    container_client = blob_service_client.get_container_client(container="sample-container")
```
Para más información, consulte los ejemplos asincrónicos de Autorización del acceso y conexión a Blob Storage.

Información de la biblioteca cliente asincrónica de blobs:

azure.storage.blob.aio: contiene las clases principales que puede usar para operar en el servicio, los contenedores y los blobs de forma asincrónica.

Autorización del acceso y conexión a Blob Storage

Para conectar una aplicación a Blob Storage, cree una instancia de la clase BlobServiceClient. Este objeto es el punto inicial para interactuar con los recursos de datos en el nivel de cuenta de almacenamiento. Puede usarlo para operar en la cuenta de almacenamiento y sus contenedores. También puede usar el cliente de servicio para crear clientes de contenedor o clientes de blobs, en función del recurso con el que necesite trabajar.

Para obtener más información sobre cómo crear y administrar objetos de cliente, incluidos los procedimientos recomendados, consulte Crear y administrar objetos de cliente que interactúan con los recursos de datos.

Puede autorizar un objeto BlobServiceClient mediante un token de autorización de Microsoft Entra, una clave de acceso de cuenta o una firma de acceso compartido. Para una seguridad óptima, Microsoft recomienda usar Microsoft Entra ID con identidades administradas para autorizar solicitudes contra datos de blobs. Para más información, vea Autorización del acceso a blobs mediante Microsoft Entra ID.

Para autorizar con Microsoft Entra ID, debe usar una entidad de seguridad. El tipo de entidad de seguridad que necesita depende de dónde se ejecute la aplicación. Use la siguiente tabla como guía:

Dónde se ejecuta la aplicación	Entidad de seguridad	Guía
Máquina local (desarrollo y pruebas)	Entidad de servicio	Con el fin de descubrir cómo registrar la aplicación, configurar un grupo de Microsoft Entra, asignar roles y configurar variables de entorno, consulte Autorización del acceso mediante entidades de servicio para desarrolladores
Máquina local (desarrollo y pruebas)	Identidad del usuario	Con el fin de descubrir cómo configurar un grupo de Microsoft Entra, asignar roles e iniciar sesión en Azure, consulte Autorización del acceso mediante credenciales para desarrolladores
Hospedado en Azure	Identidad administrada	Para descubrir cómo habilitar la identidad administrada y asignar roles, vea Autorización del acceso desde aplicaciones hospedadas en Azure mediante una identidad administrada.
Hospedado fuera de Azure (por ejemplo, aplicaciones locales)	Entidad de servicio	Para descubrir cómo registrar la aplicación, asignar roles y configurar variables de entorno, vea Autorización del acceso desde aplicaciones locales mediante una entidad de servicio de aplicación.

Autorización del acceso mediante DefaultAzureCredential

Una manera fácil y segura de autorizar el acceso y conectarse a Blob Storage es obtener un token de OAuth mediante la creación de una instancia de DefaultAzureCredential. Después, puede usar esa credencial para crear un objeto BlobServiceClient.

En el ejemplo siguiente, se crea un objeto BlobServiceClient con DefaultAzureCredential:

def get_blob_service_client_token_credential(self):
    # 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)

    return blob_service_client

Si el proyecto usa API asincrónicas, cree una instancia BlobServiceClient mediante async with:

# 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:
    # Work with data resources in the storage account

Para usar un token de firma de acceso compartido (SAS), proporcione el token como una cadena e inicialice un objeto BlobServiceClient. Si la dirección URL de la cuenta incluye el token de SAS, omita el parámetro de credencial.

def get_blob_service_client_sas(self, sas_token: str):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    # The SAS token string can be assigned to credential here or appended to the account URL
    credential = sas_token

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

    return blob_service_client

Si el proyecto usa API asincrónicas, cree una instancia BlobServiceClient mediante async with:

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

# Replace <sas_token_str> with your actual SAS token
sas_token: str = "<sas_token_str>"

async with BlobServiceClient(account_url, credential=sas_token) as blob_service_client:
    # Work with data resources in the storage account

Para obtener más información sobre cómo generar y administrar los tokens de SAS, consulte los artículos siguientes:

Grant limited access to Azure Storage resources using shared access signatures (SAS) (Otorgar acceso limitado a recursos de Azure Storage con firmas de acceso compartido [SAS])
Creación de una SAS de cuenta con Python
Creación de una SAS de servicio con Python
Creación de una SAS de delegación de usuarios con Python

Nota:

Para escenarios en los que se utilizan firmas de acceso compartido (SAS), Microsoft recomienda usar un SAS de delegación de usuario. Una SAS de delegación de usuarios está protegida con credenciales de Microsoft Entra en lugar de la clave de cuenta.

Para usar una clave compartida de la cuenta de almacenamiento, proporcione la clave como una cadena e inicialice un objeto BlobServiceClient.

def get_blob_service_client_account_key(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")
    credential = shared_access_key

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

    return blob_service_client

También puede crear un objeto BlobServiceClient mediante una cadena de conexión.

def get_blob_service_client_connection_string(self):
    # TODO: Replace <storage-account-name> with your actual storage account name
    account_url = "https://<storage-account-name>.blob.core.windows.net"
    connection_string = os.getenv("AZURE_STORAGE_CONNECTION_STRING")

    # Create the BlobServiceClient object
    blob_service_client = BlobServiceClient.from_connection_string(connection_string)

    return blob_service_client

Si el proyecto usa API asincrónicas, cree una instancia BlobServiceClient mediante async with:

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

shared_access_key = os.getenv("AZURE_STORAGE_ACCESS_KEY")

async with BlobServiceClient(account_url, credential=shared_access_key) as blob_service_client:
    # Work with data resources in the storage account

Para obtener información sobre cómo obtener claves de cuenta y directrices de procedimientos recomendados para administrar y proteger correctamente las claves, consulte Administración de claves de acceso de la cuenta de almacenamiento.

Importante

La clave de acceso de la cuenta debe usarse con precaución. Si la clave de acceso de la cuenta se pierde o se coloca por accidente en una ubicación no segura, el servicio puede volverse vulnerable. 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 proporciona características y ventajas de seguridad mejoradas y es el enfoque recomendado para administrar la autorización en los servicios de Azure.

Compilación de la aplicación

A medida que compila aplicaciones para trabajar con recursos de datos en Azure Blob Storage, el código interactúa principalmente con tres tipos de recursos: cuentas de almacenamiento, contenedores y blobs. Para más información sobre estos tipos de recursos, cómo se relacionan entre sí y cómo interactúan las aplicaciones con los recursos, consulte Descripción de cómo interactúan las aplicaciones con los recursos de datos de Blob Storage.

En las guías siguientes se muestra cómo trabajar con recursos de datos y realizar acciones específicas mediante la biblioteca cliente de Azure Storage para Python:

Guía	Descripción
Configuración de una directiva de reintentos	Implemente directivas de reintento para las operaciones de cliente.
Copia de blobs	Copie un blob de una ubicación a otra.
Creación de un contenedor	Cree contenedores de blobs.
Creación de una SAS de delegación de usuario	Creación de una SAS de delegación de usuarios para un contenedor o blob.
Creación y administración de concesiones de blobs	Establezca y administre un bloqueo en un blob.
Creación y administración de concesiones de contenedores	Establezca y administre un bloqueo en un contenedor.
Eliminación y restauración de blobs	Elimine blobs y restaure los blobs eliminados temporalmente.
Eliminación y restauración de contenedores	Elimine contenedores y restaure los contenedores eliminados temporalmente.
Descarga de los blobs	Descargue blobs mediante cadenas, secuencias y rutas de acceso de archivo.
Búsqueda de blobs mediante etiquetas	Establezca y recupere etiquetas, además de usar etiquetas para buscar blobs.
Enumeración de blobs	Enumere los blobs de diferentes maneras.
Enumeración de contenedores	Enumere los contenedores de una cuenta y las distintas opciones disponibles para personalizar una lista.
Administración de propiedades y metadatos (blobs)	Obtenga y establezca las propiedades y los metadatos de los blobs.
Administración de propiedades y metadatos (contenedores)	Obtenga y establezca las propiedades y los metadatos de los contenedores.
Optimización del rendimiento de las transferencias de datos	Optimice el rendimiento de las transferencias de datos.
Establecer o cambiar el nivel de acceso de un blob	Establezca o cambie el nivel de acceso de un blob en bloques.
Carga de blobs	Aprenda a cargar blobs mediante cadenas, secuencias, rutas de acceso de archivo y otros métodos.

Compartir vía

Comenzar con Azure Blob Storage y Python

Prerrequisitos

Configuración del proyecto

Programación asincrónica

Autorización del acceso y conexión a Blob Storage

Autorización del acceso mediante DefaultAzureCredential

Compilación de la aplicación

Comentarios

Recursos adicionales