Charger un objet blob de blocs en Python

• .NET
• Java
• JavaScript
• TypeScript
• Python
• Go

Cet article montre comment charger un objet blob à l’aide de la bibliothèque de client Stockage Azure pour Python. Vous pouvez charger des données dans un objet blob de blocs depuis un chemin d’accès de fichier, un flux, un objet binaire ou une chaîne de texte. Vous pouvez aussi charger des objets blob avec des balises d’index.

Pour en savoir plus sur le chargement d’objet blob à l’aide d’API asynchrones, consultez Charger des objets blob de manière asynchrone.

Prérequis

• Abonnement Azure : créez-en un gratuitement
• Compte de stockage Azure : créez un compte de stockage
• Python 3.8+

Paramétrer votre environnement

Si vous n’avez pas de projet existant, cette section vous montre comment configurer un projet pour utiliser la bibliothèque de client Stockage Blob Azure pour Python. Pour plus d’informations, consultez Bien démarrer avec Stockage Blob Azure et Python.

Pour utiliser les exemples de code de cet article, effectuez les étapes suivantes pour configurer votre projet.

Installer des packages

Installez les packages suivants en utilisant pip install :

pip install azure-storage-blob azure-identity

Ajouter des instructions import

Ajoutez les instructions import suivantes :

import io
import os
import uuid
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient, ContainerClient, BlobBlock, BlobClient, StandardBlobTier

Autorisation

Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour charger un objet blob. Pour l’autorisation avec Microsoft Entra ID (recommandé), vous devez disposer au minimum du rôle RBAC Azure intégré Contributeur aux données Blob du stockage. Si vous souhaitez en savoir plus, consulter l’aide sur l’autorisation pour les opérations Put Blob (API REST) et Put Block (API REST).

Créer un objet client

Pour connecter une application au Stockage Blob, créez une instance de BlobServiceClient. L’exemple suivant montre comment créer un objet client à l’aide de DefaultAzureCredential pour l’autorisation :

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

Vous pouvez également créer des objets clients pour des conteneurs ou des blobs spécifiques, directement ou à partir de l’objet BlobServiceClient. Pour en savoir plus sur la création et la gestion d’objets clients, consultez Créer et gérer des objets clients qui interagissent avec des ressources de données.

Charger des données dans un blob de blocs

Pour charger un blob en utilisant un flux ou un objet binaire, utilisez la méthode suivante :

• upload_blob

Cette méthode crée un blob à partir d’une source de données avec segmentation automatique, ce qui signifie que la source de données peut être divisée en blocs plus petits puis chargée. Pour effectuer le chargement, la bibliothèque de client peut utiliser Put Blob ou une série d’appels Put Block suivis de Put Block List. Ce comportement dépend de la taille globale de l’objet et de la façon dont les options de transfert de données sont définies.

Charger un blob de blocs à partir d’un chemin de fichier local

L’exemple suivant charge un fichier dans un objet blob de blocs à l’aide d’un objet BlobClient :

def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)

Charger un blob de blocs à partir d’un flux

L’exemple suivant crée des octets aléatoires de données, et charge un objet BytesIO dans un objet blob de blocs à l’aide d’un objet BlobClient :

def upload_blob_stream(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    input_stream = io.BytesIO(os.urandom(15))
    blob_client.upload_blob(input_stream, blob_type="BlockBlob")

Charger des données binaires dans un objet blob de blocs

L’exemple suivant charge des données binaires dans un objet blob de blocs à l’aide d’un objet BlobClient:

def upload_blob_data(self, blob_service_client: BlobServiceClient, container_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
    data = b"Sample data for blob"

    # Upload the blob data - default blob type is BlockBlob
    blob_client.upload_blob(data, blob_type="BlockBlob")

Charger un blob de blocs avec des balises d’index

L’exemple suivant charge un objet blob de blocs avec des étiquettes d’index :

def upload_blob_tags(self, blob_service_client: BlobServiceClient, container_name: str):
    container_client = blob_service_client.get_container_client(container=container_name)
    sample_tags = {"Content": "image", "Date": "2022-01-01"}
    with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
        blob_client = container_client.upload_blob(name="sample-blob.txt", data=data, tags=sample_tags)

Charger un objet blob de blocs avec des options de configuration

Vous pouvez définir des options de configuration de bibliothèque de client lors du chargement d’un objet blob. Ces options peuvent être paramétrées pour améliorer les performances, améliorer la fiabilité et optimiser les coûts. Les exemples de code suivants montrent comment définir les options de configuration pour un chargement, tant au niveau de la méthode qu’au niveau du client, dans le cadre de l’instanciation de BlobClient. Ces options peuvent également être configurées pour une instance ContainerClient ou une instance BlobServiceClient.

Spécifier les options de transfert de données pour le chargement

Vous pouvez définir les options de configuration à l’occasion de l’instanciation d’un client afin d’optimiser les opérations de transfert de données sur le plan des performances. Vous pouvez transmettre les arguments de mot clé suivants lors de la construction d’un objet client en Python :

• max_block_size – Taille de bloc maximale pour le chargement d’un objet blob de blocs sous forme de blocs. La valeur par défaut est 4 Mio.
• max_single_put_size – Si la taille du blob est inférieure ou égale à max_single_put_size, le blob est chargé avec une seule demande Put Blob. Si la taille du blob est supérieure à max_single_put_size ou n’est pas connue, le blob est chargé en blocs à l’aide de Put Block puis commité à l’aide de Put Block List. La valeur par défaut est 64 Mio.

Pour plus d’informations sur les limites de taille de transfert pour Stockage Blob, consultez Objectifs de mise à l’échelle pour Stockage Blob.

Pour les opérations de chargement, vous pouvez également transmettre l’argument max_concurrency lors de l’appel de upload_blob. Cet argument définit le nombre maximal de connexions parallèles à utiliser lorsque la taille du blob dépasse 64 Mio.

L’exemple de code suivant montre comment spécifier les options de transfert de données lors de la création d’un objet BlobClient, et comment charger les données à l’aide de cet objet client. Les valeurs fournies dans cet exemple ne sont pas destinées à être une recommandation. Pour régler correctement ces valeurs, vous devez tenir compte des besoins spécifiques de votre application.

def upload_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
    # Create a BlobClient object with data transfer options for upload
    blob_client = BlobClient(
        account_url=account_url, 
        container_name=container_name, 
        blob_name=blob_name,
        credential=DefaultAzureCredential(),
        max_block_size=1024*1024*4, # 4 MiB
        max_single_put_size=1024*1024*8 # 8 MiB
    )
    
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, max_concurrency=2)

Pour en savoir plus sur le réglage des options de transfert de données, consultez Réglage des performances pour les chargements et les téléchargements avec .NET.

Définir le niveau d’accès d’un objet blob pendant le chargement

Vous pouvez définir le niveau d’accès d’un blob lors du chargement en transmettant l’argument de mot clé standard_blob_tier à upload_blob. Stockage Azure offre différents niveaux d’accès, ce qui vous permet de stocker vos données blob de la manière la plus économique possible en fonction de leur utilisation.

L’exemple de code suivant montre comment définir le niveau d’accès lors du chargement d’un objet blob :

def upload_blob_access_tier(self, blob_service_client: BlobServiceClient, container_name: str, blob_name: str):
    blob_client = blob_service_client.get_blob_client(container=container_name, blob=blob_name)
    
    #Upload blob to the cool tier
    with open(file=os.path.join(r'file_path', blob_name), mode="rb") as data:
        blob_client = blob_client.upload_blob(data=data, overwrite=True, standard_blob_tier=StandardBlobTier.COOL)

La définition du niveau d’accès est autorisée seulement sur les objets blob de blocs. Vous pouvez définir le niveau d’accès d’un objet blob de blocs sur Hot, Cool, Coldou Archive. Pour définir le niveau d’accès sur Cold, vous devez utiliser une version minimale de la bibliothèque cliente de la version 12.15.0.

Pour en savoir plus sur les niveaux d’accès, consultez Vue générale des niveaux d’accès .

Charger un objet blob de blocs en mettant en lots des blocs et en validant

Vous pouvez avoir un meilleur contrôle sur la répartition des chargements dans des blocs en indexant manuellement des blocs de données individuels. Quand tous les blocs qui composent un blob sont indexés, vous pouvez les valider dans le Stockage Blob.

Utilisez la méthode suivante pour créer un bloc à valider dans le cadre d’un objet blob :

• stage_block

Utilisez la méthode suivante pour écrire un objet blob en spécifiant la liste des ID de bloc qui composent l’objet blob :

• commit_block_list

L’exemple suivant lit les données d’un fichier et de blocs d’index à valider dans le cadre d’un objet blob :

def upload_blocks(self, blob_container_client: ContainerClient, local_file_path: str, block_size: int):
    file_name = os.path.basename(local_file_path)
    blob_client = blob_container_client.get_blob_client(file_name)

    with open(file=local_file_path, mode="rb") as file_stream:
        block_id_list = []

        while True:
            buffer = file_stream.read(block_size)
            if not buffer:
                break

            block_id = uuid.uuid4().hex
            block_id_list.append(BlobBlock(block_id=block_id))

            blob_client.stage_block(block_id=block_id, data=buffer, length=len(buffer))

        blob_client.commit_block_list(block_id_list)

Charger des objets blob de manière asynchrone

La bibliothèque cliente Stockage Blob Azure pour Python prend en charge le chargement asynchrone d’objets blob. Pour en savoir plus sur les exigences de configuration de projet, consultez programmation asynchrone.

Procédez comme suit pour charger un objet blob à l’aide d’API asynchrones :

1. Ajoutez les instructions d’importation suivantes :

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

2. Ajoutez du code pour exécuter le programme à l’aide de asyncio.run. Cette fonction exécute la coroutine passée, main() dans notre exemple et gère la boucle d’événement asyncio. Les coroutines sont déclarées avec la syntaxe asynchrone/await. Dans cet exemple, la main()coroutine crée d’abord le niveau supérieur BlobServiceClient à l’aide de async with, puis appelle la méthode qui charge l’objet blob. Notez que seul le client de niveau supérieur doit utiliser async with, car d’autres clients créés à partir de celui-ci partagent le même pool de connexions.

   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.upload_blob_file(blob_service_client, "sample-container")
   
   if __name__ == '__main__':
       asyncio.run(main())
   

3. Ajoutez du code pour charger l’objet blob. L’exemple suivant charge un objet blob à partir d’un chemin d’accès de fichier local à l’aide d’un objet ContainerClient. Le code est identique à l’exemple synchrone, sauf que la méthode est déclarée avec le mot clé async et que le mot clé await est utilisé lors de l’appel de la méthode upload_blob.

   async def upload_blob_file(self, blob_service_client: BlobServiceClient, container_name: str):
       container_client = blob_service_client.get_container_client(container=container_name)
       with open(file=os.path.join('filepath', 'filename'), mode="rb") as data:
           blob_client = await container_client.upload_blob(name="sample-blob.txt", data=data, overwrite=True)
   

Avec cette configuration de base en place, vous pouvez implémenter d’autres exemples dans cet article en tant que coroutines à l’aide de la syntaxe asynchrone/await.

Ressources

Pour en savoir plus sur le chargement d’objets blob à l’aide de la bibliothèque de client Stockage Blob Azure pour Python, consultez les ressources suivantes.

Exemples de code

• Afficher synchrone ou exemples de code asynchrones de cet article (GitHub)

Opérations de l'API REST

Le kit SDK Azure pour Python contient des bibliothèques qui reposent sur l’API REST Azure, ce qui vous permet d’interagir avec les opérations de l’API REST via des paradigmes Python familiers. Les méthodes de bibliothèque de client pour le chargement d’objets blob utilisent les opérations d’API REST suivantes :

• Put Blob (API REST)
• Put Block (API REST)

Ressources de bibliothèque cliente

• Documentation de référence sur la bibliothèque cliente
• Code source de la bibliothèque de client
• Package (PyPi)

Voir aussi

• Gérer et rechercher des données blob Azure dans l’index d’objet blob
• Utiliser des balises d’index de blob pour gérer et rechercher des données sur Stockage Blob Azure

Étape suivante

• Cet article fait partie du guide Stockage Blob pour Python pour les développeurs. Consultez la liste complète des articles du guide pour les développeurs à la page Générer votre application.