Condividi tramite

Libreria client del servizio Azure DataLake per Python - versione 12.14.0

  • Articolo

Panoramica

Questo pacchetto di anteprima per Python include il supporto api specifico di ADLS Gen2 reso disponibile in Storage SDK. ad esempio:

  1. Nuove operazioni a livello di directory (Crea, Rinomina, Elimina) per l'account di archiviazione abilitato per lo spazio dei nomi gerarchico (HNS). Per gli account abilitati per HNS, le operazioni di rinomina/spostamento sono atomiche.
  2. Operazioni correlate alle autorizzazioni (Get/Set ACL) per gli account dello spazio dei nomi gerarchici abilitati (HNS).

Codice | sorgentePacchetto (PyPi) | Pacchetto (Conda) | Documentazione di | riferimento sulle APIDocumentazione | del prodottoCampioni

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di Archiviazione di Azure DataLake per Python con pip:

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

Creare un account di archiviazione

Se si vuole creare un nuovo account di archiviazione, è possibile usare il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure:

# 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

Autenticare il client

L'interazione con DataLake Storage inizia con un'istanza della classe DataLakeServiceClient. È necessario un account di archiviazione esistente, il relativo URL e una credenziale per creare un'istanza dell'oggetto client.

Ottenere le credenziali

Per autenticare il client sono disponibili alcune opzioni:

  1. Usare una stringa di token di firma di accesso condiviso
  2. Usare una chiave di accesso condiviso dell'account
  3. Usare una credenziale del token da azure.identity

In alternativa, è possibile eseguire l'autenticazione con un stringa di connessione di archiviazione usando il from_connection_string metodo . Vedere l'esempio: Creazione client con un stringa di connessione.

È possibile omettere le credenziali se l'URL dell'account ha già un token di firma di accesso condiviso.

Creare il client

Dopo aver pronto l'URL e le credenziali dell'account, è possibile creare DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Concetti chiave

L'archiviazione DataLake offre quattro tipi di risorse:

  • L'account di archiviazione
  • File system nell'account di archiviazione
  • Directory nel file system
  • File in un file system o nella directory

Client asincroni

Questa libreria include un'API asincrona completa supportata in Python 3.5+. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di azure-core .

I client e le credenziali asincroni devono essere chiusi quando non sono più necessari. Questi oggetti sono gestioni contesto asincrone e definiscono metodi asincroni close .

Client

DataLake Storage SDK offre quattro client diversi per interagire con il servizio DataLake:

  1. DataLakeServiceClient : questo client interagisce con il servizio DataLake a livello di account. Fornisce operazioni per recuperare e configurare le proprietà dell'account e l'elenco, creare ed eliminare file system all'interno dell'account. Per le operazioni relative a un file system, una directory o un file specifico, i client per tali entità possono essere recuperati anche usando le get_file_clientget_directory_client funzioni o get_file_system_client .
  2. FileSystemClient : questo client rappresenta l'interazione con un file system specifico, anche se tale file system non esiste ancora. Fornisce operazioni per creare, eliminare o configurare file system e include operazioni per elencare i percorsi nel file system, caricare ed eliminare file o directory nel file system. Per le operazioni relative a un file specifico, è anche possibile recuperare il client usando la get_file_client funzione. Per le operazioni relative a una directory specifica, è possibile recuperare il client usando la get_directory_client funzione.
  3. DataLakeDirectoryClient : questo client rappresenta l'interazione con una directory specifica, anche se tale directory non esiste ancora. Fornisce operazioni di directory create, delete, rinomina, recupera proprietà e imposta le operazioni delle proprietà.
  4. DataLakeFileClient : questo client rappresenta l'interazione con un file specifico, anche se tale file non esiste ancora. Fornisce operazioni di file per aggiungere dati, scaricare dati, eliminare, creare e leggere file.
  5. DataLakeLeaseClient : questo client rappresenta le interazioni di lease con un FileSystemClient, DataLakeDirectoryClient o DataLakeFileClient. Fornisce operazioni per acquisire, rinnovare, rilasciare, modificare e interrompere i lease sulle risorse.

Esempio

Le sezioni seguenti forniscono diversi frammenti di codice che coprono alcune delle attività di Storage DataLake più comuni, tra cui:

Creazione client con un stringa di connessione

Creare DataLakeServiceClient usando l'stringa di connessione all'account di archiviazione di Azure.

from azure.storage.filedatalake import DataLakeServiceClient

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

Caricamento di un file

Caricare un file nel file system.

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

Download di un file

Scaricare un file dal file system.

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)

Enumerazione dei percorsi

Elencare i percorsi nel file system.

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

Configurazione facoltativa

Argomenti delle parole chiave facoltativi che possono essere passati al client e a livello di operazione.

Configurazione dei criteri di ripetizione dei tentativi

Usare gli argomenti delle parole chiave seguenti quando si crea un'istanza di un client per configurare i criteri di ripetizione dei tentativi:

  • retry_total (int): numero totale di tentativi da consentire. Ha la precedenza su altri conteggi. retry_total=0 Passare se non si vuole ripetere i tentativi sulle richieste. Il valore predefinito è 10.
  • retry_connect (int): numero di errori correlati alla connessione da ripetere. Il valore predefinito è 3.
  • retry_read (int): numero di tentativi di ripetizione degli errori di lettura. Il valore predefinito è 3.
  • retry_status (int): quante volte ripetere i tentativi sui codici di stato non valido. Il valore predefinito è 3.
  • retry_to_secondary (bool): se la richiesta deve essere riprovata a secondaria, se in grado. Questa opzione deve essere abilitata solo per gli account RA-GRS e i dati potenzialmente non aggiornati possono essere gestiti. Il valore predefinito è False.

Altro client/configurazione per operazione

Altri argomenti delle parole chiave di configurazione facoltativi che possono essere specificati nel client o per operazione.

Argomenti delle parole chiave client:

  • connection_timeout (int): il numero di secondi che il client attenderà di stabilire una connessione al server. Il valore predefinito è 20 secondi.
  • read_timeout (int): il numero di secondi che il client attenderà, tra operazioni di lettura consecutive, per una risposta dal server. Si tratta di un timeout a livello di socket e non è interessato dalle dimensioni complessive dei dati. I timeout di lettura lato client verranno ritriti automaticamente. Il valore predefinito è 60 secondi.
  • transport (Any): trasporto fornito dall'utente per inviare la richiesta HTTP.

Argomenti delle parole chiave per operazione:

  • raw_response_hook (chiamabile): il callback specificato usa la risposta restituita dal servizio.
  • raw_request_hook (chiamabile): il callback specificato usa la richiesta prima di essere inviata al servizio.
  • client_request_id (str): utente facoltativo specificato per l'identificazione della richiesta.
  • user_agent (str): aggiunge il valore personalizzato all'intestazione dell'agente utente da inviare con la richiesta.
  • logging_enable (bool): abilita la registrazione a livello DI DEBUG. Il valore predefinito è False. Può essere passato anche a livello client per abilitarlo per tutte le richieste.
  • logging_body (bool): abilita la registrazione del corpo della richiesta e della risposta. Il valore predefinito è False. Può essere passato anche a livello client per abilitarlo per tutte le richieste.
  • intestazioni (dict): passare intestazioni personalizzate come chiave, coppie di valori. Ad esempio headers={'CustomValue': value}

Risoluzione dei problemi

Generale

I client di Archiviazione DataLake generano eccezioni definite in Azure Core.

Questo elenco può essere usato per riferimento per rilevare le eccezioni generate. Per ottenere il codice di errore specifico dell'eccezione, usare l'attributo error_code , ad esempio exception.error_code.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata del livello DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non attendibili, può essere abilitata in un client con l'argomento 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

service_client.list_file_systems(logging_enable=True)

Passaggi successivi

Altro codice di esempio

Introduzione agli esempi di Azure DataLake.

Diversi esempi di Python SDK di Archiviazione DataLake sono disponibili nel repository GitHub dell'SDK. Questi esempi forniscono codice di esempio per scenari aggiuntivi comunemente rilevati durante l'uso di DataLake Storage:

  • datalake_samples_access_control.py - Esempi per le attività comuni di archiviazione di DataLake:

    • Configurare un file system
    • Creare una directory
    • Impostare/Ottenere il controllo di accesso per la directory
    • Creare file nella directory
    • Impostare/Ottenere il controllo di accesso per ogni file
    • Eliminare il file system

  • datalake_samples_upload_download.py - Esempi per le attività comuni di archiviazione di DataLake:

    • Configurare un file system
    • Crea file
    • Aggiungere dati al file
    • Scaricare i dati nel file
    • Scaricare i dati caricati
    • Eliminare il file system

Documentazione aggiuntiva

Tabella per ADLS Gen1 a MAPPING API ADLS Gen2 Per una documentazione REST più completa su Data Lake Storage Gen2, vedere la documentazione di Data Lake Storage Gen2 su docs.microsoft.com.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.