Share via

Azure DataLake-tjänstklientbibliotek för Python – version 12.14.0

  • Artikel

Översikt

Det här förhandsversionspaketet för Python innehåller ADLS Gen2-specifikt API-stöd som görs tillgängligt i Storage SDK. Du måste bland annat:

  1. Nya åtgärder på katalognivå (Skapa, Byt namn, Ta bort) för hierarkiskt HNS-lagringskonto (Hierarkiskt namnområde aktiverat). För HNS-aktiverade konton är åtgärderna för att byta namn/flytta atomiska.
  2. Behörighetsrelaterade åtgärder (Hämta/ange ACL:er) för hierarkiska namnområdesaktiverade konton (HNS).

Källkod | Paket (PyPi) | Paket (Conda) | API-referensdokumentation | Produktdokumentation | Prover

Komma igång

Förutsättningar

Installera paketet

Installera Azure DataLake Storage-klientbiblioteket för Python med pip:

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

Skapa ett lagringskonto

Om du vill skapa ett nytt lagringskonto kan du använda Azure Portal, Azure PowerShell eller 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

Autentisera klienten

Interaktion med DataLake Storage börjar med en instans av klassen DataLakeServiceClient. Du behöver ett befintligt lagringskonto, dess URL och en autentiseringsuppgift för att instansiera klientobjektet.

Hämta autentiseringsuppgifter

För att autentisera klienten har du några alternativ:

  1. Använda en SAS-tokensträng
  2. Använda en nyckel för delad åtkomst för ett konto
  3. Använda en tokenautentiseringsuppgift från azure.identity

Du kan också autentisera med en anslutningssträng med hjälp av from_connection_string metoden . Se exempel: Skapa klient med en anslutningssträng.

Du kan utelämna autentiseringsuppgifterna om din konto-URL redan har en SAS-token.

Skapa en klient

När du har din konto-URL och dina autentiseringsuppgifter klara kan du skapa DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Viktiga begrepp

DataLake Storage erbjuder fyra typer av resurser:

  • Lagringskontot
  • Ett filsystem i lagringskontot
  • En katalog under filsystemet
  • En fil i ett filsystem eller under katalog

Async-klienter

Det här biblioteket innehåller ett fullständigt asynkront API som stöds i Python 3.5+. Om du vill använda den måste du först installera en asynkron transport, till exempel aiohttp. Mer information finns i dokumentationen om azure-core .

Asynkrona klienter och autentiseringsuppgifter bör stängas när de inte längre behövs. Dessa objekt är asynkrona kontexthanterare och definierar asynkrona close metoder.

Klienter

DataLake Storage SDK tillhandahåller fyra olika klienter för att interagera med DataLake-tjänsten:

  1. DataLakeServiceClient – den här klienten interagerar med DataLake-tjänsten på kontonivå. Den tillhandahåller åtgärder för att hämta och konfigurera kontoegenskaper samt lista, skapa och ta bort filsystem i kontot. För åtgärder som rör ett specifikt filsystem, katalog eller fil kan klienter för dessa entiteter också hämtas med hjälp av get_file_clientfunktionerna eller get_directory_clientget_file_system_client .
  2. FileSystemClient – den här klienten representerar interaktion med ett specifikt filsystem, även om det filsystemet inte finns ännu. Den tillhandahåller åtgärder för att skapa, ta bort eller konfigurera filsystem och innehåller åtgärder för att lista sökvägar under filsystem, ladda upp och ta bort fil eller katalog i filsystemet. För åtgärder som rör en specifik fil kan klienten också hämtas med hjälp av get_file_client funktionen . För åtgärder som rör en specifik katalog kan klienten hämtas med hjälp av get_directory_client funktionen .
  3. DataLakeDirectoryClient – den här klienten representerar interaktion med en specifik katalog, även om katalogen inte finns ännu. Den tillhandahåller katalogåtgärder för att skapa, ta bort, byta namn på, hämta egenskaper och ange egenskaper.
  4. DataLakeFileClient – den här klienten representerar interaktion med en specifik fil, även om filen inte finns ännu. Den tillhandahåller filåtgärder för att lägga till data, rensa data, ta bort, skapa och läsa filen.
  5. DataLakeLeaseClient – den här klienten representerar låneinteraktioner med en FileSystemClient, DataLakeDirectoryClient eller DataLakeFileClient. Den tillhandahåller åtgärder för att hämta, förnya, släppa, ändra och bryta lån på resurserna.

Exempel

Följande avsnitt innehåller flera kodfragment som täcker några av de vanligaste Storage DataLake-uppgifterna, inklusive:

Klientskapande med en anslutningssträng

Skapa DataLakeServiceClient med hjälp av anslutningssträng till ditt Azure Storage-konto.

from azure.storage.filedatalake import DataLakeServiceClient

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

Ladda upp en fil

Ladda upp en fil till filsystemet.

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

Ladda ned en fil

Ladda ned en fil från filsystemet.

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)

Räkna upp sökvägar

Lista sökvägarna i filsystemet.

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

Valfri konfiguration

Valfria nyckelordsargument som kan skickas på klient- och åtgärdsnivå.

Konfiguration av återförsöksprincip

Använd följande nyckelordsargument när du instansierar en klient för att konfigurera återförsöksprincipen:

  • retry_total (int): Totalt antal återförsök att tillåta. Har företräde framför andra antal. Skicka in retry_total=0 om du inte vill försöka igen på begäranden. Standardvärdet är 10.
  • retry_connect (int): Hur många anslutningsrelaterade fel som ska försöka igen. Standardvärdet är 3.
  • retry_read (int): Hur många gånger läsfel ska försöka igen. Standardvärdet är 3.
  • retry_status (int): Hur många gånger du försöker igen med felaktiga statuskoder. Standardvärdet är 3.
  • retry_to_secondary (bool): Om begäran ska prövas på nytt till sekundär, om det går. Detta bör endast aktiveras för RA-GRS-konton som används och potentiellt inaktuella data kan hanteras. Standardvärdet är False.

Annan klient/per åtgärd-konfiguration

Andra valfria nyckelordsargument för konfiguration som kan anges för klienten eller per åtgärd.

Argument för klientnyckelord:

  • connection_timeout (int): Antalet sekunder som klienten väntar på att upprätta en anslutning till servern. Standardvärdet är 20 sekunder.
  • read_timeout (int): Antalet sekunder som klienten väntar, mellan efterföljande läsåtgärder, på ett svar från servern. Det här är en tidsgräns på socketnivå och påverkas inte av den totala datastorleken. Tidsgränser för läsning på klientsidan görs automatiskt på nytt. Standardvärdet är 60 sekunder.
  • transport (alla): Transport som tillhandahålls av användaren för att skicka HTTP-begäran.

Nyckelordsargument per åtgärd:

  • raw_response_hook (anropsbar): Det angivna återanropet använder svaret som returneras från tjänsten.
  • raw_request_hook (anropsbar): Det angivna återanropet använder begäran innan den skickas till tjänsten.
  • client_request_id (str): Valfri användare har angett identifiering av begäran.
  • user_agent (str): Lägger till det anpassade värdet i user-agent-huvudet som ska skickas med begäran.
  • logging_enable (bool): Aktiverar loggning på felsökningsnivå. Standardvärdet är False. Kan också skickas in på klientnivå för att aktivera det för alla begäranden.
  • logging_body (bool): Aktiverar loggning av begärande- och svarstexten. Standardvärdet är False. Kan också skickas in på klientnivå för att aktivera det för alla begäranden.
  • headers (dict): Skicka in anpassade rubriker som nyckel, värdepar. E.g. headers={'CustomValue': value}

Felsökning

Allmänt

DataLake Storage-klienter genererar undantag som definierats i Azure Core.

Den här listan kan användas som referens för att fånga undantag som genereras. Om du vill hämta den specifika felkoden för undantaget använder du error_code attributet , t.ex exception.error_code. .

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning. Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO-nivå.

Detaljerad loggning på FELSÖKNINGsnivå, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på en klient med logging_enable argumentet :

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)

logging_enable På samma sätt kan aktivera detaljerad loggning för en enda åtgärd, även om den inte är aktiverad för klienten:

service_client.list_file_systems(logging_enable=True)

Nästa steg

Mer exempelkod

Kom igång med våra Azure DataLake-exempel.

Flera DataLake Storage Python SDK-exempel är tillgängliga för dig på SDK:s GitHub-lagringsplats. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med DataLake Storage:

  • datalake_samples_access_control.py – Exempel på vanliga DataLake Storage-uppgifter:

    • Konfigurera ett filsystem
    • Skapa en katalog
    • Ange/hämta åtkomstkontroll för katalogen
    • Skapa filer under katalogen
    • Ange/hämta åtkomstkontroll för varje fil
    • Ta bort filsystem

  • datalake_samples_upload_download.py – Exempel på vanliga DataLake Storage-uppgifter:

    • Konfigurera ett filsystem
    • Skapa fil
    • Lägga till data i filen
    • Rensa data till filen
    • Ladda ned uppladdade data
    • Ta bort filsystem

Ytterligare dokumentation

Tabell för API-mappning mellan ADLS Gen1 och ADLS Gen2 Mer omfattande REST-dokumentation om Data Lake Storage Gen2 finns i dokumentationen om Data Lake Storage Gen2 på docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekoden eller kontakta opencode@microsoft.com med ytterligare frågor eller kommentarer.