Télécharger un blob avec Python
Cet article montre comment télécharger un blob avec la bibliothèque de client du Stockage Azure pour Python. Vous pouvez télécharger des données blob vers différentes destinations, notamment un chemin d’accès de fichier local, un flux ou une chaîne de texte. Vous pouvez également ouvrir un flux d’objets blob et lire à partir de celui-ci.
Pour en savoir plus sur le chargement d’objet blob à l’aide d’API asynchrones, consultez Télé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 téléchargement. Pour en savoir plus, consultez les conseils d’autorisation pour l’opération d’API REST suivante :
Télécharger un objet blob
Vous pouvez utiliser la méthode suivante pour télécharger un objet blob :
La méthode download_blob
renvoie un objet StorageStreamDownloader. Au cours d’un téléchargement, les bibliothèques de client divisent la demande de téléchargement en blocs, chaque bloc étant ensuite téléchargé via une demande de plage Get Blob distincte. Ce comportement dépend de la taille totale du blob et de la façon dont les options de transfert de données sont définies.
Télécharger dans un chemin de fichier
L’exemple suivant télécharge un blob dans un chemin d’accès de fichiers :
def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob:
download_stream = blob_client.download_blob()
sample_blob.write(download_stream.readall())
Télécharger dans un flux
L’exemple suivant télécharge un blob dans un flux. Dans cet exemple, StorageStreamDownloader.read_into télécharge le contenu de l’objet blob dans un flux et retourne le nombre d’octets lus :
def download_blob_to_stream(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# readinto() downloads the blob contents to a stream and returns the number of bytes read
stream = io.BytesIO()
num_bytes = blob_client.download_blob().readinto(stream)
print(f"Number of bytes: {num_bytes}")
Télécharger un objet blob en blocs
L’exemple suivant télécharge un objet blob et itère sur des blocs dans le flux de téléchargement. Dans cet exemple, StorageStreamDownloader.chunks retourne un itérateur, qui vous permet de lire le contenu d’objet blob en blocs :
def download_blob_chunks(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# This returns a StorageStreamDownloader
stream = blob_client.download_blob()
chunk_list = []
# Read data in chunks to avoid loading all into memory at once
for chunk in stream.chunks():
# Process your data (anything can be done here - 'chunk' is a byte array)
chunk_list.append(chunk)
Télécharger dans une chaîne
L’exemple suivant télécharge le contenu d’objet blob sous forme de texte. Dans cet exemple, le paramètre encoding
est nécessaire pour que readall()
renvoie une chaîne, sinon il retourne des octets :
def download_blob_to_string(self, blob_service_client: BlobServiceClient, container_name):
blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt")
# encoding param is necessary for readall() to return str, otherwise it returns bytes
downloader = blob_client.download_blob(max_concurrency=1, encoding='UTF-8')
blob_text = downloader.readall()
print(f"Blob contents: {blob_text}")
Télé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 téléchargement d’un objet blob. Ces options peuvent être paramétrées pour améliorer les performances et améliorer la fiabilité. Les exemples de code suivants montrent comment définir les options de configuration pour un télé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 lors du télé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_chunk_get_size
– Taille de bloc maximale utilisée pour le téléchargement d’un blob. La valeur par défaut est 4 Mio.max_single_get_size
– Taille maximale pour un blob à télécharger en un seul appel. Si la taille totale du blob dépassemax_single_get_size
, le reste des données blob est téléchargé en blocs. La valeur par défaut est 32 Mio.
Pour les opérations de téléchargement, vous pouvez également transmettre l’argument max_concurrency
lors de l’appel de download_blob. Cet argument définit le nombre maximal de connexions parallèles pour l’opération de téléchargement.
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 télé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 download_blob_transfer_options(self, account_url: str, container_name: str, blob_name: str):
# Create a BlobClient object with data transfer options for download
blob_client = BlobClient(
account_url=account_url,
container_name=container_name,
blob_name=blob_name,
credential=DefaultAzureCredential(),
max_single_get_size=1024*1024*32, # 32 MiB
max_chunk_get_size=1024*1024*4 # 4 MiB
)
with open(file=os.path.join(r'file_path', 'file_name'), mode="wb") as sample_blob:
download_stream = blob_client.download_blob(max_concurrency=2)
sample_blob.write(download_stream.readall())
Télécharger des objets blob de manière asynchrone
La bibliothèque cliente Stockage Blob Azure pour Python prend en charge le téléchargement asynchrone d’objets blob. Pour en savoir plus sur les exigences de configuration de projet, consultez programmation asynchrone.
Procédez comme suit pour télécharger un objet blob à l’aide d’API asynchrones :
Ajoutez les instructions d’importation suivantes :
import asyncio from azure.identity.aio import DefaultAzureCredential from azure.storage.blob.aio import BlobServiceClient, BlobClient
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énementasyncio
. Les coroutines sont déclarées avec la syntaxe asynchrone/await. Dans cet exemple, lamain()
coroutine crée d’abord le niveau supérieurBlobServiceClient
à l’aide deasync with
, puis appelle la méthode qui télécharge l’objet blob. Notez que seul le client de niveau supérieur doit utiliserasync 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.download_blob_to_file(blob_service_client, "sample-container") if __name__ == '__main__': asyncio.run(main())
Ajoutez du code pour télécharger l’objet blob. L’exemple suivant télécharge un blob dans un chemin d’accès de fichier local à l’aide d’un objet
BlobClient
. 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éthodedownload_blob
.async def download_blob_to_file(self, blob_service_client: BlobServiceClient, container_name): blob_client = blob_service_client.get_blob_client(container=container_name, blob="sample-blob.txt") with open(file=os.path.join(r'filepath', 'filename'), mode="wb") as sample_blob: download_stream = await blob_client.download_blob() data = await download_stream.readall() sample_blob.write(data)
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 télé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 de développement logiciel (SDK) Azure pour Python contient des bibliothèques qui s’appuient sur l’API REST Azure, vous permettant d’interagir avec les opérations de l’API REST par le biais de paradigmes Python familiers. Les méthodes de bibliothèque de client pour télécharger des objets blob utilisent l’opération d’API REST suivante :
- Get Blob (API REST)
Exemples de code
- Afficher synchrone ou exemples de code asynchrones de cet article (GitHub)
Ressources de bibliothèque cliente
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour