Delen via

Azure DataLake-serviceclientbibliotheek voor Python - versie 12.14.0

  • Artikel

Overzicht

Dit preview-pakket voor Python bevat ADLS Gen2-specifieke API-ondersteuning die beschikbaar wordt gesteld in de Storage SDK. Dit omvat:

  1. Nieuwe bewerkingen op directoryniveau (Maken, Naam wijzigen, Verwijderen) voor opslagaccount met hiërarchische naamruimte (HNS). Voor accounts waarvoor HNS is ingeschakeld, zijn de bewerkingen voor hernoemen/verplaatsen atomisch.
  2. Machtigingsgerelateerde bewerkingen (ACL's ophalen/instellen) voor HNS-accounts (hiërarchische naamruimte ingeschakeld).

Broncode | Pakket (PyPi) | Pakket (Conda) | API-referentiedocumentatie | Productdocumentatie | Monsters

Aan de slag

Vereisten

Het pakket installeren

Installeer de Azure DataLake Storage-clientbibliotheek voor Python met pip:

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

Create a storage account

Als u een nieuw opslagaccount wilt maken, kunt u Azure Portal, Azure PowerShell of Azure CLI gebruiken:

# 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

De client verifiëren

Interactie met DataLake Storage begint met een exemplaar van de klasse DataLakeServiceClient. U hebt een bestaand opslagaccount, de URL en een referentie nodig om het clientobject te instantiëren.

Referenties ophalen

Als u de client wilt verifiëren, hebt u een aantal opties:

  1. Een SAS-tokentekenreeks gebruiken
  2. Een gedeelde toegangssleutel voor een account gebruiken
  3. Een tokenreferentie van azure.identity gebruiken

U kunt zich ook verifiëren met een opslag-verbindingsreeks met behulp van de from_connection_string -methode. Zie voorbeeld: Client maken met een verbindingsreeks.

U kunt de referentie weglaten als uw account-URL al een SAS-token heeft.

Client maken

Zodra u de account-URL en referenties bij de hand hebt, kunt u de DataLakeServiceClient maken:

from azure.storage.filedatalake import DataLakeServiceClient

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

Belangrijkste concepten

DataLake Storage biedt vier typen resources:

  • Het opslagaccount
  • Een bestandssysteem in het opslagaccount
  • Een map onder het bestandssysteem
  • Een bestand in een bestandssysteem of onder de map

Asynchrone clients

Deze bibliotheek bevat een volledige asynchrone API die wordt ondersteund in Python 3.5+. Als u deze wilt gebruiken, moet u eerst een asynchroon transport installeren, zoals aiohttp. Zie azure-core-documentatie voor meer informatie.

Asynchrone clients en referenties moeten worden gesloten wanneer ze niet meer nodig zijn. Deze objecten zijn asynchrone contextbeheerders en definiëren asynchrone close methoden.

Clients

De DataLake Storage SDK biedt vier verschillende clients voor interactie met de DataLake-service:

  1. DataLakeServiceClient : deze client communiceert met de DataLake-service op accountniveau. Het biedt bewerkingen voor het ophalen en configureren van de accounteigenschappen, evenals het weergeven, maken en verwijderen van bestandssystemen binnen het account. Voor bewerkingen die betrekking hebben op een specifiek bestandssysteem, een specifieke map of een specifiek bestand, kunnen clients voor deze entiteiten ook worden opgehaald met behulp van de get_file_clientfuncties , get_directory_client of get_file_system_client .
  2. FileSystemClient : deze client vertegenwoordigt interactie met een specifiek bestandssysteem, zelfs als dat bestandssysteem nog niet bestaat. Het biedt bewerkingen voor het maken, verwijderen of configureren van bestandssystemen en bevat bewerkingen voor het weergeven van paden onder het bestandssysteem, het uploaden en verwijderen van bestanden of mappen in het bestandssysteem. Voor bewerkingen met betrekking tot een specifiek bestand kan de client ook worden opgehaald met behulp van de get_file_client functie . Voor bewerkingen die betrekking hebben op een specifieke map, kan de client worden opgehaald met behulp van de get_directory_client functie.
  3. DataLakeDirectoryClient - deze client vertegenwoordigt interactie met een specifieke map, zelfs als die map nog niet bestaat. Het biedt bewerkingen voor maken, verwijderen, hernoemen, eigenschappen ophalen en eigenschappen instellen bewerkingen.
  4. DataLakeFileClient - deze client vertegenwoordigt interactie met een specifiek bestand, zelfs als dat bestand nog niet bestaat. Het biedt bestandsbewerkingen voor het toevoegen van gegevens, het leegmaken van gegevens, het verwijderen, maken en lezen van bestanden.
  5. DataLakeLeaseClient - deze client vertegenwoordigt lease-interacties met een FileSystemClient, DataLakeDirectoryClient of DataLakeFileClient. Het biedt bewerkingen voor het verkrijgen, vernieuwen, vrijgeven, wijzigen en verbreken van leases voor de resources.

Voorbeelden

De volgende secties bevatten verschillende codefragmenten voor enkele van de meest voorkomende Storage DataLake-taken, waaronder:

Client maken met een verbindingsreeks

Maak de DataLakeServiceClient met behulp van de verbindingsreeks naar uw Azure Storage-account.

from azure.storage.filedatalake import DataLakeServiceClient

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

Een bestand uploaden

Upload een bestand naar uw bestandssysteem.

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

Een bestand downloaden

Download een bestand uit uw bestandssysteem.

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)

Paden opsommen

Maak een lijst met de paden in uw bestandssysteem.

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

Optionele configuratie

Optionele trefwoordargumenten die kunnen worden doorgegeven op het niveau van de client en per bewerking.

Configuratie van beleid voor opnieuw proberen

Gebruik de volgende trefwoordargumenten bij het instantiëren van een client om het beleid voor opnieuw proberen te configureren:

  • retry_total (int): het totale aantal nieuwe pogingen dat moet worden toegestaan. Heeft voorrang op andere aantallen. Geef door retry_total=0 als u aanvragen niet opnieuw wilt proberen. De standaardwaarde is 10.
  • retry_connect (int): hoeveel verbindingsfouten u opnieuw wilt proberen. Standaardwaarde is 3.
  • retry_read (int): hoe vaak moet u het opnieuw proberen bij leesfouten. Standaardwaarde is 3.
  • retry_status (int): hoe vaak moet u ongeldige statuscodes opnieuw proberen. Standaardwaarde is 3.
  • retry_to_secondary (bool): of de aanvraag opnieuw moet worden geprobeerd naar secundaire, indien mogelijk. Dit mag alleen worden ingeschakeld als RA-GRS-accounts worden gebruikt en mogelijk verouderde gegevens kunnen worden verwerkt. De standaardwaarde is False.

Andere client/configuratie per bewerking

Andere optionele trefwoordargumenten voor configuratie die kunnen worden opgegeven op de client of per bewerking.

Argumenten voor clientwoorden:

  • connection_timeout (int): het aantal seconden dat de client wacht om verbinding te maken met de server. De standaardwaarde is 20 seconden.
  • read_timeout (int): het aantal seconden dat de client tussen opeenvolgende leesbewerkingen wacht op een antwoord van de server. Dit is een time-out op socketniveau en wordt niet beïnvloed door de totale gegevensgrootte. Time-outs voor lezen aan de clientzijde worden automatisch opnieuw geprobeerd. De standaardwaarde is 60 seconden.
  • transport (alle): door de gebruiker opgegeven transport om de HTTP-aanvraag te verzenden.

Trefwoordargumenten per bewerking:

  • raw_response_hook (aanroepbaar): de opgegeven callback maakt gebruik van het antwoord dat is geretourneerd door de service.
  • raw_request_hook (aanroepbaar): de opgegeven callback maakt gebruik van de aanvraag voordat deze naar de service wordt verzonden.
  • client_request_id (str): optioneel door de gebruiker opgegeven identificatie van de aanvraag.
  • user_agent (str): voegt de aangepaste waarde toe aan de header user-agent die met de aanvraag moet worden verzonden.
  • logging_enable (bool): hiermee schakelt u logboekregistratie in op het niveau VAN FOUTOPSPORING. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • logging_body (bool): hiermee schakelt u logboekregistratie van de aanvraag- en antwoordtekst in. Standaard ingesteld op False. Kan ook worden doorgegeven op clientniveau om deze in te schakelen voor alle aanvragen.
  • headers (dict): geef aangepaste headers door als sleutel, waardeparen. Bijvoorbeeld. headers={'CustomValue': value}

Problemen oplossen

Algemeen

DataLake Storage-clients genereren uitzonderingen die zijn gedefinieerd in Azure Core.

Deze lijst kan worden gebruikt ter referentie om opgetreden uitzonderingen te ondervangen. Als u de specifieke foutcode van de uitzondering wilt ophalen, gebruikt u het error_code kenmerk, dat wil zeggen exception.error_code.

Logboekregistratie

Deze bibliotheek maakt gebruik van de standaardbibliotheek voor logboekregistratie voor logboekregistratie. Basisinformatie over HTTP-sessies (URL's, headers, enzovoort) wordt geregistreerd op INFO-niveau.

Gedetailleerde logboekregistratie op foutopsporingsniveau, inclusief aanvraag-/antwoordteksten en niet-bewerkte headers, kan worden ingeschakeld op een client met het logging_enable argument:

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)

Op dezelfde manier kan logging_enable logboekregistratie voor één bewerking inschakelen, zelfs wanneer dit niet is ingeschakeld voor de client:

service_client.list_file_systems(logging_enable=True)

Volgende stappen

Meer voorbeeldcode

Ga aan de slag met onze Azure DataLake-voorbeelden.

Er zijn verschillende Python SDK-voorbeelden voor DataLake Storage beschikbaar in de GitHub-opslagplaats van de SDK. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met DataLake Storage:

  • datalake_samples_access_control.py - Voorbeelden voor algemene DataLake Storage-taken:

    • Een bestandssysteem instellen
    • Een map maken
    • Toegangsbeheer voor de map instellen/ophalen
    • Bestanden maken in de map
    • Toegangsbeheer instellen/ophalen voor elk bestand
    • Bestandssysteem verwijderen

  • datalake_samples_upload_download.py - Voorbeelden voor algemene DataLake Storage-taken:

    • Een bestandssysteem instellen
    • Bestand maken
    • Gegevens toevoegen aan het bestand
    • Gegevens naar het bestand leegmaken
    • De geüploade gegevens downloaden
    • Bestandssysteem verwijderen

Aanvullende documentatie

Tabel voor API-toewijzing van ADLS Gen1 naar ADLS Gen2 Zie de Data Lake Storage Gen2 documentatie over docs.microsoft.com voor uitgebreidere REST-documentatie over Data Lake Storage Gen2.

Bijdragen

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie de Veelgestelde vragen over de gedragscode voor meer informatie of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.