Bibliothèque cliente de partage de fichiers de stockage Azure pour Python - version 12.15.0

  • Article

Le stockage Azure File Share offre des partages de fichiers entièrement managés dans le cloud qui sont accessibles via le protocole SMB (Server Message Block) standard du secteur. Les partages de fichiers Azure peuvent être montés simultanément sur des déploiements cloud ou locaux de Windows, Linux et macOS. En outre, les partages de fichiers Azure peuvent être mis en cache sur les serveurs Windows avec Azure File Sync pour un accès rapide à proximité de l’endroit où les données sont utilisées.

Les partages de fichiers Azure peuvent être utilisés pour :

  • Remplacer ou compléter les serveurs de fichiers locaux
  • Applications « Lift-and-shift »
  • Simplifier le développement cloud avec les paramètres d’application partagés, le partage de diagnostic et les outils Dev/Test/Debug

| 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 de partage de fichiers de stockage Azure pour Python avec pip :

pip install azure-storage-file-share

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 de partage de fichiers de stockage Azure pour Python vous permet d’interagir avec quatre types de ressources : le compte de stockage lui-même, les partages de fichiers, les répertoires et les fichiers. 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 service de fichiers du compte de stockage et d’informations d’identification qui vous permettent d’accéder au compte de stockage :

from azure.storage.fileshare import ShareServiceClient

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

Recherche de l’URL du compte

Vous trouverez l’URL du service de fichiers du compte de stockage à l’aide du portail Azure, de Azure PowerShell ou d’Azure CLI :

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

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 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 partage ou le fichier :

    from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, 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)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

  2. 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.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")

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.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.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 De partage de fichiers Azure :

  • Le compte de stockage lui-même
  • Un partage de fichiers dans le compte de stockage
  • Hiérarchie facultative des répertoires au sein du partage de fichiers
  • Un fichier dans le partage de fichiers, qui peut avoir jusqu’à 1 Tio de taille

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

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 .

Clients

Quatre clients différents sont fournis pour interagir avec les différents composants du service de partage de fichiers :

  1. ShareServiceClient : 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 partages de fichiers dans. Il fournit des opérations pour récupérer et configurer les propriétés du service, ainsi que pour répertorier, créer et supprimer des partages dans le compte. Pour effectuer des opérations sur un partage spécifique, récupérez un client à l’aide de la get_share_client méthode .
  2. ShareClient : ce client représente l’interaction avec un partage de fichiers spécifique (qui n’a pas besoin d’exister) et vous permet d’acquérir des instances clientes préconfigurées pour accéder aux répertoires et aux fichiers dans. Il fournit des opérations de création, de suppression, de configuration ou de création d’instantanés d’un partage et inclut des opérations permettant de créer et d’énumérer le contenu des répertoires qu’il contient. Pour effectuer des opérations sur un répertoire ou un fichier spécifique, récupérez un client à l’aide des get_directory_client méthodes ou get_file_client .
  3. ShareDirectoryClient : ce client représente l’interaction avec un répertoire spécifique (qui n’a pas encore besoin d’exister). Il fournit des opérations pour créer, supprimer ou énumérer le contenu d’un sous-répertoire immédiat ou imbriqué, et inclut des opérations de création et de suppression de fichiers dans celui-ci. Pour les opérations relatives à un sous-répertoire ou à un fichier spécifique, un client pour cette entité peut également être récupéré à l’aide des get_subdirectory_client fonctions et get_file_client .
  4. ShareFileClient : ce client représente l’interaction avec un fichier spécifique (qui n’a pas besoin d’exister). Il fournit des opérations de chargement, de téléchargement, de création, de suppression et de copie d’un fichier.

Pour plus d’informations sur les restrictions de nommage des chemins d’accès, consultez Nommage et référencement des partages, répertoires, fichiers et métadonnées.

Exemples

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

Création d'un partage de fichiers

Créer un partage de fichiers pour stocker vos fichiers

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

Utiliser le client asynchrone pour créer un partage de fichiers

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

Téléchargement d’un fichier

Charger un fichier dans le partage

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

Charger un fichier de manière asynchrone

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

Téléchargement d’un fichier

Télécharger un fichier à partir du partage

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

Télécharger un fichier de manière asynchrone

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

Liste du contenu d’un répertoire

Répertorier tous les répertoires et fichiers sous un répertoire parent

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

Répertorier le contenu d’un répertoire de manière asynchrone

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

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.

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 de fichiers 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.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
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 = ShareServiceClient.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_properties(logging_enable=True)

Étapes suivantes

Autres exemples de code

Prise en main de nos exemples de partage de fichiers.

Plusieurs exemples de sdk Python de partage de fichiers de stockage sont disponibles dans le référentiel GitHub du SDK. Ces exemples fournissent un exemple de code pour d’autres scénarios couramment rencontrés lors de l’utilisation du partage de fichiers de stockage :

  • file_samples_hello_world.py (version asynchrone) - Exemples trouvés dans cet article :

    • Création de client
    • Créer un partage de fichiers
    • Charger un fichier

  • file_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é

  • file_samples_service.py (version asynchrone) - Exemples d’interaction avec le service de fichiers :

    • Obtenir et définir des propriétés de service
    • Créer, répertorier et supprimer des partages
    • Obtenir un client de partage

  • file_samples_share.py (version asynchrone) - Exemples d’interaction avec les partages de fichiers :

    • Créer un instantané de partage
    • Définir le quota de partage et les métadonnées
    • Répertorier les répertoires et les fichiers
    • Obtenir le client de répertoire ou de fichier pour interagir avec une entité spécifique

  • file_samples_directory.py (version asynchrone) - Exemples d’interaction avec les répertoires :

    • Créer un répertoire et ajouter des fichiers
    • Créer et supprimer des sous-répertoires
    • Obtenir le client de sous-répertoire

  • file_samples_client.py (version asynchrone) - Exemples d’interaction avec des fichiers :

    • Créer, charger, télécharger et supprimer des fichiers
    • Copier un fichier à partir d’une URL

Documentation complémentaire

Pour obtenir une documentation plus complète sur le stockage Azure File Share, consultez la documentation sur le stockage Azure File Share 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.