Bibliothèque cliente du service Azure DataLake pour Python - version 12.14.0

  • Article

Vue d’ensemble

Ce package de préversion pour Python inclut la prise en charge de l’API spécifique à ADLS Gen2 mise à disposition dans le Kit de développement logiciel (SDK) Stockage. notamment :

  1. Nouvelles opérations au niveau du répertoire (Créer, Renommer, Supprimer) pour le compte de stockage HNS (Espace de noms hiérarchique). Pour les comptes HNS activés, les opérations de renommage/déplacement sont atomiques.
  2. Opérations liées aux autorisations (Get/Set ACL) pour les comptes HNS (Espace de noms hiérarchiques activés).

| 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 Stockage Azure DataLake pour Python avec pip :

pip install azure-storage-file-datalake --pre

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

# Install the extension 'Storage-Preview'
az extension add --name storage-preview

# Create the storage account
az storage account create --name my-storage-account-name --resource-group my-resource-group --sku Standard_LRS --kind StorageV2 --hierarchical-namespace true

Authentifier le client

L’interaction avec DataLake Storage commence par un instance de la classe DataLakeServiceClient. Vous avez besoin d’un compte de stockage existant, de son URL et d’informations d’identification pour instancier l’objet client.

Récupérer les informations d’identification

Pour authentifier le client, vous disposez de quelques options :

  1. Utiliser une chaîne de jeton SAS
  2. Utiliser une clé d’accès partagé de compte
  3. Utiliser des informations d’identification de jeton à partir d’azure.identity

Vous pouvez également vous authentifier auprès d’un chaîne de connexion de stockage à l’aide de la from_connection_string méthode . Voir l’exemple : Création de client avec un chaîne de connexion.

Vous pouvez omettre les informations d’identification si l’URL de votre compte a déjà un jeton SAP.

Créer un client

Une fois l’URL et les informations d’identification de votre compte prêtes, vous pouvez créer le DataLakeServiceClient :

from azure.storage.filedatalake import DataLakeServiceClient

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

Concepts clés

Le stockage DataLake offre quatre types de ressources :

  • Le compte de stockage
  • Un système de fichiers dans le compte de stockage
  • Répertoire sous le système de fichiers
  • Un fichier dans un système de fichiers ou sous le répertoire

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

Le Kit de développement logiciel (SDK) DataLake Storage fournit quatre clients différents pour interagir avec le service DataLake :

  1. DataLakeServiceClient : ce client interagit avec le service DataLake au niveau du compte. 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 systèmes de fichiers au sein du compte. Pour les opérations relatives à un système de fichiers, un répertoire ou un fichier spécifique, les clients de ces entités peuvent également être récupérés à l’aide des get_file_clientfonctions ou get_directory_clientget_file_system_client .
  2. FileSystemClient : ce client représente l’interaction avec un système de fichiers spécifique, même si ce système de fichiers n’existe pas encore. Il fournit des opérations pour créer, supprimer ou configurer des systèmes de fichiers et inclut des opérations de liste des chemins d’accès sous le système de fichiers, de chargement et de suppression de fichier ou de répertoire dans le système de fichiers. Pour les opérations relatives à un fichier spécifique, le client peut également être récupéré à l’aide de la get_file_client fonction . Pour les opérations relatives à un répertoire spécifique, le client peut être récupéré à l’aide de la get_directory_client fonction .
  3. DataLakeDirectoryClient : ce client représente l’interaction avec un répertoire spécifique, même si ce répertoire n’existe pas encore. Il fournit des opérations de création, de suppression, de renommage, d’obtention de propriétés et d’opérations de définition des propriétés.
  4. DataLakeFileClient : ce client représente l’interaction avec un fichier spécifique, même si ce fichier n’existe pas encore. Il fournit des opérations de fichier pour ajouter des données, vider des données, supprimer, créer et lire un fichier.
  5. DataLakeLeaseClient : ce client représente les interactions de bail avec un FileSystemClient, DataLakeDirectoryClient ou DataLakeFileClient. Il fournit des opérations d’acquisition, de renouvellement, de libération, de modification et d’interruption des baux sur les ressources.

Exemples

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

Création de client avec un chaîne de connexion

Créez dataLakeServiceClient à l’aide de la chaîne de connexion à votre compte Stockage Azure.

from azure.storage.filedatalake import DataLakeServiceClient

service = DataLakeServiceClient.from_connection_string(conn_str="my_connection_string")

Téléchargement d’un fichier

Chargez un fichier dans votre système de fichiers.

from azure.storage.filedatalake import DataLakeFileClient

data = b"abc"
file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")
file.create_file ()
file.append_data(data, offset=0, length=len(data))
file.flush_data(len(data))

Téléchargement d’un fichier

Téléchargez un fichier à partir de votre système de fichiers.

from azure.storage.filedatalake import DataLakeFileClient

file = DataLakeFileClient.from_connection_string("my_connection_string",
                                                 file_system_name="myfilesystem", file_path="myfile")

with open("./BlockDestination.txt", "wb") as my_file:
    download = file.download_file()
    download.readinto(my_file)

Énumération des chemins d’accès

Répertoriez les chemins d’accès dans votre système de fichiers.

from azure.storage.filedatalake import FileSystemClient

file_system = FileSystemClient.from_connection_string("my_connection_string", file_system_name="myfilesystem")

paths = file_system.get_paths()
for path in paths:
    print(path.name + '\n')

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 DataLake Storage 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.filedatalake import DataLakeServiceClient

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

Étapes suivantes

Autres exemples de code

Bien démarrer avec nos exemples Azure DataLake.

Plusieurs exemples de kit de développement logiciel (SDK) Python DataLake Storage 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 de DataLake Storage :

  • datalake_samples_access_control.py - Exemples de tâches de stockage DataLake courantes :

    • Configurer un système de fichiers
    • Créer un répertoire
    • Définir/Obtenir le contrôle d’accès pour le répertoire
    • Créer des fichiers sous le répertoire
    • Définir/obtenir le contrôle d’accès pour chaque fichier
    • Supprimer un système de fichiers

  • datalake_samples_upload_download.py - Exemples de tâches de stockage DataLake courantes :

    • Configurer un système de fichiers
    • Créer un fichier
    • Ajouter des données au fichier
    • Vider les données dans le fichier
    • Télécharger les données chargées
    • Supprimer un système de fichiers

Documentation complémentaire

Table pour le mappage des API ADLS Gen1 vers ADLS Gen2 Pour obtenir une documentation REST plus complète sur Data Lake Storage Gen2, consultez la documentation Data Lake Storage Gen2 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.