Biblioteca cliente de Blobs de Azure Storage para Python: versión 12.19.0

Artículo
11/07/2023

Azure Blob Storage es la solución de almacenamiento de objetos de Microsoft para la nube. Blob Storage está optimizado para el almacenamiento de cantidades masivas de datos no estructurados, como texto o datos binarios.

Blob Storage resulta muy conveniente para lo siguiente:

Servicio de imágenes o documentos directamente a un explorador
Almacenar archivos para el acceso distribuido.
Realizar streaming de audio y vídeo.
Almacenar datos para copia de seguridad y restauración, recuperación ante desastres y archivado.
Almacenar de datos para el análisis por un servicio local u hospedado por Azure.

Introducción

Requisitos previos

Se requiere Python 3.7 o posterior para usar este paquete. Para más información, lea nuestra página sobre la directiva de compatibilidad con versiones de Azure SDK para Python.
Debe tener una suscripción de Azure y una cuenta de almacenamiento de Azure para usar este paquete.

Instalar el paquete

Instale la biblioteca cliente de Blobs de Azure Storage para Python con pip:

pip install azure-storage-blob

Crear una cuenta de almacenamiento

Si desea crear una cuenta de almacenamiento, puede usar Azure Portal, Azure PowerShell o la CLI de Azure:

# Create a new resource group to hold the storage account -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Creación del cliente

La biblioteca cliente de Blobs de Azure Storage para Python le permite interactuar con tres tipos de recursos: la propia cuenta de almacenamiento, los contenedores de blobs y los blobs. La interacción con estos recursos comienza con una instancia de un cliente. Para crear un objeto de cliente, necesitará la dirección URL de la cuenta de blob service de la cuenta de almacenamiento y una credencial que le permita acceder a la cuenta de almacenamiento:

from azure.storage.blob import BlobServiceClient

service = BlobServiceClient(account_url="https://<my-storage-account-name>.blob.core.windows.net/", credential=credential)

Búsqueda de la dirección URL de la cuenta

Puede encontrar la dirección URL del servicio de blobs de la cuenta de almacenamiento mediante Azure Portal, Azure PowerShell o la CLI de Azure:

# Get the blob service account url for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.blob"

Tipos de credenciales

El credential parámetro se puede proporcionar en varias formas diferentes, según el tipo de autorización que desee usar:

Para usar una credencial de token de Azure Active Directory (AAD), proporcione una instancia del tipo de credencial deseado obtenido de la biblioteca azure-identity . Por ejemplo, DefaultAzureCredential se puede usar para autenticar al cliente.

Esto requiere una configuración inicial:
- Instalación de azure-identity
- Registro de una nueva aplicación de AAD y concesión de permisos para acceder a Azure Storage
- Concesión de acceso a datos de blobs de Azure con RBAC en Azure Portal
- Establezca los valores del identificador de cliente, el identificador de inquilino y el secreto de cliente de la aplicación de AAD como variables de entorno: AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET
Use la credencial de token devuelta para autenticar al cliente:
```
    from azure.identity import DefaultAzureCredential
    from azure.storage.blob import BlobServiceClient
    token_credential = DefaultAzureCredential()

    blob_service_client = BlobServiceClient(
        account_url="https://<my_account_name>.blob.core.windows.net",
        credential=token_credential
    )
```

Para usar un token de firma de acceso compartido (SAS), proporcione el token como una cadena. Si la dirección URL de la cuenta incluye el token de SAS, omita el parámetro de credencial. Puede generar un token de SAS desde Azure Portal en "Firma de acceso compartido" o usar una de las generate_sas() funciones para crear un token sas para la cuenta de almacenamiento, el contenedor o el blob:

from datetime import datetime, timedelta
from azure.storage.blob import BlobServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

blob_service_client = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential=sas_token)

Para usar una clave compartida de cuenta de almacenamiento (también conocida como clave de acceso o clave de acceso), proporcione la clave como una cadena. Esto puede encontrarse en Azure Portal en la sección "Claves de acceso" o ejecutando el siguiente comando de la CLI de Azure:

az storage account keys list -g MyResourceGroup -n MyStorageAccount

Use la clave como parámetro de credencial para autenticar el cliente:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")
```
Si usa una dirección URL personalizada (lo que significa que la dirección URL no está en este formato <my_account_name>.blob.core.windows.net), cree una instancia del cliente con la credencial siguiente:
```
from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", 
   credential={"account_name": "<your_account_name>", "account_key":"<account_access_key>"})
```
Para usar el acceso de lectura público anónimo, simplemente omita el parámetro de credencial.

Creación del cliente a partir de un cadena de conexión

Según el caso de uso y el método de autorización, es posible que prefiera inicializar una instancia de cliente con un cadena de conexión de almacenamiento en lugar de proporcionar la dirección URL de la cuenta y las credenciales por separado. Para ello, pase el cadena de conexión de almacenamiento al método de clase del from_connection_string cliente:

from azure.storage.blob import BlobServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = BlobServiceClient.from_connection_string(conn_str=connection_string)

La cadena de conexión a la cuenta de almacenamiento se puede encontrar en Azure Portal en la sección "Claves de acceso" o mediante la ejecución del siguiente comando de la CLI:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Conceptos clave

Los siguientes componentes componen Azure Blob Service:

La propia cuenta de almacenamiento
Un contenedor dentro de la cuenta de almacenamiento
Un blob dentro de un contenedor

La biblioteca cliente de Blobs de Azure Storage para Python le permite interactuar con cada uno de estos componentes mediante el uso de un objeto de cliente dedicado.

Clientes

Se proporcionan cuatro clientes diferentes para interactuar con los distintos componentes de Blob Service:

BlobServiceClient : este cliente representa la interacción con la propia cuenta de almacenamiento de Azure y permite adquirir instancias de cliente preconfiguradas para acceder a los contenedores y blobs dentro. Proporciona operaciones para recuperar y configurar las propiedades de la cuenta, así como enumerar, crear y eliminar contenedores dentro de la cuenta. Para realizar operaciones en un contenedor o blob específico, recupere un cliente mediante los get_container_client métodos o get_blob_client .
ContainerClient : este cliente representa la interacción con un contenedor específico (que aún no es necesario) y permite adquirir instancias de cliente preconfiguradas para acceder a los blobs dentro. Proporciona operaciones para crear, eliminar o configurar un contenedor e incluye operaciones para enumerar, cargar y eliminar los blobs dentro de él. Para realizar operaciones en un blob específico dentro del contenedor, recupere un cliente mediante el get_blob_client método .
BlobClient : este cliente representa la interacción con un blob específico (que aún no es necesario). Proporciona operaciones para cargar, descargar, eliminar y crear instantáneas de un blob, así como operaciones específicas por tipo de blob.
BlobLeaseClient : este cliente representa interacciones de concesión con o ContainerClientBlobClient. Proporciona operaciones para adquirir, renovar, liberar, cambiar y interrumpir una concesión en un recurso especificado.

Clientes asincrónicos

Esta biblioteca incluye una API asincrónica completa compatible con Python 3.5 y versiones posteriores. Para usarlo, primero debe instalar un transporte asincrónico, como aiohttp. Consulte la documentación de azure-core para más información.

Los clientes asincrónicos y las credenciales deben cerrarse cuando ya no sean necesarios. Estos objetos son administradores de contexto asincrónicos y definen métodos asincrónicos close .

Tipos de blobs

Una vez que haya inicializado un cliente, puede elegir entre los distintos tipos de blobs:

Los blobs en bloques almacenan texto y datos binarios, hasta aproximadamente 4,75 TiB. Los blobs en bloques se componen de bloques de datos que se pueden administrar individualmente.
Los blobs en anexos constan de bloques, como los blobs en bloques, pero están optimizados para operaciones de anexión. Los blobs en anexos son ideales para escenarios como el registro de datos de máquinas virtuales.
Los blobs en páginas almacenan archivos de acceso aleatorio con un tamaño máximo de 8 TiB. Los blobs en páginas almacenan archivos de disco duro virtual (VHD) y sirven como discos para máquinas virtuales de Azure

Ejemplos

En las secciones siguientes se proporcionan varios fragmentos de código que abarcan algunas de las tareas de Storage Blob más comunes, entre las que se incluyen:

Creación de un contenedor
Carga de un blob
Descarga de un blob
Enumeración de blobs

Tenga en cuenta que se debe crear un contenedor antes de cargar o descargar un blob.

Crear un contenedor

Cree un contenedor desde donde pueda cargar o descargar blobs.

from azure.storage.blob import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

container_client.create_container()

Uso del cliente asincrónico para cargar un blob

from azure.storage.blob.aio import ContainerClient

container_client = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

await container_client.create_container()

Carga de un blob

Carga de un blob en el contenedor

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    blob.upload_blob(data)

Uso del cliente asincrónico para cargar un blob

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./SampleSource.txt", "rb") as data:
    await blob.upload_blob(data)

Descarga de un blob

Descarga de un blob desde el contenedor

from azure.storage.blob import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    blob_data = blob.download_blob()
    blob_data.readinto(my_blob)

Descarga de un blob de forma asincrónica

from azure.storage.blob.aio import BlobClient

blob = BlobClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer", blob_name="my_blob")

with open("./BlockDestination.txt", "wb") as my_blob:
    stream = await blob.download_blob()
    data = await stream.readall()
    my_blob.write(data)

Enumeración de blobs

Enumeración de los blobs del contenedor

from azure.storage.blob import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = container.list_blobs()
for blob in blob_list:
    print(blob.name + '\n')

Enumeración de los blobs de forma asincrónica

from azure.storage.blob.aio import ContainerClient

container = ContainerClient.from_connection_string(conn_str="<connection_string>", container_name="mycontainer")

blob_list = []
async for blob in container.list_blobs():
    blob_list.append(blob)
print(blob_list)

Configuración opcional

Argumentos de palabra clave opcionales que se pueden pasar en el cliente y en el nivel de operación.

Configuración de la directiva de reintento

Use los argumentos de palabra clave siguientes al crear una instancia de un cliente para configurar la directiva de reintento:

retry_total (int): número total de reintentos que se van a permitir. Tiene prioridad sobre otros recuentos. retry_total=0 Pase si no desea volver a intentarlo en las solicitudes. El valor predeterminado es 10.
retry_connect (int): cuántos errores relacionados con la conexión se reintentan. El valor predeterminado es 3.
retry_read (int): cuántas veces se reintenta en los errores de lectura. El valor predeterminado es 3.
retry_status (int): cuántas veces se reintenta en códigos de estado incorrectos. El valor predeterminado es 3.
retry_to_secondary (bool): indica si la solicitud se debe reintentar en la secundaria, si es posible. Esto solo debe habilitarse en las cuentas de RA-GRS y se pueden controlar los datos potencialmente obsoletos. Tiene como valor predeterminado False.

Configuración de cifrado

Use los argumentos de palabra clave siguientes al crear instancias de un cliente para configurar el cifrado:

require_encryption (bool): si se establece en True, aplicará que los objetos estén cifrados y los descifren.
encryption_version (str): especifica la versión del cifrado que se va a usar. Las opciones actuales son '2.0' o '1.0' y el valor predeterminado es '1.0'. La versión 1.0 está en desuso y se recomienda encarecidamente usar la versión 2.0.
key_encryption_key (objeto): clave-cifrado-clave proporcionada por el usuario. La instancia debe implementar los métodos siguientes:
- wrap_key(key)--encapsula la clave especificada mediante un algoritmo de la elección del usuario.
- get_key_wrap_algorithm()--devuelve el algoritmo usado para encapsular la clave simétrica especificada.
- get_kid()--devuelve un identificador de clave de cadena para esta clave-cifrado-clave.
key_resolver_function (invocable): solucionador de claves proporcionado por el usuario. Usa la cadena kid para devolver una clave de cifrado de claves que implementa la interfaz definida anteriormente.

Otra configuración de cliente o por operación

Otros argumentos de palabra clave de configuración opcionales que se pueden especificar en el cliente o por operación.

Argumentos de palabra clave de cliente:

connection_timeout (int): número de segundos que el cliente esperará para establecer una conexión con el servidor. El valor predeterminado es de 20 segundos.
read_timeout (int): número de segundos que el cliente esperará, entre operaciones de lectura consecutivas, para una respuesta del servidor. Se trata de un tiempo de espera de nivel de socket y no se ve afectado por el tamaño total de los datos. Los tiempos de espera de lectura del lado cliente se reintentarán automáticamente. El valor predeterminado es 60 segundos.
transport (Any): transporte proporcionado por el usuario para enviar la solicitud HTTP.

Argumentos de palabra clave por operación:

raw_response_hook (invocable): la devolución de llamada especificada usa la respuesta devuelta desde el servicio.
raw_request_hook (invocable): la devolución de llamada especificada usa la solicitud antes de enviarse al servicio.
client_request_id (str): el usuario opcional especificó la identificación de la solicitud.
user_agent (str): anexa el valor personalizado al encabezado user-agent que se enviará con la solicitud.
logging_enable (bool): habilita el registro en el nivel DEBUG. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
logging_body (bool): habilita el registro del cuerpo de la solicitud y la respuesta. El valor predeterminado es False. También se puede pasar en el nivel de cliente para habilitarlo para todas las solicitudes.
encabezados (dict): pase encabezados personalizados como pares clave y valor. Por ejemplo headers={'CustomValue': value}

Solución de problemas

General

Los clientes de Storage Blob generan excepciones definidas en Azure Core.

Esta lista se puede usar como referencia para detectar excepciones iniciadas. Para obtener el código de error específico de la excepción, use el error_code atributo , es decir, exception.error_code.

Registro

Esta biblioteca usa la biblioteca de registro estándar para el registro. La información básica sobre las sesiones HTTP (direcciones URL, encabezados, etc.) se registra en el nivel INFO.

El registro detallado de nivel DEBUG, incluidos los cuerpos de solicitud/respuesta y los encabezados no aprobados, se puede habilitar en un cliente con el logging_enable argumento :

import sys
import logging
from azure.storage.blob import BlobServiceClient

# Create a logger for the 'azure.storage.blob' SDK
logger = logging.getLogger('azure.storage.blob')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
service_client = BlobServiceClient.from_connection_string("your_connection_string", logging_enable=True)

Igualmente, logging_enable puede habilitar el registro detallado de una sola operación, aunque no esté habilitado para el cliente:

service_client.get_service_stats(logging_enable=True)

Pasos siguientes

Más código de ejemplo

Introducción a nuestros ejemplos de blobs.

Hay varios ejemplos del SDK de Python de Storage Blobs disponibles en el repositorio de GitHub del SDK. Estos ejemplos proporcionan código de ejemplo para escenarios adicionales que se suelen encontrar al trabajar con blobs de Storage:

blob_samples_container_access_policy.py (versión asincrónica): ejemplos para establecer directivas de acceso:
- Configuración de la directiva de acceso para el contenedor
blob_samples_hello_world.py (versión asincrónica): ejemplos de tareas comunes de Storage Blob:
- Configuración de un contenedor
- Creación de un blob en bloques, páginas o anexos
- Cargar blobs
- Descargar blobs
- Eliminar blobs
blob_samples_authentication.py (versión asincrónica): ejemplos para autenticar y crear el cliente:
- Desde un cadena de conexión
- Desde una clave de acceso compartido
- Desde un token de firma de acceso compartido
- Desde Active Directory
blob_samples_service.py (versión asincrónica): ejemplos para interactuar con blob service:
- Obtención de información de la cuenta
- Obtención y establecimiento de las propiedades del servicio
- Obtención de estadísticas de servicio
- Creación, enumeración y eliminación de contenedores
- Obtención del cliente de blobs o contenedores
blob_samples_containers.py (versión asincrónica): ejemplos para interactuar con contenedores:
- Creación de un contenedor y eliminación de contenedores
- Establecimiento de metadatos en contenedores
- Obtención de propiedades de contenedor
- Adquisición de una concesión en el contenedor
- Establecimiento de una directiva de acceso en un contenedor
- Carga, lista y eliminación de blobs en el contenedor
- Obtención del cliente de blobs para interactuar con un blob específico
blob_samples_common.py (versión asincrónica): ejemplos comunes a todos los tipos de blobs:
- Crear una instantánea
- Eliminación de una instantánea de blob
- Eliminación temporal de un blob
- Recuperar un blob
- Adquisición de una concesión en un blob
- Copia de un blob desde una dirección URL
blob_samples_directory_interface.py : ejemplos para interactuar con Blob Storage como si fuera un directorio en un sistema de archivos:
- Copiar (cargar o descargar) un único archivo o directorio
- Enumerar archivos o directorios en un solo nivel o de forma recursiva
- Eliminar un único archivo o eliminar de forma recursiva un directorio

Documentación adicional

Para más información sobre Azure Blob Storage, consulte la documentación de Azure Blob Storage sobre docs.microsoft.com.

Contribuciones

Este proyecto agradece las contribuciones y sugerencias. La mayoría de las contribuciones requieren que acepte un Contrato de licencia para el colaborador (CLA) que declara que tiene el derecho a concedernos y nos concede los derechos para usar su contribución. Para más detalles, visite https://cla.microsoft.com.

Cuando se envía una solicitud de incorporación de cambios, un bot de CLA determinará de forma automática si tiene que aportar un CLA y completar la PR adecuadamente (por ejemplo, la etiqueta, el comentario). Solo siga las instrucciones que le dará el bot. Solo será necesario que lo haga una vez en todos los repositorios con nuestro CLA.

Este proyecto ha adoptado el Código de conducta de Microsoft Open Source. Para más información, consulte las preguntas más frecuentes del código de conducta o póngase en contacto con opencode@microsoft.com si tiene cualquier otra pregunta o comentario.

Compartir a través de