Vývoj pro Azure Files s využitím Python

Naučte se vyvíjet Python aplikace, které k ukládání dat používají Azure Files. Azure Files je spravovaná sdílená služba v cloudu. Poskytuje plně spravované sdílené složky, které jsou přístupné prostřednictvím standardních protokolů SMB (Server Message Block) a NFS (Network File System). Azure Files také poskytuje rozhraní REST API pro programový přístup ke sdíleným složkám.

V tomto článku se dozvíte o různých přístupech k vývoji pomocí Azure Files v Python a o tom, jak zvolit přístup, který nejlépe vyhovuje potřebám vaší aplikace. Dozvíte se také, jak vytvořit základní konzolovou aplikaci, která komunikuje s Azure Files prostředky.

Informace o vývoji Python aplikací pomocí Azure Files

Azure Files nabízí několik způsobů, jak Python vývojářům přistupovat k datům a spravovat prostředky v Azure Files. Následující tabulka uvádí přístupy, shrnuje jejich fungování a poskytuje pokyny k použití jednotlivých přístupů:

Přístup Jak to funguje Kdy použít
Standardní vstupně-výstupní knihovny souborů Používá volání rozhraní API na úrovni operačního systému prostřednictvím Azure sdílených složek připojených pomocí protokolu SMB nebo NFS. Při připojování sdílené složky pomocí protokolu SMB/NFS můžete pro programovací jazyk nebo architekturu použít knihovny vstupně-výstupních operací souborů, například os a io pro Python. Máte obchodní aplikace se stávajícím kódem, který používá standardní vstupně-výstupní operace se soubory a nechcete přepsat kód pro aplikaci, aby fungovala se sdílenou složkou Azure.
FileREST API Přímé volání koncových bodů HTTPS pro interakci s daty uloženými v Azure Files. Poskytuje programové řízení nad zdroji sdílených složek. Azure SDK poskytuje klientskou knihovnu sdílených složek (azure-storage-file-share), která je založená na rozhraní FileREST API, což umožňuje interakci s operacemi rozhraní FileREST API prostřednictvím známých paradigmat programovacího jazyka Python. Vytváříte cloudové služby a aplikace přidané hodnotou pro zákazníky a chcete používat pokročilé funkce, které nejsou dostupné prostřednictvím Python vstupně-výstupních knihoven souborů.
REST API poskytovatele pro úložiště Používá Azure Resource Manager (ARM) ke správě účtů úložiště a sdílených složek. Volá koncové body rozhraní REST API pro různé operace správy prostředků. Aplikace nebo služba musí provádět úlohy správy prostředků, jako je vytváření, odstraňování nebo aktualizace účtů úložiště nebo sdílených složek.

Obecné informace o těchto přístupech najdete v tématu Přehled vývoje aplikací pomocí Azure Files.

Tento článek se zaměřuje na práci s Azure Files prostředky s využitím následujících přístupů:

Požadavky

Nastavení projektu

Tato část vás provede přípravou projektu pro práci s Azure Files.

Z adresáře projektu nainstalujte balíčky na základě potřeb vaší aplikace pomocí pip install příkazu. Následující příklad ukazuje, jak nainstalovat klientskou knihovnu Azure sdílených složek, klientskou knihovnu správy úložiště a knihovnu identit Azure. Balíček azure-identity je potřeba pro připojení bez hesla ke službám Azure.

pip install azure-identity
pip install azure-storage-file-share
pip install azure-mgmt-resource
pip install azure-mgmt-storage

Otevřete soubor kódu a přidejte potřebné příkazy importu.

Pokud plánujete používat knihovny Python a , přidejte do souboru .py2 následující:

import os
import io

Pokud plánujete používat klientskou knihovnu Azure Storage File Shares, přidejte do souboru .py následující:

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareClient, ShareDirectoryClient, ShareFileClient

Pokud plánujete používat knihovny pro správu Azure Storage, přidejte do souboru .py následující:

from azure.identity import DefaultAzureCredential
from azure.mgmt.resource import ResourceManagementClient
from azure.mgmt.storage import StorageManagementClient

Práce s Azure Files pomocí vstupně-výstupních knihoven souborů Python

Standardní vstupně-výstupní knihovny souborů představují nejběžnější způsob přístupu k prostředkům Azure Files a práci s nich. Když připojíte sdílenou složku pomocí protokolu SMB nebo NFS, váš operační systém přesměruje požadavky rozhraní API pro místní systém souborů. Tento přístup umožňuje používat standardní vstupně-výstupní knihovny souborů, například os nebo io, pro interakci se soubory a adresáři ve sdílené složce.

Pokud vaše aplikace vyžaduje, zvažte použití Python vstupně-výstupních knihoven souborů:

  • Kompatibilita aplikací: Ideální pro obchodní aplikace s existujícím kódem, který už používá Python vstupně-výstupní knihovny souborů. Aby aplikace fungovala se sdílenou složkou Azure, nemusíte přepisovat kód.
  • Aze použití: Python vstupně-výstupní knihovny souborů jsou dobře známé a snadno se používají. Návrh klíčové hodnoty Azure Files spočívá v tom, že zpřístupňuje nativní rozhraní API systému souborů prostřednictvím protokolu SMB a NFS.

V této části se dozvíte, jak používat vstupně-výstupní knihovny pro Python ke zpracování prostředků Azure Files.

Další informace a příklady najdete v následujících zdrojích informací:

  • knihovny Python pro vstupně-výstupní operace souborů: os a io

Připojit sdílenou složku

Pokud chcete použít Python vstupně-výstupní knihovny souborů, musíte nejprve připojit sdílenou složku. Pokyny k připojení sdílené složky pomocí protokolu SMB nebo NFS najdete v následujících zdrojích informací:

V tomto článku používáme následující cestu, která odkazuje na připojenou sdílenou složku SMB na Windows:

file_share_path = "Z:\\file-share"

Příklad: Připojení ke sdílené složce a vytvoření výčtu adresářů pomocí Python vstupně-výstupních knihoven souborů

Následující příklad kódu ukazuje, jak se připojit ke sdílené složce a zobrazit seznam adresářů ve sdílené složce:

import os

def enumerate_directories(path):
    try:
        # Get all directories in the specified path
        dirs = [d for d in os.listdir(path) if os.path.isdir(os.path.join(path, d))]
        
        # Print each directory name
        for dir_name in dirs:
            print(f"{dir_name}")
            
        print(f"{len(dirs)} directories found.")
    except (PermissionError, FileNotFoundError, OSError) as ex:
        print(f"Error: {ex}")

#Example usage
file_share_path = "Z:\\file-share"
enumerate_directories(file_share_path)

Příklad: Zápis do souboru ve sdílené složce pomocí Python vstupně-výstupních knihoven souborů

Následující příklad kódu ukazuje, jak zapisovat a připojovat text k souboru:

import os

def write_to_file(file_share_path, file_name):
    # First line of text with platform-appropriate line ending
    text_to_write = "First line" + os.linesep
    
    # Combine the file share path and filename
    file_path = os.path.join(file_share_path, file_name)
    
    # Write initial text to file (overwrites if file exists)
    with open(file_path, 'w') as file:
        file.write(text_to_write)
    
    # Text to append
    text_to_append = ["Second line", "Third line"]
    
    # Append lines to the file
    with open(file_path, 'a') as file:
        file.write(os.linesep.join(text_to_append) + os.linesep)

# Example usage
file_share_path = "Z:\\file-share"
write_to_file(file_share_path, "test.txt")

Příklad: Výčet seznamů ACL souborů pomocí Python vstupně-výstupních knihoven souborů

Následující příklad kódu ukazuje, jak vytvořit výčet seznamů řízení přístupu (ACL) pro soubor:

import os
import stat

def enumerate_file_acls(file_path):
    try:
        # Get file stats
        file_stat = os.stat(file_path)
        
        # Get permissions in octal format
        permissions_octal = oct(stat.S_IMODE(file_stat.st_mode))
        
        print(f"File: {file_path}")
        print(f"Permissions (octal): {permissions_octal}")
        
        # Interpret permissions in a human-readable format
        permissions = ""
        permissions += "r" if file_stat.st_mode & stat.S_IRUSR else "-"
        permissions += "w" if file_stat.st_mode & stat.S_IWUSR else "-"
        permissions += "x" if file_stat.st_mode & stat.S_IXUSR else "-"
        permissions += "r" if file_stat.st_mode & stat.S_IRGRP else "-"
        permissions += "w" if file_stat.st_mode & stat.S_IWGRP else "-" 
        permissions += "x" if file_stat.st_mode & stat.S_IXGRP else "-"
        permissions += "r" if file_stat.st_mode & stat.S_IROTH else "-"
        permissions += "w" if file_stat.st_mode & stat.S_IWOTH else "-"
        permissions += "x" if file_stat.st_mode & stat.S_IXOTH else "-"
        
        print(f"Permissions (symbolic): {permissions}")
        
        print(f"Owner ID: {file_stat.st_uid}")
        print(f"Group ID: {file_stat.st_gid}")
        print("Note: For detailed Windows ACLs, you may need a specialized library.")
        
    except FileNotFoundError:
        print(f"Error: File '{file_path}' not found.")
    except PermissionError:
        print(f"Error: Permission denied for '{file_path}'.")
    except Exception as e:
        print(f"Error: {e}")

# Example usage
file_share_path = "Z:\\file-share"
file_name = "test.txt"
file_path = os.path.join(file_share_path, file_name)

enumerate_file_acls(file_path)

Práce s daty Azure Files pomocí klientské knihovny sdílených složek pro Python

Rozhraní FileREST API poskytuje programový přístup k Azure Files. Umožňuje volat koncové body HTTPS, které provádějí operace se sdílenými složkami, adresáři a soubory. Rozhraní FileREST API je navržené pro vysokou škálovatelnost a pokročilé funkce, které nemusí být dostupné prostřednictvím nativních protokolů. Azure SDK poskytuje klientské knihovny, jako je klientská knihovna sdílených složek pro Python, která vychází z rozhraní FileREST API.

Pokud vaše aplikace vyžaduje, zvažte použití rozhraní FileREST API a klientské knihovny sdílené složky:

  • Pokročilé funkce: Přístup k operacím a funkcím, které nejsou dostupné prostřednictvím nativních protokolů.
  • Správa cloudových integrací: Vytváření vlastních služeb s přidanou hodnotou, jako je zálohování, antivirový program nebo správa dat, které komunikují přímo s Azure Files.
  • Optimalizace výkonu: Využijte výhod výkonu ve scénářích s vysokým měřítkem pomocí operací roviny dat.

FileREST API modeluje Azure Files jako hierarchii prostředků a doporučuje se pro operace, které jsou prováděny na úrovni adresáře nebo souboru. Pro operace prováděné na úrovni souborové služby nebo sdílené složky byste měli preferovat rozhraní REST API poskytovatele prostředků úložiště.

V této části se dozvíte, jak používat klientskou knihovnu File Shares k práci s prostředky služby Azure Files.

Další informace a příklady najdete v následujících zdrojích informací:

Autorizace přístupu a vytvoření klienta

Pokud chcete připojit aplikaci k Azure Files, vytvořte objekt ShareClient. Tento objekt je vaším výchozím bodem pro práci s prostředky Azure Files. Následující příklady kódu ukazují, jak vytvořit ShareClient objekt pomocí různých mechanismů autorizace.

Pokud chcete autorizovat pomocí Microsoft Entra ID, musíte použít bezpečnostní principál. Typ požadovaného objektu zabezpečení závisí na tom, kde vaše aplikace běží. Tuto tabulku použijte jako vodítko.

Kde aplikace běží Principál zabezpečení Vodítko
Místní počítač (vývoj a testování) Hlavní služba Informace o registraci aplikace, nastavení skupiny Microsoft Entra, přiřazení rolí a konfiguraci proměnných prostředí naleznete v části Autorizace přístupu pomocí zástupců služby pro vývojáře.
Místní počítač (vývoj a testování) Identita uživatele Informace o nastavení skupiny Microsoft Entra, přiřazení rolí a přihlášení k Azure najdete v tématu Authorize přístupu pomocí přihlašovacích údajů vývojáře
Hostované v Azure Spravovaná identita Informace o povolení spravované identity a přiřazování rolí najdete v tématu Authorize přístupu z Azure hostovaných aplikací pomocí spravované identity
Hostované mimo Azure (například místní aplikace) Hlavní služba Informace o registraci aplikace, přiřazení rolí a konfiguraci proměnných prostředí najdete v tématu Autorizace přístupu z místních aplikací pomocí instančního objektu aplikace.

Pokud chcete pracovat s příklady kódu v tomto článku, přiřaďte k objektu zabezpečení předdefinovanou roli Azure RBAC Storage File Data Privileged Contributor. Tato role poskytuje úplný přístup ke čtení, zápisu, úpravě seznamů ACL a odstraňování všech dat ve sdílených složkách pro všechny nakonfigurované účty úložiště bez ohledu na nastavená oprávnění NTFS na úrovni souboru nebo adresáře. Další informace najdete v tématu K přístupu ke sdíleným složkám Azure pomocí Microsoft Entra ID s Azure Files OAuth pomocí REST.

Autorizace přístupu pomocí DefaultAzureCredential

Snadným a bezpečným způsobem autorizace přístupu a připojení k Azure Files je získání tokenu OAuth vytvořením instance DefaultAzureCredential. Tyto přihlašovací údaje pak můžete použít k vytvoření objektu ShareClient .

Následující příklad vytvoří ShareClient objekt autorizovaný pomocí DefaultAzureCredentiala pak vytvoří ShareDirectoryClient objekt pro práci s adresářem ve sdílené složce:

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareClient

account_name = "<account-name>"
share_name = "<share-name>"

# Create the share client using DefaultAzureCredential
share_client = ShareClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=share_name,
    credential=DefaultAzureCredential(),
    # When using a token credential, you MUST specify a token_intent
    token_intent='backup'
)

# Get a reference to a directory in the share
directory_client = share_client.get_directory_client("sample-directory")

Pokud přesně víte, jaký typ přihlašovacích údajů používáte k ověřování uživatelů, můžete token OAuth získat pomocí jiných tříd v klientské knihovně Azure Identity pro Python. Tyto třídy jsou odvozeny z TokenCredential třídy.

Další informace o každém z těchto mechanismů autorizace najdete v tématu Volba způsobu autorizace přístupu k datům souborů.

Příklad: Kopírování souborů pomocí klientské knihovny sdílených složek

Soubory ve sdílené složce nebo mezi sdílenými složkami můžete kopírovat pomocí následující metody:

Pomocí následující metody z objektu BlobClient můžete zkopírovat soubor do cílového objektu blob.

Následující příklad kódu ukazuje, jak zkopírovat soubor do souboru v jiné sdílené složce:

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareFileClient

# Define storage account parameters
account_name = "<account-name>"
src_share_name = "src-file-share"
dest_share_name = "dest-file-share"
src_file_path = "src/path/to/file"
dest_file_path = "dest/path/to/file"

# Create token credential
token_credential = DefaultAzureCredential()

# Create source file client
src_file_client = ShareFileClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=src_share_name,
    file_path=src_file_path,
    credential=token_credential,
    token_intent='backup'
)

# Create destination file client
dest_file_client = ShareFileClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=dest_share_name,
    file_path=dest_file_path,
    credential=token_credential,
    token_intent='backup'
)

# Copy the file from the source share to the destination share
copy_operation = dest_file_client.start_copy_from_url(src_file_client.url)

Příklad: Zapůjčení souboru pomocí klientské knihovny sdílených složek

Pronájem vytvoří zámek na souboru spravovaném Azure prostřednictvím ID pronájmu. Zapůjčení poskytuje mechanismus pro koordinaci přístupu k souborům napříč více klienty v distribuovaném systému. Zapůjčení souboru poskytuje výhradní přístup k zápisu a odstranění. Další informace o stavech a akcích zapůjčení najdete v tématu Soubor zapůjčení.

Následující příklad kódu ukazuje, jak vytvořit klienta zapůjčení, získat nekonečnou dobu zapůjčení souboru a uvolnit zapůjčení:

from azure.identity import DefaultAzureCredential
from azure.storage.fileshare import ShareFileClient, ShareLeaseClient

# Define storage account parameters
account_name = "<account-name>"
share_name = "sample-file-share"
file_path = "path/to/file"

# Create a DefaultAzureCredential for authentication
token_credential = DefaultAzureCredential()

# Create a ShareFileClient
file_client = ShareFileClient(
    account_url=f"https://{account_name}.file.core.windows.net",
    share_name=share_name,
    file_path=file_path,
    credential=token_credential,
    token_intent='backup'
)

# Get a lease client for the file
lease_client = ShareLeaseClient(file_client)

# Acquire an infinite duration lease on the file
lease_info = lease_client.acquire()

# Do something with the file while it's leased
# ...

# Release the lease
lease_client.release()

Při použití protokolu SMB i FileREST API mějte na paměti, že FileREST API používá ke správě zámků souborů leasing, zatímco SMB používá zámky systému souborů spravované operačním systémem. Další informace o správě interakcí uzamčení souborů mezi protokolem SMB a rozhraním FileREST API najdete v tématu Správa zámků souborů.

Příklad: Vytvoření a výpis snímků sdílených složek pomocí klientské knihovny sdílených složek

Snímky sdílené složky jsou kopie sdílené složky jen pro čtení v určitém okamžiku. Můžete vytvořit snímek sdílené složky a pak pomocí snímku získat přístup k datům ve sdílené složce v okamžiku vytvoření snímku. Můžete také zobrazit seznam všech snímků ve sdílené složce a odstranit snímky sdílené složky.

Následující příklad kódu ukazuje, jak vytvořit snímek sdílené složky, vypsat snímky ve sdílené složce a procházet kořenový adresář ve snímku sdílené složky:

from azure.storage.fileshare import ShareServiceClient, ShareDirectoryClient

def list_root_directory_snapshot(root_dir: ShareDirectoryClient):
    for item in root_dir.list_directories_and_files():
        if item["is_directory"]:
            print(f"Directory in snapshot: {item['name']}")
        else:
            print(f"File in snapshot: {item['name']}")

# Connection string with account key (required for share snapshots)
connection_string = "<connection-string>"

# Create service and share clients
share_service_client = ShareServiceClient.from_connection_string(connection_string)
share_name = "sample-file-share"
share_client = share_service_client.get_share_client(share_name)

# Create a snapshot
snapshot_info = share_client.create_snapshot()
print(f"Snapshot created: {snapshot_info['snapshot']}")

# List snapshots in a share
for share_item in share_service_client.list_shares(include_snapshots=True):
    if share_item["snapshot"]:
        print(f"Share: {share_item['name']} (Snapshot: {share_item['snapshot']})")

# List directories and files in a share snapshot
snapshot_timestamp = snapshot_info["snapshot"]
share_snapshot = share_service_client.get_share_client(share_name, snapshot=snapshot_timestamp)
root_dir = share_snapshot.get_directory_client("")

list_root_directory_snapshot(root_dir)

Poznámka:

Tokeny OAuth, jako jsou tokeny získané při použití DefaultAzureCredential, nejsou povolené pro operace roviny dat na úrovni sdílené složky. Aby bylo možné pracovat se snímky sdílených složek, musí být klientský objekt autorizovaný pomocí klíče účtu. Objekt ShareClient vytvořený v tomto příkladu kódu používá connection string, který obsahuje klíč účtu.

Ukládání klíčů účtu nebo připojovacích řetězců představuje bezpečnostní riziko. Měli byste je použít jenom v případě, že není k dispozici ověřování Microsoft Entra. Další informace o bezpečné autorizaci přístupu k úložišti najdete v tématu Authorize přístupu k datům v Azure Storage.

Správa Azure Files prostředků pomocí knihoven pro správu Azure Storage

Knihovny pro správu Azure Storage jsou založené na rozhraní REST API poskytovatele prostředků Azure Storage. Poskytovatel prostředků Azure Storage je služba založená na Azure Resource Manager a podporuje deklarativní (šablony) i imperativní metody (přímé volání rozhraní API). Rozhraní REST API poskytovatele prostředků Azure Storage poskytuje programový přístup k prostředkům Azure Storage, včetně sdílených složek. Azure SDK poskytuje knihovny pro správu, které vycházejí z rozhraní REST API poskytovatele prostředků Azure Storage.

Knihovny pro správu se doporučují pro operace prováděné na úrovni souborové služby nebo sdílené složky . V této části se dozvíte, jak používat knihovny pro správu Azure Storage ke správě Azure Files prostředků.

Příklad: Vytvoření sdílené složky pomocí knihovny pro správu Azure Storage

Následující příklad kódu ukazuje, jak vytvořit objekt nejvyšší úrovně ArmClient, zaregistrovat poskytovatele prostředků úložiště s předplatným a vytvořit sdílenou složku pomocí knihovny pro správu Azure Storage:

from azure.identity import DefaultAzureCredential
from azure.mgmt.resource import ResourceManagementClient, SubscriptionClient
from azure.mgmt.storage import StorageManagementClient
from azure.mgmt.storage.models import FileShare

# Create the credential for authentication
credential = DefaultAzureCredential()

# Define variables
subscription_id = "<subscription-id>"
resource_group_name = "<resource-group-name>"
storage_account_name = "<storage-account-name>"
share_name = "sample-file-share"

# Create clients
resource_client = ResourceManagementClient(credential, subscription_id)
subscription_client = SubscriptionClient(credential)
storage_client = StorageManagementClient(credential, subscription_id)

# Register Microsoft.Storage resource provider, if not already registered
provider = resource_client.providers.get('Microsoft.Storage')
if provider.registration_state == "NotRegistered":
    resource_client.providers.register('Microsoft.Storage')

# Create a file share
file_share = storage_client.file_shares.create(
    resource_group_name=resource_group_name,
    account_name=storage_account_name,
    share_name=share_name,
    file_share=FileShare(
        share_quota=1  # Share size in GiB
        # Add other file share properties here
    )
)

Vlastnosti sdílené složky můžete nakonfigurovat pomocí FileShare třídy. Předchozí příklad ukazuje, jak nastavit share_quota vlastnost. Další informace najdete v referenčních informacích ke třídě StorageManagementClient .

Poznámka:

K provedení operace registrace potřebujete oprávnění pro následující akci Azure RBAC: Microsoft.Storage/register/action. Toto oprávnění je součástí předdefinovaných rolí Přispěvatel a Vlastník.

Příklad: Výpis sdílených složek a snímků pomocí knihovny pro správu Azure Storage

Následující příklad kódu ukazuje, jak zobrazit seznam sdílených složek a snímků v účtu úložiště:

from azure.identity import DefaultAzureCredential
from azure.mgmt.storage import StorageManagementClient

# Create the credential for authentication
credential = DefaultAzureCredential()

# Define variables
subscription_id = "<subscription-id>"
resource_group_name = "<resource-group-name>"
storage_account_name = "<storage-account-name>"
expand = "snapshots"  # Include snapshots in the response

# Create storage management client
storage_client = StorageManagementClient(credential, subscription_id)

# List all file shares with their snapshots
file_shares = storage_client.file_shares.list(
    resource_group_name=resource_group_name,
    account_name=storage_account_name,
    expand=expand
)

# Iterate over the file shares and print them along with any snapshots
for share in file_shares:
    print(f"Resource name: {share.name}")
    if share.snapshot_time:
        print(f"Snapshot: {share.snapshot_time}")

Související obsah

Další informace o vývoji pomocí Azure Files najdete v následujících zdrojích informací:

  • Last updated on