Sdílet prostřednictvím

Klientská knihovna služby Azure DataLake pro Python – verze 12.14.0

  • Článek

Přehled

Tento balíček Preview pro Python zahrnuje podporu rozhraní API ADLS Gen2, která je k dispozici v sadě SDK služby Storage. Sem patří:

  1. Nové operace na úrovni adresáře (Vytvoření, Přejmenování, Odstranění) pro účet úložiště s povoleným hierarchickým oborem názvů (HNS). U účtů s povolenými HNS jsou operace přejmenování a přesunu atomické.
  2. Operace související s oprávněními (získání/nastavení seznamů ACL) pro účty s povoleným hierarchickým oborem názvů (HNS).

Zdrojový kód | Balíček (PyPi) | Balíček (Conda) | Referenční dokumentace k | rozhraní APIDokumentace k | produktuVzorky

Začínáme

Požadavky

Instalace balíčku

Nainstalujte klientskou knihovnu Azure DataLake Storage pro Python pomocí pip:

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

Vytvoření účtu úložiště

Pokud chcete vytvořit nový účet úložiště, můžete použít Azure Portal, Azure PowerShell nebo 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

Ověření klienta

Interakce se službou DataLake Storage začíná instancí třídy DataLakeServiceClient. K vytvoření instance objektu klienta potřebujete existující účet úložiště, jeho adresu URL a přihlašovací údaje.

Získání přihlašovacích údajů

K ověření klienta máte několik možností:

  1. Použití řetězce tokenu SAS
  2. Použití sdíleného přístupového klíče účtu
  3. Použití přihlašovacích údajů tokenu z azure.identity

Případně se můžete ověřit pomocí připojovací řetězec úložiště pomocí from_connection_string metody . Příklad: Vytvoření klienta s připojovací řetězec.

Pokud adresa URL vašeho účtu už token SAS obsahuje, můžete přihlašovací údaje vynechat.

Vytvoření klienta

Jakmile budete mít adresu URL účtu a přihlašovací údaje připravené, můžete vytvořit DataLakeServiceClient:

from azure.storage.filedatalake import DataLakeServiceClient

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

Klíčové koncepty

Úložiště DataLake nabízí čtyři typy prostředků:

  • Účet úložiště
  • Systém souborů v účtu úložiště
  • Adresář v systému souborů
  • Soubor v systému souborů nebo v adresáři

Asynchronní klienti

Tato knihovna obsahuje kompletní asynchronní rozhraní API podporované v Pythonu 3.5 nebo novějším. Abyste ho mohli používat, musíte nejdřív nainstalovat asynchronní přenos, například aiohttp. Další informace najdete v dokumentaci k azure-core .

Asynchronní klienti a přihlašovací údaje by se měly zavřít, když už je nepotřebujete. Tyto objekty jsou správci asynchronního kontextu a definují asynchronní close metody.

Klienti

Sada DataLake Storage SDK poskytuje čtyři různé klienty pro interakci se službou DataLake:

  1. DataLakeServiceClient – tento klient komunikuje se službou DataLake na úrovni účtu. Poskytuje operace pro načtení a konfiguraci vlastností účtu a také výpis, vytvoření a odstranění systémů souborů v rámci účtu. U operací souvisejících s konkrétním systémem souborů, adresářem nebo souborem je možné klienty pro tyto entity načíst také pomocí get_file_clientfunkcí , get_directory_client nebo get_file_system_client .
  2. FileSystemClient – tento klient představuje interakci s konkrétním systémem souborů, i když tento systém souborů ještě neexistuje. Poskytuje operace pro vytvoření, odstranění nebo konfiguraci systémů souborů a zahrnuje operace pro výpis cest v systému souborů, nahrávání a odstraňování souborů nebo adresářů v systému souborů. U operací souvisejících s konkrétním souborem je možné klienta načíst také pomocí get_file_client funkce . U operací souvisejících s konkrétním adresářem je možné klienta načíst pomocí get_directory_client funkce .
  3. DataLakeDirectoryClient – tento klient představuje interakci s konkrétním adresářem, i když tento adresář ještě neexistuje. Poskytuje operace vytvoření, odstranění, přejmenování, získání vlastností a nastavení vlastností adresářů.
  4. DataLakeFileClient – tento klient představuje interakci s konkrétním souborem, i když tento soubor ještě neexistuje. Poskytuje operace se soubory pro připojení dat, vyprázdnění dat, odstranění, vytvoření a čtení souboru.
  5. DataLakeLeaseClient – tento klient představuje interakce zapůjčení s objekty FileSystemClient, DataLakeDirectoryClient nebo DataLakeFileClient. Poskytuje operace pro získání, prodloužení, uvolnění, změnu a přerušení zapůjčení prostředků.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé nejběžnější úlohy Storage DataLake, včetně těchto:

Vytvoření klienta pomocí připojovací řetězec

Vytvořte DataLakeServiceClient pomocí připojovací řetězec k vašemu účtu Azure Storage.

from azure.storage.filedatalake import DataLakeServiceClient

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

Nahrání souboru

Nahrajte soubor do systému souborů.

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

Stažení souboru

Stáhněte soubor ze systému souborů.

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)

Vytváření výčtu cest

Vypište cesty v systému souborů.

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

Volitelná konfigurace

Volitelné argumenty klíčových slov, které je možné předat na úrovni klienta a jednotlivých operací.

Konfigurace zásad opakování

Při vytváření instance klienta ke konfiguraci zásad opakování použijte následující argumenty s klíčovými slovy:

  • retry_total (int): Celkový počet povolených opakování. Má přednost před ostatními počty. retry_total=0 Pokud nechcete opakovat pokusy na žádostech, předejte je. Výchozí hodnota je 10.
  • retry_connect (int): Kolik chyb souvisejících s připojením se má opakovat. Výchozí hodnota je 3.
  • retry_read (int): Kolikrát se má opakovat při čtení chyb. Výchozí hodnota je 3.
  • retry_status (int): Kolikrát se má opakovat chybný stavový kód. Výchozí hodnota je 3.
  • retry_to_secondary (bool): Určuje, jestli se má požadavek opakovat do sekundárního systému, pokud je to možné. Tato možnost by měla být povolená pouze u účtů RA-GRS a potenciálně je možné zpracovávat zastaralá data. Výchozí hodnota je False.

Konfigurace jiného klienta nebo operace

Další volitelné argumenty klíčového slova konfigurace, které je možné zadat v klientovi nebo pro každou operaci.

Argumenty klíčových slov klienta:

  • connection_timeout (int): Počet sekund, po které bude klient čekat na navázání připojení k serveru. Výchozí hodnota je 20 sekund.
  • read_timeout (int): Počet sekund, po který klient čeká mezi po sobě jdoucími operacemi čtení na odpověď ze serveru. Jedná se o časový limit na úrovni soketů, který není ovlivněn celkovou velikostí dat. Časové limity čtení na straně klienta se automaticky zopakují. Výchozí hodnota je 60 sekund.
  • transport (libovolný): Uživatelem poskytnutý přenos pro odeslání požadavku HTTP.

Argumenty klíčových slov pro jednotlivé operace:

  • raw_response_hook (volatelné): Dané zpětné volání používá odpověď vrácenou službou.
  • raw_request_hook (volatelné): Dané zpětné volání použije požadavek před odesláním do služby.
  • client_request_id (str): Identifikace požadavku byla zadána nepovinně uživatelem.
  • user_agent (str): Připojí vlastní hodnotu k hlavičce uživatelského agenta, která se má spolu s požadavkem odeslat.
  • logging_enable (bool): Povolí protokolování na úrovni LADĚNÍ. Výchozí hodnota je False. Dá se také předat na úrovni klienta, aby se povolilo pro všechny požadavky.
  • logging_body (bool): Povolí protokolování textu požadavku a odpovědi. Výchozí hodnota je False. Dá se také předat na úrovni klienta, aby se povolilo pro všechny požadavky.
  • headers (dict): Předávají vlastní hlavičky jako páry klíčů a hodnot. Např. headers={'CustomValue': value}

Poradce při potížích

Obecné

Klienti DataLake Storage vyvolávají výjimky definované v Azure Core.

Tento seznam lze použít jako referenci k zachycení vyvolaných výjimek. Pokud chcete získat konkrétní kód chyby výjimky, použijte error_code atribut , tj exception.error_code. .

protokolování

Tato knihovna používá k protokolování standardní knihovnu protokolování . Základní informace o relacích HTTP (adresy URL, hlavičky atd.) se protokolují na úrovni INFO.

Podrobné protokolování úrovně LADĚNÍ, včetně těl požadavků/odpovědí a nezopravovaných hlaviček, je možné povolit na klientovi s 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)

Podobně logging_enable může povolit podrobné protokolování pro jednu operaci, i když není povolené pro klienta:

service_client.list_file_systems(logging_enable=True)

Další kroky

Další vzorový kód

Začněte s našimi ukázkami Azure DataLake.

V úložišti Sady SDK GitHub sady SDK pro DataLake Storage máte k dispozici několik ukázek sady Python SDK. Tyto ukázky poskytují ukázkový kód pro další scénáře, se kterými se běžně setkáte při práci se službou DataLake Storage:

  • datalake_samples_access_control.py – Příklady běžných úloh DataLake Storage:

    • Nastavení systému souborů
    • Vytvoření adresáře
    • Nastavení nebo získání řízení přístupu k adresáři
    • Vytvoření souborů v adresáři
    • Nastavení nebo získání řízení přístupu pro každý soubor
    • Odstranit systém souborů

  • datalake_samples_upload_download.py – Příklady běžných úloh DataLake Storage:

    • Nastavení systému souborů
    • Vytvořit soubor
    • Připojení dat k souboru
    • Vyprázdnění dat do souboru
    • Stažení nahraných dat
    • Odstranit systém souborů

Další dokumentace

Tabulka pro mapování rozhraní API ADLS Gen1 na ADLS Gen2. Podrobnější dokumentaci k Data Lake Storage Gen2 najdete v dokumentaci k Data Lake Storage Gen2 k docs.microsoft.com.

Přispívání

Tento projekt vítá příspěvky a návrhy. Většina příspěvků vyžaduje souhlas s licenční smlouvou s přispěvatelem (CLA), která stanoví, že máte právo udělit nám práva k používání vašeho příspěvku a skutečně tak činíte. Podrobnosti najdete tady: https://cla.microsoft.com

Při odesílání žádosti o přijetí změn robot CLA automaticky určí, jestli je potřeba poskytnout smlouvu CLA, a příslušným způsobem žádost o přijetí změn upraví (např. přidáním jmenovky nebo komentáře). Stačí postupovat podle pokynů robota. Pro všechna úložiště používající naši smlouvu CLA to stačí udělat jenom jednou.

Tento projekt přijal pravidla chování pro Microsoft Open Source. Další informace najdete v nejčastějších dotazech k pravidlům chování nebo kontaktujte s opencode@microsoft.com případnými dalšími dotazy nebo připomínkami.