Klientská knihovna služby Azure DataLake pro Python – verze 12.14.0
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ří:
- 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é.
- 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
- K použití tohoto balíčku se vyžaduje Python 3.7 nebo novější. Další podrobnosti najdete na naší stránce věnované zásadám podpory verzí sady Azure SDK pro Python.
- Abyste mohli tento balíček používat, musíte mít předplatné Azure a účet úložiště Azure .
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í:
- Použití řetězce tokenu SAS
- Použití sdíleného přístupového klíče účtu
- 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:
- 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_client
funkcí ,get_directory_client
neboget_file_system_client
. - 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 . - 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ářů.
- 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.
- 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.
Azure SDK for Python
Váš názor
https://aka.ms/ContentUserFeedback.
Připravujeme: V průběhu roku 2024 budeme postupně vyřazovat problémy z GitHub coby mechanismus zpětné vazby pro obsah a nahrazovat ho novým systémem zpětné vazby. Další informace naleznete v tématu:Odeslat a zobrazit názory pro