Biblioteka klienta usługi Azure DataLake dla języka Python — wersja 12.14.0

Omówienie

Ten pakiet w wersji zapoznawczej dla języka Python zawiera obsługę interfejsu API specyficznego dla usługi ADLS Gen2 udostępnionego w zestawie STORAGE SDK. Obejmuje to następujące działania:

1. Nowe operacje na poziomie katalogu (Tworzenie, zmienianie nazwy, usuwanie) dla konta magazynu z włączoną hierarchiczną przestrzenią nazw (HNS). W przypadku kont z włączoną usługą HNS operacje zmiany nazwy/przenoszenia są niepodzielne.
2. Operacje związane z uprawnieniami (Pobieranie/ustawianie list ACL) dla kont z włączoną hierarchiczną przestrzenią nazw (HNS).

Kod | źródłowyPakiet (PyPi) | Pakiet (Conda) | Dokumentacja referencyjna interfejsu | APIDokumentacja | produktuPróbki

Wprowadzenie

Wymagania wstępne

• Do korzystania z tego pakietu jest wymagany język Python w wersji 3.7 lub nowszej. Aby uzyskać więcej informacji, przeczytaj naszą stronę dotyczącą zasad pomocy technicznej zestawu Azure SDK dla języka Python.
• Aby korzystać z tego pakietu, musisz mieć subskrypcję platformy Azure i konto usługi Azure Storage .

Instalowanie pakietu

Zainstaluj bibliotekę klienta usługi Azure DataLake Storage dla języka Python za pomocą narzędzia pip:

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

Tworzenie konta magazynu

Jeśli chcesz utworzyć nowe konto magazynu, możesz użyć witryny Azure Portal, Azure PowerShell lub interfejsu wiersza polecenia platformy 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

Uwierzytelnianie klienta

Interakcja z usługą DataLake Storage rozpoczyna się od wystąpienia klasy DataLakeServiceClient. Do utworzenia wystąpienia obiektu klienta potrzebne jest istniejące konto magazynu, jego adres URL i poświadczenia.

Pobieranie poświadczeń

Aby uwierzytelnić klienta, masz kilka opcji:

1. Używanie ciągu tokenu sygnatury dostępu współdzielonego
2. Używanie klucza dostępu współdzielonego konta
3. Używanie poświadczeń tokenu z pliku azure.identity

Alternatywnie możesz uwierzytelnić się przy użyciu parametry połączenia magazynu przy użyciu from_connection_string metody . Zobacz przykład: Tworzenie klienta przy użyciu parametry połączenia.

Możesz pominąć poświadczenie, jeśli adres URL konta ma już token SAS.

Tworzenie klienta

Po uzyskaniu gotowego adresu URL konta i poświadczeń możesz utworzyć element DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Kluczowe pojęcia

Magazyn DataLake oferuje cztery typy zasobów:

• Konto magazynu
• System plików na koncie magazynu
• Katalog w systemie plików
• Plik w systemie plików lub w katalogu

Klienci asynchroniczny

Ta biblioteka zawiera kompletny asynchroniczny interfejs API obsługiwany w języku Python 3.5 lub nowszym. Aby go używać, należy najpierw zainstalować transport asynchroniczny, taki jak aiohttp. Aby uzyskać więcej informacji, zobacz dokumentację platformy azure-core .

Klienci asynchroniczne i poświadczenia powinny być zamykane, gdy nie są już potrzebne. Te obiekty są menedżerami kontekstu asynchronicznego i definiują metody asynchroniczne close .

Klienci

Zestaw SDK usługi DataLake Storage udostępnia czterech różnych klientów do interakcji z usługą DataLake:

1. DataLakeServiceClient — ten klient wchodzi w interakcję z usługą DataLake na poziomie konta. Zapewnia ona operacje pobierania i konfigurowania właściwości konta, a także tworzenia i usuwania systemów plików w ramach konta. W przypadku operacji związanych z określonym systemem plików, katalogiem lub plikiem klienci dla tych jednostek mogą być również pobierani przy użyciu get_file_clientfunkcji lub get_directory_clientget_file_system_client .
2. FileSystemClient — ten klient reprezentuje interakcję z określonym systemem plików, nawet jeśli ten system plików jeszcze nie istnieje. Zapewnia ona operacje tworzenia, usuwania lub konfigurowania systemów plików oraz obejmuje operacje umożliwiające wyświetlanie listy ścieżek w systemie plików, przekazywanie i usuwanie pliku lub katalogu w systemie plików. W przypadku operacji związanych z określonym plikiem można również pobrać klienta przy użyciu get_file_client funkcji . W przypadku operacji związanych z określonym katalogiem można pobrać klienta przy użyciu get_directory_client funkcji .
3. DataLakeDirectoryClient — ten klient reprezentuje interakcję z określonym katalogiem, nawet jeśli ten katalog jeszcze nie istnieje. Zapewnia operacje tworzenia, usuwania, zmieniania nazwy, pobierania właściwości i ustawiania operacji właściwości.
4. DataLakeFileClient — ten klient reprezentuje interakcję z określonym plikiem, nawet jeśli ten plik jeszcze nie istnieje. Zapewnia operacje na plikach umożliwiające dołączanie danych, opróżnianie danych, usuwanie, tworzenie i odczytywanie pliku.
5. DataLakeLeaseClient — ten klient reprezentuje interakcje dzierżawy z elementem FileSystemClient, DataLakeDirectoryClient lub DataLakeFileClient. Zapewnia ona operacje uzyskiwania, odnawiania, wydawania, zmieniania i przerywania dzierżaw zasobów.

Przykłady

W poniższych sekcjach przedstawiono kilka fragmentów kodu obejmujących niektóre z najbardziej typowych zadań usługi Storage DataLake, w tym:

• Tworzenie klienta przy użyciu parametry połączenia
• Przekazywanie pliku
• Pobieranie pliku
• Wyliczanie ścieżek

Tworzenie klienta przy użyciu parametry połączenia

Utwórz obiekt DataLakeServiceClient przy użyciu parametry połączenia na koncie usługi Azure Storage.

from azure.storage.filedatalake import DataLakeServiceClient

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

Przekazywanie pliku

Przekaż plik do systemu plików.

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

Pobieranie pliku

Pobierz plik z systemu plików.

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)

Wyliczanie ścieżek

Wyświetl listę ścieżek w systemie plików.

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

Konfiguracja opcjonalna

Opcjonalne argumenty słów kluczowych, które można przekazać na poziomie klienta i na poziomie operacji.

Konfiguracja zasad ponawiania

Podczas tworzenia wystąpienia klienta w celu skonfigurowania zasad ponawiania należy użyć następujących argumentów słów kluczowych:

• retry_total (int): całkowita liczba ponownych prób do zezwolenia. Ma pierwszeństwo przed innymi liczbami. Przekaż, retry_total=0 jeśli nie chcesz ponawiać prób na żądaniach. Wartość domyślna to 10.
• retry_connect (int): ile błędów związanych z połączeniem należy ponowić próbę. Wartość domyślna to 3.
• retry_read (int): ile razy należy ponowić próbę w przypadku błędów odczytu. Wartość domyślna to 3.
• retry_status (int): ile razy należy ponowić próbę w przypadku kodów złego stanu. Wartość domyślna to 3.
• retry_to_secondary (wartość logiczna): czy żądanie powinno zostać ponowione do pomocniczego, jeśli jest możliwe. Powinno być włączone tylko konta RA-GRS są używane i potencjalnie nieaktualne dane mogą być obsługiwane. Wartość domyślna to False.

Inna konfiguracja klienta/operacji

Inne opcjonalne argumenty słowa kluczowego konfiguracji, które można określić na kliencie lub na operację.

Argumenty słów kluczowych klienta:

• connection_timeout (int): liczba sekund oczekiwania klienta na nawiązanie połączenia z serwerem. Wartość domyślna to 20 sekund.
• read_timeout (int): liczba sekund oczekiwania klienta między kolejnymi operacjami odczytu na odpowiedź z serwera. Jest to limit czasu na poziomie gniazda i nie ma to wpływu na ogólny rozmiar danych. Limity czasu odczytu po stronie klienta zostaną automatycznie ponawiane. Wartość domyślna to 60 sekund.
• transport (dowolny): transport dostarczony przez użytkownika w celu wysłania żądania HTTP.

Argumenty słów kluczowych dla operacji:

• raw_response_hook (możliwe do wywołania): podane wywołanie zwrotne używa odpowiedzi zwróconej z usługi.
• raw_request_hook (z możliwością wywołania): podane wywołanie zwrotne używa żądania przed wysłaniem do usługi.
• client_request_id (str): opcjonalna identyfikacja żądania przez użytkownika.
• user_agent (str): dołącza wartość niestandardową do nagłówka user-agent, który ma zostać wysłany wraz z żądaniem.
• logging_enable (wartość logiczna): włącza rejestrowanie na poziomie DEBUG. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
• logging_body (wartość logiczna): umożliwia rejestrowanie treści żądania i odpowiedzi. Wartość domyślna to False. Można również przekazać na poziomie klienta, aby włączyć je dla wszystkich żądań.
• nagłówki (dict): przekazuj nagłówki niestandardowe jako pary klucz, wartość. Przykład. headers={'CustomValue': value}

Rozwiązywanie problemów

Ogólne

Klienci usługi DataLake Storage zgłaszają wyjątki zdefiniowane w usłudze Azure Core.

Ta lista może służyć do przywoływania zgłaszanych wyjątków. Aby uzyskać określony kod błędu wyjątku, użyj atrybutu error_code , tj exception.error_code. .

Rejestrowanie

Ta biblioteka używa standardowej biblioteki rejestrowania do rejestrowania. Podstawowe informacje o sesjach HTTP (adresach URL, nagłówkach itp.) są rejestrowane na poziomie INFORMACJI.

Szczegółowe rejestrowanie na poziomie DEBUG, w tym treści żądań/odpowiedzi i nieredagowanych nagłówków, można włączyć na kliencie z argumentem 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)

logging_enable Podobnie można włączyć szczegółowe rejestrowanie dla pojedynczej operacji, nawet jeśli nie jest włączone dla klienta:

service_client.list_file_systems(logging_enable=True)

Następne kroki

Więcej przykładów kodu

Rozpocznij pracę z przykładami usługi Azure DataLake.

Kilka przykładów zestawu SDK języka Python usługi DataLake Storage jest dostępnych w repozytorium GitHub zestawu SDK. Te przykłady zawierają przykładowy kod dla dodatkowych scenariuszy, które często występują podczas pracy z usługą DataLake Storage:

• datalake_samples_access_control.py — Przykłady typowych zadań usługi DataLake Storage:

  • Konfigurowanie systemu plików
  • Tworzenie katalogu
  • Ustawianie/uzyskiwanie kontroli dostępu dla katalogu
  • Tworzenie plików w katalogu
  • Ustawianie/uzyskiwanie kontroli dostępu dla każdego pliku
  • Usuwanie systemu plików

• datalake_samples_upload_download.py — Przykłady typowych zadań usługi DataLake Storage:

  • Konfigurowanie systemu plików
  • Tworzenie pliku
  • Dołączanie danych do pliku
  • Opróżnianie danych do pliku
  • Pobieranie przekazanych danych
  • Usuwanie systemu plików

Dodatkowa dokumentacja

Tabela mapowania interfejsu API usługi ADLS Gen1 na usługę ADLS Gen2. Aby uzyskać bardziej obszerną dokumentację REST dotyczącą Data Lake Storage Gen2, zobacz dokumentację Data Lake Storage Gen2 dotyczącą docs.microsoft.com.

Współtworzenie

W tym projekcie zachęcamy do współtworzenia i zgłaszania sugestii. Współtworzenie w większości przypadków wymaga zgody na umowę licencyjną dotyczącą współautorów (CLA, Contributor License Agreement), zgodnie z którą współautor ma prawo udzielić i faktycznie udziela nam praw do używania wytworzonej przez siebie zawartości. Aby uzyskać szczegółowe informacje, odwiedź stronę https://cla.microsoft.com.

Po przesłaniu żądania ściągnięcia robot CLA automatycznie określi, czy musisz przekazać umowę CLA, i doda odpowiednie informacje do tego żądania (na przykład etykietę czy komentarz). Po prostu postępuj zgodnie z instrukcjami robota. Wystarczy zrobić to raz dla wszystkich repozytoriów, w przypadku których jest używana nasza umowa CLA.

W tym projekcie przyjęto Kodeks postępowania oprogramowania Open Source firmy Microsoft. Aby uzyskać więcej informacji, zobacz Często zadawane pytania dotyczące kodeksu postępowania lub skontaktuj się z opencode@microsoft.com dodatkowymi pytaniami lub komentarzami.