Charger un objet blob de blocs en Python

  • Article

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

  • Cet article suppose que vous disposez déjà d'un projet configuré pour fonctionner avec la bibliothèque client Azure Blob Storage pour Python. Pour en savoir plus sur la configuration de votre projet, y compris l'installation du package, l'ajout d'instructions import et la création d'un objet client autorisé, consultez Bien démarrer avec Azure Blob Storage et Python.
  • Pour utiliser des API asynchrones dans votre code, consultez les conditions requises dans la section programmation asynchrone.
  • Le mécanisme d’autorisation doit disposer des autorisations nécessaires pour effectuer une opération de chargement. Pour plus d’informations, consultez les conseils d’autorisation pour les opérations d’API REST suivantes :

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 :

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 :

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

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.

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 :

Exemples de code

Ressources de bibliothèque cliente

Voir aussi