Sdílet prostřednictvím

Klientská knihovna sdílené složky Azure Storage pro Python – verze 12.15.0

  • Článek

Úložiště sdílených složek Azure nabízí plně spravované sdílené složky v cloudu, které jsou přístupné prostřednictvím standardního protokolu SMB (Server Message Block). Sdílené složky Azure je možné připojit současně do cloudových i místních nasazení systémů Windows, Linux a macOS. Sdílené složky Azure je navíc možné ukládat do mezipaměti ve Windows Serveru pomocí Synchronizace souborů Azure, aby byly rychle přístupné poblíž místa, kde se data používají.

Sdílené složky Azure lze použít k těmto činnostem:

  • Nahrazení nebo doplnění místních souborových serverů
  • Aplikace "lift and shift"
  • Zjednodušení vývoje pro cloud pomocí nastavení sdílených aplikací, sdílené složky diagnostiky a nástrojů pro vývoj, testování a ladění

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 sdílené složky Azure Storage pro Python pomocí pip:

pip install azure-storage-file-share

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

# Create the storage account
az storage account create -n my-storage-account-name -g my-resource-group

Vytvoření klienta

Klientská knihovna sdílených složek Azure Storage pro Python umožňuje interakci se čtyřmi typy prostředků: se samotným účtem úložiště, sdílenými složkami, adresáři a soubory. Interakce s těmito prostředky začíná instancí klienta. K vytvoření objektu klienta budete potřebovat adresu URL souborové služby účtu úložiště a přihlašovací údaje, které vám umožní přístup k účtu úložiště:

from azure.storage.fileshare import ShareServiceClient

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

Vyhledání adresy URL účtu

Adresu URL souborové služby účtu úložiště najdete pomocí webu Azure Portal, Azure PowerShell nebo Azure CLI:

# Get the file service URL for the storage account
az storage account show -n my-storage-account-name -g my-resource-group --query "primaryEndpoints.file"

Typy přihlašovacích údajů

Parametr credential může být k dispozici v různých formách v závislosti na typu autorizace , kterou chcete použít:

  1. Pokud chcete použít token sdíleného přístupového podpisu (SAS), zadejte token jako řetězec. Pokud adresa URL vašeho účtu obsahuje token SAS, vyněžte parametr credential. Token SAS můžete vygenerovat na webu Azure Portal v části Sdílený přístupový podpis nebo můžete použít některou z generate_sas() funkcí k vytvoření tokenu SAS pro účet úložiště, sdílenou složku nebo soubor:

    from datetime import datetime, timedelta
from azure.storage.fileshare import ShareServiceClient, generate_account_sas, ResourceTypes, AccountSasPermissions

sas_token = generate_account_sas(
    account_name="<storage-account-name>",
    account_key="<account-access-key>",
    resource_types=ResourceTypes(service=True),
    permission=AccountSasPermissions(read=True),
    expiry=datetime.utcnow() + timedelta(hours=1)
)

share_service_client = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential=sas_token)

  2. Pokud chcete použít sdílený klíč účtu úložiště (neboli přístupový klíč účtu), zadejte ho jako řetězec. Najdete ho na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu Azure CLI:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    K ověření klienta použijte klíč jako parametr přihlašovacích údajů:

    from azure.storage.fileshare import ShareServiceClient
service = ShareServiceClient(account_url="https://<my_account_name>.file.core.windows.net", credential="<account_access_key>")

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

V závislosti na vašem případu použití a metodě autorizace můžete dát přednost inicializaci instance klienta s připojovací řetězec úložiště místo zadání adresy URL účtu a přihlašovacích údajů zvlášť. Uděláte to tak, že předáte připojovací řetězec úložiště metodě třídy klientafrom_connection_string:

from azure.storage.fileshare import ShareServiceClient

connection_string = "DefaultEndpointsProtocol=https;AccountName=xxxx;AccountKey=xxxx;EndpointSuffix=core.windows.net"
service = ShareServiceClient.from_connection_string(conn_str=connection_string)

Připojovací řetězec k účtu úložiště najdete na webu Azure Portal v části Přístupové klíče nebo spuštěním následujícího příkazu rozhraní příkazového řádku:

az storage account show-connection-string -g MyResourceGroup -n MyStorageAccount

Klíčové koncepty

Službu sdílených složek Azure tvoří následující komponenty:

  • Samotný účet úložiště
  • Sdílená složka v rámci účtu úložiště
  • Volitelná hierarchie adresářů v rámci sdílené složky
  • Soubor ve sdílené složce, který může mít velikost až 1 TiB.

Klientská knihovna sdílených složek Azure Storage pro Python umožňuje interakci s každou z těchto komponent pomocí vyhrazeného klientského objektu.

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

K dispozici jsou čtyři různí klienti pro interakci s různými komponentami služby Sdílení souborů:

  1. ShareServiceClient – tento klient představuje interakci se samotným účtem úložiště Azure a umožňuje získat předem nakonfigurované instance klienta pro přístup ke sdíleným složkám v rámci. Poskytuje operace pro načtení a konfiguraci vlastností služby a také výpis, vytvoření a odstranění sdílených složek v rámci účtu. Pokud chcete s konkrétní sdílenou složkou provádět operace, načtěte klienta pomocí metody .get_share_client
  2. ShareClient – tento klient představuje interakci s konkrétní sdílenou složkou (která ještě nemusí existovat) a umožňuje získat předem nakonfigurované instance klienta pro přístup k adresářům a souborům v rámci. Poskytuje operace pro vytvoření, odstranění, konfiguraci nebo vytvoření snímků sdílené složky a zahrnuje operace pro vytvoření a výčet obsahu adresářů v ní. Pokud chcete provádět operace s konkrétním adresářem nebo souborem, načtěte klienta pomocí get_directory_client metod nebo get_file_client .
  3. ShareDirectoryClient – tento klient představuje interakci s konkrétním adresářem (který ještě nemusí existovat). Poskytuje operace pro vytvoření, odstranění nebo výčet obsahu okamžitého nebo vnořeného podadresáře a zahrnuje operace pro vytvoření a odstranění souborů v něm. U operací souvisejících s konkrétním podadresářem nebo souborem lze klienta pro danou entitu načíst také pomocí get_subdirectory_client funkcí a get_file_client .
  4. ShareFileClient – tento klient představuje interakci s konkrétním souborem (který ještě nemusí existovat). Poskytuje operace pro nahrání, stažení, vytvoření, odstranění a kopírování souboru.

Podrobnosti o omezeních pojmenování cest najdete v tématu Pojmenování sdílených složek, adresářů, souborů a metadat a odkazování na je.

Příklady

Následující části obsahují několik fragmentů kódu, které pokrývají některé z nejběžnějších úloh sdílené složky úložiště, mezi které patří:

Vytvoření sdílené složky

Vytvoření sdílené složky pro ukládání souborů

from azure.storage.fileshare import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
share.create_share()

Vytvoření sdílené složky pomocí asynchronního klienta

from azure.storage.fileshare.aio import ShareClient

share = ShareClient.from_connection_string(conn_str="<connection_string>", share_name="myshare")
await share.create_share()

Nahrání souboru

Nahrání souboru do sdílené složky

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    file_client.upload_file(source_file)

Asynchronní nahrání souboru

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("./SampleSource.txt", "rb") as source_file:
    await file_client.upload_file(source_file)

Stažení souboru

Stažení souboru ze sdílené složky

from azure.storage.fileshare import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = file_client.download_file()
    data.readinto(file_handle)

Asynchronní stažení souboru

from azure.storage.fileshare.aio import ShareFileClient

file_client = ShareFileClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", file_path="my_file")

with open("DEST_FILE", "wb") as file_handle:
    data = await file_client.download_file()
    await data.readinto(file_handle)

Výpis obsahu adresáře

Výpis všech adresářů a souborů v nadřazené adresáři

from azure.storage.fileshare import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_list = list(parent_dir.list_directories_and_files())
print(my_list)

Asynchronní výpis obsahu adresáře

from azure.storage.fileshare.aio import ShareDirectoryClient

parent_dir = ShareDirectoryClient.from_connection_string(conn_str="<connection_string>", share_name="myshare", directory_path="parent_dir")

my_files = []
async for item in parent_dir.list_directories_and_files():
    my_files.append(item)
print(my_files)

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é lze 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é bude klient čekat mezi po sobě jdoucími operacemi čtení na odpověď ze serveru. Jedná se o časový limit na úrovni soketů, který nemá vliv na celkovou velikost dat. Automaticky se budou opakovat časové limity čtení na straně klienta. Výchozí hodnota je 60 sekund.
  • transport (Any): Přenos poskytnutý uživatelem k odeslání požadavku HTTP.

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

  • raw_response_hook (volatelné): Dané zpětné volání použije 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): Nepovinný uživatel zadal identifikaci požadavku.
  • user_agent (str): Připojí vlastní hodnotu k hlavičce uživatelského agenta, která se má odeslat spolu s požadavkem.
  • logging_enable (bool): Povolí protokolování na úrovni LADĚNÍ. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
  • logging_body (bool): Povolí protokolování textu požadavku a odpovědi. Výchozí hodnota je False. Můžete ho také předat na úrovni klienta, abyste ho povolili pro všechny požadavky.
  • headers (dict): Předejte vlastní hlavičky jako klíče a páry hodnot. Např. headers={'CustomValue': value}

Poradce při potížích

Obecné

Klienti souborů úložiště 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 , exception.error_codetj. .

protokolování

Tato knihovna používá pro 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 nereagovaných hlaviček, je možné povolit na klientovi s argumentem logging_enable :

import sys
import logging
from azure.storage.fileshare import ShareServiceClient

# Create a logger for the 'azure.storage.fileshare' SDK
logger = logging.getLogger('azure.storage.fileshare')
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 = ShareServiceClient.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.get_service_properties(logging_enable=True)

Další kroky

Další ukázkový kód

Začněte používat ukázky sdílení souborů.

Několik ukázek sady Python SDK pro sdílenou složku úložiště je k dispozici v úložišti sady SDK Na GitHubu. Tyto ukázky poskytují příklad kódu pro další scénáře, se kterými se při práci se sdílenou složkou úložiště běžně dochází:

  • file_samples_hello_world.py (asynchronní verze) – příklady v tomto článku:

    • Vytvoření klienta
    • Vytvoření sdílené složky
    • Nahrání souboru

  • file_samples_authentication.py (asynchronní verze) – příklady ověřování a vytvoření klienta:

    • Z připojovací řetězec
    • Ze sdíleného přístupového klíče
    • Z tokenu sdíleného přístupového podpisu

  • file_samples_service.py (asynchronní verze) – příklady pro interakci se souborovou službou:

    • Získání a nastavení vlastností služby
    • Vytvoření, výpis a odstranění sdílených složek
    • Získání klienta sdílené složky

  • file_samples_share.py (asynchronní verze) – příklady pro interakci se sdílenými složkami:

    • Vytvoření snímku sdílené složky
    • Nastavení kvóty sdílené složky a metadat
    • Výpis adresářů a souborů
    • Získání klienta adresáře nebo souboru pro interakci s konkrétní entitou

  • file_samples_directory.py (asynchronní verze) – příklady pro interakci s adresáři:

    • Vytvoření adresáře a přidání souborů
    • Vytvoření a odstranění podadresářů
    • Získání klienta podadresáře

  • file_samples_client.py (asynchronní verze) – příklady pro práci se soubory:

    • Vytváření, nahrávání, stahování a odstraňování souborů
    • Kopírování souboru z adresy URL

Další dokumentace

Rozsáhlejší dokumentaci ke službě Azure File Share Storage najdete v dokumentaci ke službě Azure File Share Storage na 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 se obraťte na opencode@microsoft.com případné další dotazy nebo komentáře.