Bibliothèque cliente d’objets blob de stockage Azure pour Python - version 12.19.0

  • Article

Le stockage Blob Azure est la solution de stockage d’objet de Microsoft pour le cloud. Le stockage Blob est optimisé pour stocker de grandes quantités de données non structurées, telles que des données texte ou binaires.

Le stockage Blob est idéal pour :

  • Mise à disposition d’images ou de documents directement dans un navigateur
  • Stockage de fichiers pour un accès distribué
  • Streaming de contenu vidéo et audio
  • Stockage de données pour la sauvegarde et la restauration, la reprise d’activité après sinistre et l’archivage
  • Stockage des données pour l’analyse par un service local ou hébergé par Azure

| Code sourcePackage (PyPI) | Package (Conda) | Documentation de référence sur les | API | Documentation produitÉchantillons

Prise en main

Prérequis

Installer le package

Installez la bibliothèque cliente d’objets blob de stockage Azure pour Python avec pip :

pip install azure-storage-blob

Créez un compte de stockage.

Si vous souhaitez créer un compte de stockage, vous pouvez utiliser le portail Azure, Azure PowerShell ou Azure CLI :

# 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

Création du client

La bibliothèque cliente Stockage Blobs Azure pour Python vous permet d’interagir avec trois types de ressources : le compte de stockage lui-même, les conteneurs de stockage d’objets blob et les objets blob. L’interaction avec ces ressources commence par une instance d’un client. Pour créer un objet client, vous aurez besoin de l’URL du compte de service blob du compte de stockage et d’informations d’identification qui vous permettent d’accéder au compte de stockage :

from azure.storage.blob import BlobServiceClient

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

Recherche de l’URL du compte

Vous pouvez trouver l’URL du service blob du compte de stockage à l’aide du portail Azure, de Azure PowerShell ou d’Azure CLI :

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

Types d’informations d’identification

Le credential paramètre peut être fourni sous plusieurs formes différentes, selon le type d’autorisation que vous souhaitez utiliser :

  1. Pour utiliser des informations d’identification de jeton Azure Active Directory (AAD), fournissez une instance du type d’informations d’identification souhaité obtenu à partir de la bibliothèque d’identité Azure. Par exemple, DefaultAzureCredential peut être utilisé pour authentifier le client.

    Cela nécessite une configuration initiale :

    • Installer azure-identity
    • Inscrire une nouvelle application AAD et accorder des autorisations d’accès au Stockage Azure
    • Accorder l’accès aux données d’objets blob Azure avec RBAC dans le portail Azure
    • Définissez les valeurs de l’ID client, de l’ID de locataire et de la clé secrète client de l’application AAD en tant que variables d’environnement : AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET

    Utilisez les informations d’identification de jeton retournées pour authentifier le client :

        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
    )

  2. Pour utiliser un jeton de signature d’accès partagé (SAP), fournissez le jeton sous forme de chaîne. Si l’URL de votre compte inclut le jeton SAS, omettez le paramètre des informations d’identification. Vous pouvez générer un jeton SAP à partir du portail Azure sous « Signature d’accès partagé » ou utiliser l’une generate_sas() des fonctions pour créer un jeton sas pour le compte de stockage, le conteneur ou l’objet 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)

  3. Pour utiliser une clé partagée de compte de stockage (également appelée clé de compte ou clé d’accès), fournissez la clé sous forme de chaîne. Vous pouvez le trouver dans le portail Azure sous la section « Clés d’accès » ou en exécutant la commande Azure CLI suivante :

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Utilisez la clé comme paramètre d’informations d’identification pour authentifier le client :

    from azure.storage.blob import BlobServiceClient
service = BlobServiceClient(account_url="https://<my_account_name>.blob.core.windows.net", credential="<account_access_key>")

    Si vous utilisez une URL personnalisée (ce qui signifie que l’URL n’est pas dans ce format <my_account_name>.blob.core.windows.net), instanciez le client à l’aide des informations d’identification ci-dessous :

    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>"})

  4. Pour utiliser l’accès en lecture public anonyme, omettez simplement le paramètre d’informations d’identification.

Création du client à partir d’un chaîne de connexion

En fonction de votre cas d’usage et de votre méthode d’autorisation, vous préférerez peut-être initialiser un instance client avec un chaîne de connexion de stockage au lieu de fournir l’URL et les informations d’identification du compte séparément. Pour ce faire, transmettez le chaîne de connexion de stockage à la méthode de classe du from_connection_string client :

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 chaîne de connexion à votre compte de stockage se trouve dans le Portail Azure sous la section « Clés d’accès » ou en exécutant la commande CLI suivante :

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

Concepts clés

Les composants suivants composent le service Blob Azure :

  • Le compte de stockage lui-même
  • Un conteneur dans le compte de stockage
  • Objet blob dans un conteneur

La bibliothèque cliente Stockage Blobs Azure pour Python vous permet d’interagir avec chacun de ces composants via l’utilisation d’un objet client dédié.

Clients

Quatre clients différents sont fournis pour interagir avec les différents composants du service Blob :

  1. BlobServiceClient : ce client représente l’interaction avec le compte de stockage Azure lui-même et vous permet d’acquérir des instances clientes préconfigurées pour accéder aux conteneurs et aux objets blob dans. Il fournit des opérations pour récupérer et configurer les propriétés du compte, ainsi que répertorier, créer et supprimer des conteneurs dans le compte. Pour effectuer des opérations sur un conteneur ou un objet blob spécifique, récupérez un client à l’aide des get_container_client méthodes ou get_blob_client .
  2. ContainerClient : ce client représente l’interaction avec un conteneur spécifique (qui n’a pas besoin d’exister encore) et vous permet d’acquérir des instances clientes préconfigurées pour accéder aux objets blob dans. Il fournit des opérations pour créer, supprimer ou configurer un conteneur et inclut des opérations de liste, de chargement et de suppression des objets blob qu’il contient. Pour effectuer des opérations sur un objet blob spécifique dans le conteneur, récupérez un client à l’aide de la get_blob_client méthode .
  3. BlobClient : ce client représente l’interaction avec un objet blob spécifique (qui n’a pas besoin d’exister encore). Il fournit des opérations pour charger, télécharger, supprimer et créer des instantanés d’un objet blob, ainsi que des opérations spécifiques par type d’objet blob.
  4. BlobLeaseClient : ce client représente les interactions de bail avec un ContainerClient ou BlobClient. Il fournit des opérations d’acquisition, de renouvellement, de mise en production, de modification et de rupture d’un bail sur une ressource spécifiée.

Clients asynchrones

Cette bibliothèque inclut une API asynchrone complète prise en charge sur Python 3.5+. Pour l’utiliser, vous devez d’abord installer un transport asynchrone, tel que aiohttp. Pour plus d’informations, consultez la documentation azure-core .

Les clients et les informations d’identification asynchrones doivent être fermés lorsqu’ils ne sont plus nécessaires. Ces objets sont des gestionnaires de contexte asynchrones et définissent des méthodes asynchrones close .

Types d’objets blob

Une fois que vous avez initialisé un client, vous pouvez choisir parmi les différents types d’objets blob :

  • Les objets blob de blocs stockent du texte et des données binaires, jusqu’à environ 4,75 Tio. Les objets blob de blocs sont constitués de blocs de données qui peuvent être gérés individuellement
  • Les objets blob d’ajout se composent de blocs, comme les objets blob de blocs, mais sont optimisés pour les opérations d’ajout. Les objets blob d’ajout sont idéaux pour les scénarios tels que la journalisation des données à partir de machines virtuelles
  • Les objets blob de pages stockent des fichiers à accès aléatoire d’une taille maximale de 8 Tio. Les objets blob de pages stockent des fichiers de disque dur virtuel (VHD) et servent de disques pour les machines virtuelles Azure

Exemples

Les sections suivantes fournissent plusieurs extraits de code couvrant certaines des tâches blob de stockage les plus courantes, notamment :

Notez qu’un conteneur doit être créé avant de charger ou de télécharger un objet blob.

Créez un conteneur.

Créez un conteneur à partir duquel vous pouvez charger ou télécharger des objets blob.

from azure.storage.blob import ContainerClient

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

container_client.create_container()

Utiliser le client asynchrone pour charger un objet 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()

Chargement d’un objet blob

Charger un objet blob dans votre conteneur

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)

Utiliser le client asynchrone pour charger un objet 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)

Téléchargement d’un objet blob

Télécharger un objet blob à partir de votre conteneur

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)

Télécharger un objet blob de manière asynchrone

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)

Énumération d’objets blob

Répertorier les objets blob dans votre conteneur

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

Répertorier les objets blob de manière asynchrone

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)

Configuration facultative

Facultatif mot clé arguments qui peuvent être transmis au niveau du client et par opération.

Configuration de la stratégie de nouvelle tentative

Utilisez les arguments mot clé suivants lors de l’instanciation d’un client pour configurer la stratégie de nouvelle tentative :

  • retry_total (int) : nombre total de nouvelles tentatives à autoriser. Est prioritaire sur d’autres nombres. Transmettez retry_total=0 si vous ne souhaitez pas réessayer sur les demandes. La valeur par défaut est 10.
  • retry_connect (int) : nombre d’erreurs liées à la connexion à retenter. La valeur par défaut est 3.
  • retry_read (int) : nombre de nouvelles tentatives en cas d’erreurs de lecture. La valeur par défaut est 3.
  • retry_status (int) : nombre de nouvelles tentatives sur des codes de status incorrects. La valeur par défaut est 3.
  • retry_to_secondary (bool) : indique si la demande doit être retentée au niveau secondaire, si possible. Cela ne doit être activé que si les comptes RA-GRS sont utilisés et que les données potentiellement obsolètes peuvent être gérées. La valeur par défaut est False.

Configuration du chiffrement

Utilisez les arguments mot clé suivants lors de l’instanciation d’un client pour configurer le chiffrement :

  • require_encryption (bool) : s’il est défini sur True, applique que les objets sont chiffrés et les déchiffre.
  • encryption_version (str) : spécifie la version de chiffrement à utiliser. Les options actuelles sont '2.0' ou '1.0' et la valeur par défaut est '1.0'. La version 1.0 est déconseillée et il est vivement recommandé d’utiliser la version 2.0.
  • key_encryption_key (objet) : clé-chiffrement-clé fournie par l’utilisateur. Le instance doit implémenter les méthodes suivantes :
    • wrap_key(key)--encapsule la clé spécifiée à l’aide d’un algorithme de choix de l’utilisateur.
    • get_key_wrap_algorithm()--retourne l’algorithme utilisé pour encapsuler la clé symétrique spécifiée.
    • get_kid()--retourne un ID de clé de chaîne pour cette clé-chiffrement-clé.
  • key_resolver_function (appelable) : programme de résolution de clés fourni par l’utilisateur. Utilise la chaîne kid pour renvoyer une clé de chiffrement de clé implémentant l’interface définie ci-dessus.

Autre configuration client/ par opération

D’autres configurations facultatives mot clé arguments qui peuvent être spécifiés sur le client ou par opération.

Arguments de mot clé client :

  • connection_timeout (int) : nombre de secondes pendant lesquelles le client attend pour établir une connexion au serveur. La valeur par défaut est de 20 secondes.
  • read_timeout (int) : nombre de secondes pendant lesquelles le client attend une réponse du serveur entre les opérations de lecture consécutives. Il s’agit d’un délai d’attente au niveau du socket qui n’est pas affecté par la taille globale des données. Les délais de lecture côté client sont automatiquement retentés. La valeur par défaut est de 60 secondes.
  • transport (Any) : transport fourni par l’utilisateur pour envoyer la requête HTTP.

Arguments de mot clé par opération :

  • raw_response_hook (appelable) : le rappel donné utilise la réponse retournée par le service.
  • raw_request_hook (appelable) : le rappel donné utilise la requête avant d’être envoyé au service.
  • client_request_id (str) : identification facultative spécifiée par l’utilisateur de la demande.
  • user_agent (str) : ajoute la valeur personnalisée à l’en-tête user-agent à envoyer avec la demande.
  • logging_enable (bool) : active la journalisation au niveau DEBUG. Valeur par défaut False. Peut également être transmis au niveau du client pour l’activer pour toutes les demandes.
  • logging_body (bool) : active la journalisation du corps de la requête et de la réponse. Valeur par défaut False. Peut également être transmis au niveau du client pour l’activer pour toutes les demandes.
  • en-têtes (dict) : passez des en-têtes personnalisés en tant que paires de clés et de valeurs. Par exemple, headers={'CustomValue': value}

Dépannage

Général

Les clients d’objets blob de stockage déclenchent des exceptions définies dans Azure Core.

Cette liste peut être utilisée à des fins de référence pour intercepter les exceptions levées. Pour obtenir le code d’erreur spécifique de l’exception, utilisez l’attribut error_code , exception.error_codec’est-à-dire .

Journalisation

Cette bibliothèque utilise la bibliothèque de journalisation standard pour la journalisation. Les informations de base sur les sessions HTTP (URL, en-têtes, etc.) sont enregistrées au niveau INFO.

La journalisation détaillée au niveau DEBUG, y compris les corps de requête/réponse et les en-têtes non expurgés, peut être activée sur un client avec l’argument logging_enable :

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)

De la même façon, logging_enable peut activer la journalisation détaillée pour une seule opération, même quand elle n’est pas activée pour le client :

service_client.get_service_stats(logging_enable=True)

Étapes suivantes

Autres exemples de code

Bien démarrer avec nos exemples d’objets blob.

Plusieurs exemples de KIT de développement logiciel (SDK) Python d’objets blob de stockage sont disponibles dans le dépôt GitHub du SDK. Ces exemples fournissent un exemple de code pour d’autres scénarios couramment rencontrés lors de l’utilisation d’objets blob de stockage :

  • blob_samples_container_access_policy.py (version asynchrone) - Exemples de définition de stratégies d’accès :

    • Configurer la stratégie d’accès pour le conteneur

  • blob_samples_hello_world.py (version asynchrone) - Exemples de tâches blob de stockage courantes :

    • Configurer un conteneur
    • Créer un objet blob de bloc, de page ou d’ajout
    • Charger des objets blob
    • Télécharger des objets blob
    • Supprimer les objets blob

  • blob_samples_authentication.py (version asynchrone) : exemples d’authentification et de création du client :

    • À partir d’un chaîne de connexion
    • À partir d’une clé d’accès partagé
    • À partir d’un jeton de signature d’accès partagé
    • À partir d’Active Directory

  • blob_samples_service.py (version asynchrone) : exemples d’interaction avec le service blob :

    • Obtenir les informations de compte
    • Obtenir et définir des propriétés de service
    • Obtenir des statistiques de service
    • Créer, répertorier et supprimer des conteneurs
    • Obtenir le client d’objet blob ou de conteneur

  • blob_samples_containers.py (version asynchrone) - Exemples d’interaction avec des conteneurs :

    • Créer un conteneur et supprimer des conteneurs
    • Définir des métadonnées sur des conteneurs
    • Obtenir les propriétés du conteneur
    • Acquérir un bail sur le conteneur
    • Définir une stratégie d’accès sur un conteneur
    • Charger, répertorier, supprimer des objets blob dans le conteneur
    • Obtenir le client d’objets blob pour interagir avec un objet blob spécifique

  • blob_samples_common.py (version asynchrone) : exemples communs à tous les types d’objets blob :

    • Créer un instantané
    • Supprimer un instantané blob
    • Suppression réversible d’un objet blob
    • Annuler la suppression d’un objet blob
    • Acquérir un bail sur un objet blob
    • Copier un objet blob à partir d’une URL

  • blob_samples_directory_interface.py : exemples d’interfaçage avec le stockage Blob comme s’il s’agissait d’un répertoire sur un système de fichiers :

    • Copier (charger ou télécharger) un seul fichier ou répertoire
    • Répertorier les fichiers ou répertoires à un seul niveau ou de manière récursive
    • Supprimer un fichier unique ou supprimer un répertoire de manière récursive

Documentation complémentaire

Pour obtenir une documentation plus complète sur le stockage Blob Azure, consultez la documentation stockage Blob Azure sur docs.microsoft.com.

Contribution

Ce projet accepte les contributions et les suggestions. La plupart des contributions vous demandent d’accepter un contrat de licence de contribution (CLA) déclarant que vous avez le droit de nous accorder, et que vous nous accordez réellement, les droits d’utilisation de votre contribution. Pour plus d’informations, visitez https://cla.microsoft.com.

Quand vous envoyez une demande de tirage (pull request), un bot CLA détermine automatiquement si vous devez fournir un contrat CLA et agrémenter la demande de tirage de façon appropriée (par exemple, avec une étiquette ou un commentaire). Suivez simplement les instructions fournies par le bot. Vous ne devez effectuer cette opération qu’une seule fois sur tous les dépôts utilisant notre contrat CLA.

Ce projet a adopté le Code de conduite Open Source de Microsoft. Pour plus d’informations, consultez les Questions fréquentes (FAQ) sur le code de conduite ou envoyez vos questions ou vos commentaires à opencode@microsoft.com.