Condividi tramite

Sviluppare per File di Azure con Python

Informazioni su come sviluppare applicazioni Python che usano File di Azure per archiviare i dati. File di Azure è un servizio di condivisione file gestito nel cloud. Fornisce condivisioni file completamente gestite accessibili tramite i protocolli SMB (Server Message Block) e NFS (Network File System) standard del settore. File di Azure fornisce anche un'API REST per l'accesso a livello di codice alle condivisioni file.

Questo articolo illustra i diversi approcci allo sviluppo con File di Azure in Python e come scegliere l'approccio più adatto alle esigenze dell'app. Si apprenderà anche come creare un'app console di base che interagisce con le risorse di File di Azure.

Si applica a

Modello di gestione Modello di fatturazione Livello supporti Ridondanza SMB NFS
Microsoft.Storage Con provisioning v2 HDD (standard) Locale Sì No
Microsoft.Storage Con provisioning v2 HDD (standard) Della zona Sì No
Microsoft.Storage Con provisioning v2 HDD (standard) Geografica Sì No
Microsoft.Storage Con provisioning v2 HDD (standard) GeoZone (GZRS) Sì No
Microsoft.Storage Con provisioning v1 SSD (Premium) Locale Sì No
Microsoft.Storage Con provisioning v1 SSD (Premium) Della zona Sì No
Microsoft.Storage Pagamento in base al consumo HDD (standard) Locale Sì No
Microsoft.Storage Pagamento in base al consumo HDD (standard) Della zona Sì No
Microsoft.Storage Pagamento in base al consumo HDD (standard) Geografica Sì No
Microsoft.Storage Con pagamento in base al consumo HDD (standard) GeoZone (GZRS) Sì No

Informazioni sullo sviluppo di app Python con File di Azure

File di Azure offre diversi modi per consentire agli sviluppatori Python di accedere ai dati e gestire le risorse in File di Azure. La tabella seguente elenca gli approcci, riepiloga il funzionamento e fornisce indicazioni su quando usare ogni approccio:

Avvicinarsi Come funziona Quando utilizzare
Librerie di I/O file standard Usa chiamate API a livello di sistema operativo tramite condivisioni file di Azure montate usando SMB o NFS. Quando si monta una condivisione file usando SMB/NFS, è possibile usare librerie di I/O di file per un linguaggio di programmazione o un framework, ad esempio os e io per Python. Hai app line-of-business con codice esistente che utilizza l'I/O di file standard e non vuoi riscrivere il codice per far sì che l'app funzioni con una condivisione file di Azure.
FileREST API Chiama direttamente gli endpoint HTTPS per interagire con i dati archiviati in File di Azure. Fornisce il controllo a livello di codice sulle risorse di condivisione file. Azure SDK fornisce la libreria client condivisioni file (azure-storage-file-share) basata sull'API FileREST, consentendo di interagire con le operazioni dell'API FileREST tramite paradigmi noti del linguaggio di programmazione Python. Si creano servizi cloud e app a valore aggiunto per i clienti e si vogliono usare funzionalità avanzate non disponibili tramite le librerie di I/O dei file Python.
API REST del provider di risorse di archiviazione Usa Azure Resource Manager (ARM) per gestire gli account di archiviazione e le condivisioni file. Chiama gli endpoint DELL'API REST per varie operazioni di gestione delle risorse. L'app o il servizio deve eseguire attività di gestione delle risorse, ad esempio la creazione, l'eliminazione o l'aggiornamento di account di archiviazione o condivisioni file.

Per informazioni generali su questi approcci, vedere Panoramica dello sviluppo di applicazioni con File di Azure.

Questo articolo è incentrato sull'uso delle risorse di File di Azure usando gli approcci seguenti:

Prerequisiti

Impostare il progetto

Questa sezione illustra come preparare un progetto per lavorare con File di Azure.

Dalla directory del progetto installare i pacchetti in base alle esigenze dell'app usando il pip install comando . L'esempio seguente illustra come installare la libreria client condivisioni file di Azure, la libreria client di gestione archiviazione e la libreria di identità di Azure. Il pacchetto azure-identity è necessario per le connessioni senza password ai servizi di Azure.

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

Aprire il file di codice e aggiungere le istruzioni import necessarie.

Se si prevede di usare Python os e io le librerie, aggiungere quanto segue al file .py :

import os
import io

Se hai intenzione di utilizzare la libreria client per le condivisioni file di Azure Storage, aggiungi quanto segue al file .py :

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

Se si prevede di usare le librerie di gestione di Archiviazione di Azure, aggiungere quanto segue al file .py :

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

Usare File di Azure con le librerie Python per l'I/O dei file

Le librerie di I/O di file standard sono il modo più comune per accedere e usare le risorse di File di Azure. Quando si monta una condivisione file usando SMB o NFS, il sistema operativo reindirizza le richieste API per il file system locale. Questo approccio consente di usare librerie di I/O di file standard, ad esempio os o io, per interagire con file e directory nella condivisione.

Prendere in considerazione l'uso delle librerie di I/O dei file Python quando l'app richiede:

  • Compatibilità delle app: Ideale per le app line-of-business con codice esistente che usa già librerie di I/O di file Python. Non è necessario riscrivere il codice affinché l'app funzioni con una condivisione file di Azure.
  • Facilità d'uso: Le librerie di I/O dei file Python sono note dagli sviluppatori e facili da usare. Una proposta di valore chiave di File di Azure consiste nell'esposizione delle API del file system native tramite SMB e NFS.

In questa sezione si apprenderà come usare le librerie di I/O dei file Python per usare le risorse di File di Azure.

Per altre informazioni ed esempi, vedere le risorse seguenti:

  • Librerie Python per I/O di file: os e io

Montare una condivisione di file

Per usare le librerie di I/O dei file Python, è prima necessario montare una condivisione file. Per indicazioni su come montare una condivisione file con SMB o NFS, vedere le risorse seguenti:

In questo articolo viene usato il percorso seguente per fare riferimento a una condivisione file SMB montata in Windows:

file_share_path = "Z:\\file-share"

Esempio: Connettersi a una condivisione file ed enumerare le directory usando le librerie di I/O dei file Python

Nell'esempio di codice seguente viene illustrato come connettersi a una condivisione file ed elencare le directory nella condivisione:

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)

Esempio: Scrivere su un file in una condivisione file usando le librerie di I/O per file di Python

Nell'esempio di codice seguente viene illustrato come scrivere e aggiungere testo a un file:

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

Esempio: Enumerare gli ACL di file usando le librerie di I/O dei file Python

Nell'esempio di codice seguente viene illustrato come enumerare elenchi di controllo di accesso di base (ACL) per un file:

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)

Usare i dati di File di Azure usando la libreria client Condivisioni file per Python

L'API FileREST fornisce l'accesso a livello di codice a File di Azure. Consente di chiamare gli endpoint HTTPS per eseguire operazioni su condivisioni file, directory e file. L'API FileREST è progettata per funzionalità avanzate e scalabilità elevate che potrebbero non essere disponibili tramite protocolli nativi. Azure SDK fornisce librerie client, ad esempio la libreria client condivisioni file per Python, che si basano sull'API FileREST.

È consigliabile usare l'API FileREST e la libreria client di condivisione file se l'applicazione richiede:

  • Funzionalità avanzate: Operazioni di accesso e funzionalità non disponibili tramite protocolli nativi.
  • Integrazioni cloud personalizzate: Creare servizi personalizzati a valore aggiunto, ad esempio backup, antivirus o gestione dei dati, che interagiscono direttamente con File di Azure.
  • Ottimizzazione delle prestazioni: Sfruttare i vantaggi delle prestazioni in scenari su larga scala usando le operazioni del piano dati.

L'API FileREST modella File di Azure come gerarchia di risorse ed è consigliata per le operazioni eseguite a livello di directory o file . È consigliabile preferire l'API REST del provider di risorse di archiviazione per le operazioni eseguite a livello di servizio file o condivisione file .

In questa sezione si apprenderà come utilizzare la libreria client File Shares per gestire le risorse di Azure Files.

Per altre informazioni ed esempi, vedere le risorse seguenti:

Autorizzare l'accesso e creare un client

Per connettere un'app a File di Azure, creare un oggetto ShareClient. Questo oggetto è il punto di partenza per l'uso delle risorse di File di Azure. Negli esempi di codice seguenti viene illustrato come creare un ShareClient oggetto usando meccanismi di autorizzazione diversi.

Per autorizzare con Microsoft Entra ID è necessario usare un'entità di sicurezza. Il tipo di entità di sicurezza necessaria dipende dalla posizione in cui viene eseguita l'app. Usare questa tabella come riferimento.

Posizione in cui viene eseguita l'applicazione Entità di sicurezza Indicazioni
Computer locale (sviluppo e test) Service Principal Per informazioni su come registrare l'app, configurare un gruppo di Microsoft Entra, assegnare ruoli e configurare le variabili di ambiente, vedere Autorizzare l'accesso usando le entità servizio per sviluppatori
Computer locale (sviluppo e test) Identità utente Per informazioni su come configurare un gruppo di Microsoft Entra, assegnare ruoli e accedere ad Azure, vedere Autorizzare l'accesso usando le credenziali per sviluppatori
Ospitato su Azure Identità gestita Per informazioni su come abilitare l'identità gestita e assegnare ruoli, vedere Autorizzare l'accesso dalle app ospitate in Azure usando un'identità gestita
Ospitata all'esterno di Azure (ad esempio, app locali) Service Principal Per informazioni su come registrare l'app, assegnare ruoli e configurare le variabili di ambiente, vedere Autorizzare l'accesso dalle app locali usando un'entità servizio dell'applicazione

Per lavorare con gli esempi di codice in questo articolo, assegnare all'entità di sicurezza il ruolo predefinito di Controllo degli accessi in base al ruolo di Azure Collaboratore con privilegi per i dati dei file di archiviazione. Questo ruolo fornisce l'accesso completo in lettura, scrittura, modifica ACL ed eliminazione su tutti i dati nelle condivisioni per tutti gli account di archiviazione configurati, indipendentemente dalle autorizzazioni NTFS impostate a livello di file/directory. Per ulteriori informazioni, vedere Accedere alle condivisioni file di Azure utilizzando Microsoft Entra ID con OAuth Files di Azure tramite REST.

Autorizzare l'accesso con DefaultAzureCredential

Un modo semplice e sicuro per autorizzare l'accesso e connettersi a File di Azure consiste nel ottenere un token OAuth creando un'istanza DefaultAzureCredential . È quindi possibile usare tale credenziale per creare un ShareClient oggetto .

Nell'esempio seguente viene creato un ShareClient oggetto autorizzato usando DefaultAzureCredential, quindi viene creato un ShareDirectoryClient oggetto per lavorare con una directory nella condivisione:

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

Se si conosce esattamente il tipo di credenziale usato per autenticare gli utenti, è possibile ottenere un token OAuth usando altre classi nella libreria client di Identità di Azure per Python. Queste classi derivano dalla classe TokenCredential.

Per altre informazioni su ognuno di questi meccanismi di autorizzazione, vedere Scegliere come autorizzare l'accesso ai dati dei file.

Esempio: Copiare file usando la libreria client Condivisioni file

È possibile copiare file all'interno di una condivisione file o tra condivisioni file usando il metodo seguente:

È possibile copiare un file in un BLOB di destinazione usando il metodo seguente da un BlobClient oggetto :

Nell'esempio di codice seguente viene illustrato come copiare un file in un file in un'altra condivisione file:

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)

Esempio: Creare un lease su un file usando la libreria client di Condivisioni file

Un lease crea un blocco in un file gestito da Azure tramite un ID lease. Il lease fornisce un meccanismo per coordinare l'accesso ai file tra più client in un sistema distribuito. Un lease su un file fornisce accesso esclusivo in scrittura ed eliminazione. Per altre informazioni sugli stati di lease e sulle azioni, vedere File di lease.

L'esempio di codice seguente illustra come creare un client di lease, acquisire un lease di durata infinito in un file e rilasciare il lease:

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

Quando si usano sia SMB che l'API FileREST, tenere presente che l'API FileREST usa lease per gestire i blocchi di file, mentre SMB usa blocchi del file system gestiti dal sistema operativo. Per altre informazioni sulla gestione delle interazioni di blocco dei file tra SMB e l'API FileREST, vedere Gestire i blocchi di file.

Esempio: creare ed elencare snapshot di condivisioni usando la libreria client di Condivisioni file

Gli snapshot di condivisione sono copie di sola lettura di una condivisione file in un momento specifico. È possibile creare uno snapshot di una condivisione file e quindi usare lo snapshot per accedere ai dati nella condivisione al momento della creazione dello snapshot. È anche possibile elencare tutti gli snapshot in una condivisione file ed eliminare gli snapshot di condivisione.

L'esempio di codice seguente illustra come creare uno snapshot di condivisione, elencare gli snapshot in una condivisione di file e navigare all'interno della directory radice di uno snapshot di condivisione.

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)

Annotazioni

I token OAuth, ad esempio quelli ottenuti quando si usa DefaultAzureCredential, non sono consentiti per le operazioni del piano dati a livello di condivisione file. Per usare gli snapshot di condivisione, l'oggetto client deve essere autorizzato usando la chiave dell'account. L'oggetto ShareClient creato in questo esempio di codice usa una stringa di connessione, che include la chiave dell'account.

L'archiviazione delle chiavi dell'account o delle stringhe di connessione presenta un rischio per la sicurezza. È consigliabile usarli solo quando l'autenticazione di Microsoft Entra non è disponibile. Per altre informazioni sull'archiviazione sicura delle chiavi dell'account in Azure Key Vault, vedere Informazioni sulle chiavi dell'account di archiviazione gestito di Azure Key Vault.

Gestire le risorse di File di Azure usando le librerie di gestione di Archiviazione di Azure

Le librerie di gestione di Archiviazione di Azure sono basate sull'API REST del provider di risorse di Archiviazione di Azure. Il provider di risorse di Archiviazione di Azure è un servizio basato su Azure Resource Manager e supporta sia metodi dichiarativi (modelli) che imperativi (chiamata API diretta). L'API REST del provider di risorse di Archiviazione di Azure fornisce l'accesso a livello di codice alle risorse di Archiviazione di Azure, incluse le condivisioni file. Azure SDK offre librerie di gestione basate sull'API REST del provider di risorse di Archiviazione di Azure.

Le librerie di gestione sono consigliate per le operazioni eseguite a livello di servizio file o condivisione file . In questa sezione si apprenderà come usare le librerie di gestione di Archiviazione di Azure per gestire le risorse di File di Azure.

Esempio: Creare una condivisione file usando la libreria di gestione di Archiviazione di Azure

L'esempio di codice seguente illustra come creare un oggetto di primo livello ArmClient , registrare il provider di risorse di archiviazione con una sottoscrizione e creare una condivisione file usando la libreria di gestione di Archiviazione di Azure:

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

È possibile configurare le proprietà della condivisione file usando la FileShare classe . Nell'esempio precedente viene illustrato come impostare la share_quota proprietà . Per altre informazioni, vedere le informazioni di riferimento sulla classe StorageManagementClient .

Annotazioni

Per eseguire l'operazione di registrazione, sono necessarie le autorizzazioni per la seguente azione RBAC di Azure: Microsoft.Storage/register/action. Questa autorizzazione è inclusa nei ruoli predefiniti Collaboratore e Proprietario.

Esempio: Elencare condivisioni file e snapshot usando la libreria di gestione di Archiviazione di Azure

L'esempio di codice seguente illustra come elencare condivisioni file e snapshot in un account di archiviazione:

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

Contenuto correlato

Per altre informazioni sullo sviluppo con File di Azure, vedere le risorse seguenti: