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.

In questo articolo vengono illustrati 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 File di Azure.

Informazioni sullo sviluppo di app Python con File di Azure

File di Azure offre diversi modi per consentire agli sviluppatori di 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 le chiamate API a livello di sistema operativo tramite le condivisioni file Azure montate usando SMB o NFS. Quando si monta una condivisione file con 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 che hanno un codice esistente che usa le operazioni di I/O di file standard e non vuoi riscrivere il codice affinché 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. Il 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 Python librerie di I/O di file.
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 di File di Azure risorse usando gli approcci seguenti:

Prerequisiti

Impostare il progetto

Questa sezione illustra come preparare un progetto per l'uso del File di Azure.

Dalla directory del progetto installare i pacchetti in base alle esigenze dell'app usando il pip install comando . Nell'esempio seguente viene illustrato come installare la libreria client Azure condivisioni file, la libreria client di gestione archiviazione e la libreria Azure Identity. 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 le librerie Python os e io, aggiungere quanto segue al file .py:

import os
import io

Se prevedi di utilizzare la libreria client di condivisione file di Archiviazione di Azure, 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 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 usando le librerie di I/O dei file di Python

Le librerie di I/O di file standard sono il modo più comune per accedere e usare le risorse 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.

È consigliabile usare Python librerie di I/O dei file quando l'app richiede:

  • Compatibilità delle app: Ideale per le applicazioni aziendali con codice esistente che utilizza già librerie di I/O di file Python. Non è necessario riscrivere il codice affinché l'app funzioni con una condivisione file Azure.
  • Ease of use: Python librerie di I/O di file sono note dagli sviluppatori e facili da usare. Una proposta di valore chiave di File di Azure è che espone API native del file system tramite SMB e NFS.

In questa sezione viene illustrato come usare le librerie di I/O dei file Python per usare le risorse File di Azure.

Per altre informazioni ed esempi, vedere le risorse seguenti:

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

Montare una condivisione di file

Per usare le librerie di I/O di file di Python, è necessario prima montare una condivisione di 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 elencare le directory usando le librerie di I/O dei file di 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 in un file in una condivisione file usando le librerie di I/O di 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 elenchi di controllo di accesso (ACL) ai file usando le librerie di I/O dei file di 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)

Lavorare con i dati di File di Azure usando la libreria client File Shares per Python

L'API FileREST fornisce l'accesso a livello di codice alle 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. Il 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 a valore aggiunto personalizzati, 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 una 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 viene illustrato come usare la libreria client Condivisioni file per usare le risorse File di Azure.

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 lavorare con le risorse 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 a 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 da app ospitate Azure usando un'identità gestita
Ospitato 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 usare gli esempi di codice in questo articolo, assegnare all'entità di sicurezza il ruolo integrato Controllo degli Accessi basato sui Ruoli di Azure Storage File Data Privileged Contributor. 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 altre informazioni, vedere Accedi alle condivisioni file di Azure utilizzando Microsoft Entra ID con File di Azure OAuth 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 di 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 Azure Identity 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 su 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 un 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'autorizzazione sicura dell'accesso all'archiviazione, vedere Autorizzare l'accesso ai dati in Archiviazione di Azure.

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

Le librerie di gestione Archiviazione di Azure sono basate sull'API REST del provider di risorse Archiviazione di Azure. Il provider di risorse 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 Archiviazione di Azure fornisce l'accesso a livello di codice alle risorse Archiviazione di Azure, incluse le condivisioni file. Il Azure SDK fornisce librerie di gestione basate sull'API REST del provider di risorse Archiviazione di Azure.

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

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

L'esempio di codice seguente illustra come creare un oggetto ArmClient di primo livello, registrare il provider di risorse di archiviazione con una sottoscrizione e creare una condivisione file usando la libreria di gestione 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 Azure RBAC: Microsoft.Storage/register/action. Questa autorizzazione è inclusa nei ruoli predefiniti Collaboratore e Proprietario.

Esempio: Elencare condivisioni file e snapshot usando la libreria di gestione 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:

  • Last updated on