Condividi tramite

Libreria client di Condivisione file di Archiviazione di Azure per Python - versione 12.15.0

  • Articolo

L'archiviazione condivisione file di Azure offre condivisioni file completamente gestite nel cloud accessibili tramite il protocollo SMB (Server Message Block) standard del settore. Le condivisioni file di Azure possono essere montate simultaneamente da distribuzioni cloud o locali di Windows, macOS e Linux. Le condivisioni file di Azure possono essere anche memorizzate nella cache in Windows Server con Sincronizzazione file di Azure per l'accesso rapido nelle vicinanze del punto in cui vengono usati i dati.

Le condivisioni file di Azure possono essere usate per:

  • Sostituire o integrare file server locali
  • Applicazioni "Lift and shift"
  • Semplificare lo sviluppo cloud con impostazioni dell'applicazione condivise, condivisione di diagnostica e strumenti di sviluppo/test/debug

Codice | sorgentePacchetto (PyPI) | Pacchetto (Conda) | Documentazione | di riferimento sulle APIDocumentazione | del prodottoCampioni

Introduzione

Prerequisiti

Installare il pacchetto

Installare la libreria client di Condivisione file di Archiviazione di Azure per Python con pip:

pip install azure-storage-file-share

Creare un account di archiviazione

Se si vuole creare un nuovo account di archiviazione, è possibile usare il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure:

# 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

Creare il client

La libreria client di Condivisione file di Archiviazione di Azure per Python consente di interagire con quattro tipi di risorse: l'account di archiviazione stesso, le condivisioni file, le directory e i file. L'interazione con queste risorse inizia con un'istanza di un client. Per creare un oggetto client, è necessario l'URL del servizio file dell'account di archiviazione e una credenziale che consente di accedere all'account di archiviazione:

from azure.storage.fileshare import ShareServiceClient

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

Ricerca dell'URL dell'account

È possibile trovare l'URL del servizio file dell'account di archiviazione usando il portale di Azure, Azure PowerShell o l'interfaccia della riga di comando di Azure:

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

Tipi di credenziali

Il credential parametro può essere fornito in diversi formati, a seconda del tipo di autorizzazione che si vuole usare:

  1. Per usare un token di firma di accesso condiviso (SAS), specificare il token come stringa. Se l'URL dell'account include il token di firma di accesso condiviso, omettere il parametro credential. È possibile generare un token di firma di accesso condiviso dal portale di Azure in "Firma di accesso condiviso" o usare una delle funzioni per creare un token di firma di generate_sas() accesso condiviso per l'account di archiviazione, la condivisione o il file:

    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. Per usare una chiave condivisa dell'account di archiviazione (nota anche come chiave dell'account o chiave di accesso), specificare la chiave come stringa. Questo è disponibile nel portale di Azure nella sezione "Chiavi di accesso" o eseguendo il comando seguente dell'interfaccia della riga di comando di Azure:

    az storage account keys list -g MyResourceGroup -n MyStorageAccount

    Usare la chiave come parametro delle credenziali per autenticare il client:

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

Creazione del client da un stringa di connessione

A seconda del caso d'uso e del metodo di autorizzazione, è consigliabile inizializzare un'istanza client con un stringa di connessione di archiviazione anziché fornire separatamente l'URL e le credenziali dell'account. A tale scopo, passare il stringa di connessione di archiviazione al metodo della classe del from_connection_string client:

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)

Il stringa di connessione all'account di archiviazione è disponibile nel portale di Azure nella sezione "Chiavi di accesso" o eseguendo il comando dell'interfaccia della riga di comando seguente:

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

Concetti chiave

I componenti seguenti costituiscono il servizio Condivisione file di Azure:

  • Account di archiviazione stesso
  • Condivisione file all'interno dell'account di archiviazione
  • Gerarchia facoltativa di directory all'interno della condivisione file
  • Un file all'interno della condivisione file, che può avere dimensioni fino a 1 TiB

La libreria client di Condivisione file di Archiviazione di Azure per Python consente di interagire con ognuno di questi componenti tramite l'uso di un oggetto client dedicato.

Client asincroni

Questa libreria include un'API asincrona completa supportata in Python 3.5+. Per usarlo, è prima necessario installare un trasporto asincrono, ad esempio aiohttp. Per altre informazioni, vedere la documentazione di azure-core .

I client e le credenziali asincroni devono essere chiusi quando non sono più necessari. Questi oggetti sono gestori di contesti asincroni e definiscono metodi asincroni close .

Client

Vengono forniti quattro client diversi per interagire con i vari componenti del servizio condivisione file:

  1. ShareServiceClient : questo client rappresenta l'interazione con l'account di archiviazione di Azure stesso e consente di acquisire istanze client preconfigurate per accedere alle condivisioni file all'interno. Fornisce operazioni per recuperare e configurare le proprietà del servizio, nonché l'elenco, la creazione e l'eliminazione di condivisioni all'interno dell'account. Per eseguire operazioni su una condivisione specifica, recuperare un client usando il get_share_client metodo .
  2. ShareClient : questo client rappresenta l'interazione con una condivisione file specifica (che non è ancora presente) e consente di acquisire istanze client preconfigurate per accedere alle directory e ai file all'interno. Fornisce operazioni per creare, eliminare, configurare o creare snapshot di una condivisione e include operazioni per creare ed enumerare il contenuto delle directory al suo interno. Per eseguire operazioni su una directory o un file specifico, recuperare un client usando i get_directory_client metodi o get_file_client .
  3. ShareDirectoryClient : questo client rappresenta l'interazione con una directory specifica (che non è ancora presente). Fornisce operazioni per creare, eliminare o enumerare il contenuto di una sottodirectory immediata o annidata e include operazioni per creare ed eliminare file al suo interno. Per le operazioni relative a una sottodirectory o a un file specifico, è anche possibile recuperare un client per tale entità usando le get_subdirectory_client funzioni e get_file_client .
  4. ShareFileClient : questo client rappresenta l'interazione con un file specifico (che non è ancora presente). Fornisce operazioni per caricare, scaricare, creare, eliminare e copiare un file.

Per informazioni dettagliate sulle restrizioni di denominazione dei percorsi, vedere Denominazione e riferimento a condivisioni, directory, file e metadati.

Esempio

Le sezioni seguenti forniscono diversi frammenti di codice che illustrano alcune delle attività di condivisione file di archiviazione più comuni, tra cui:

Creazione di una condivisione file

Creare una condivisione file per archiviare i file

from azure.storage.fileshare import ShareClient

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

Usare il client asincrono per creare una condivisione file

from azure.storage.fileshare.aio import ShareClient

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

Caricamento di un file

Caricare un file nella condivisione

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)

Caricare un file in modo asincrono

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)

Download di un file

Scaricare un file dalla condivisione

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)

Scaricare un file in modo asincrono

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)

Presentazione del contenuto di una directory

Elencare tutte le directory e i file in una directory padre

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)

Elencare il contenuto di una directory in modo asincrono

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)

Configurazione facoltativa

Argomenti di parole chiave facoltativi che possono essere passati al client e a livello di operazione.

Configurazione dei criteri di ripetizione

Usare gli argomenti della parola chiave seguenti quando si crea un'istanza di un client per configurare i criteri di ripetizione dei tentativi:

  • retry_total (int): numero totale di tentativi consentiti. Ha la precedenza su altri conteggi. retry_total=0 Passare se non si vuole riprovare alle richieste. Il valore predefinito è 10.
  • retry_connect (int): numero di errori relativi alla connessione da ritentare. Il valore predefinito è 3.
  • retry_read (int): numero di tentativi di ripetizione degli errori di lettura. Il valore predefinito è 3.
  • retry_status (int): numero di tentativi per i codici di stato non corretti. Il valore predefinito è 3.
  • retry_to_secondary (bool): indica se la richiesta deve essere ritentata a secondaria, se possibile. Questa opzione deve essere abilitata solo per gli account RA-GRS e i dati potenzialmente non aggiornati possono essere gestiti. Il valore predefinito è False.

Altra configurazione client/per operazione

Altri argomenti di parole chiave di configurazione facoltativi che possono essere specificati nel client o per ogni operazione.

Argomenti di parole chiave client:

  • connection_timeout (int): numero di secondi in cui il client attenderà di stabilire una connessione al server. Il valore predefinito è 20 secondi.
  • read_timeout (int): numero di secondi in cui il client attenderà, tra le operazioni di lettura consecutive, una risposta dal server. Si tratta di un timeout a livello di socket e non è influenzato dalle dimensioni complessive dei dati. I timeout di lettura lato client verranno ritentati automaticamente. Il valore predefinito è 60 secondi.
  • transport (Any): trasporto fornito dall'utente per inviare la richiesta HTTP.

Argomenti per parola chiave per operazione:

  • raw_response_hook (chiamabile): il callback specificato usa la risposta restituita dal servizio.
  • raw_request_hook (chiamabile): il callback specificato usa la richiesta prima di essere inviata al servizio.
  • client_request_id (str): identificazione specificata dall'utente facoltativo della richiesta.
  • user_agent (str): aggiunge il valore personalizzato all'intestazione user-agent da inviare con la richiesta.
  • logging_enable (bool): abilita la registrazione a livello DI DEBUG. Il valore predefinito è False. Può anche essere passato a livello di client per abilitarlo per tutte le richieste.
  • logging_body (bool): abilita la registrazione del corpo della richiesta e della risposta. Il valore predefinito è False. Può anche essere passato a livello di client per abilitarlo per tutte le richieste.
  • intestazioni (dict): passare intestazioni personalizzate come coppie chiave-valore. Ad esempio headers={'CustomValue': value}

Risoluzione dei problemi

Generale

I client file di archiviazione generano eccezioni definite in Azure Core.

Questo elenco può essere usato per fare riferimento alle eccezioni generate. Per ottenere il codice di errore specifico dell'eccezione, usare l'attributo error_code , ad esempio exception.error_code.

Registrazione

Questa libreria usa la libreria di registrazione standard per la registrazione. Le informazioni di base sulle sessioni HTTP (URL, intestazioni e così via) vengono registrate a livello di INFO.

La registrazione dettagliata a livello di DEBUG, inclusi i corpi di richiesta/risposta e le intestazioni non contrassegnate, può essere abilitata in un client con l'argomento 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)

Analogamente, logging_enable può abilitare la registrazione dettagliata per una singola operazione, anche quando non è abilitata per il client:

service_client.get_service_properties(logging_enable=True)

Passaggi successivi

Altro codice di esempio

Introduzione agli esempi di condivisione file.

Sono disponibili diversi esempi di Python SDK per condivisione file di archiviazione nel repository GitHub dell'SDK. Questi esempi forniscono codice di esempio per scenari aggiuntivi comunemente rilevati durante l'uso della condivisione file di archiviazione:

Documentazione aggiuntiva

Per una documentazione più completa sull'archiviazione di Condivisione file di Azure, vedere la documentazione sull'archiviazione di Condivisioni file di Azure in docs.microsoft.com.

Contributo

In questo progetto sono benvenuti i contributi e i suggerimenti. Per la maggior parte dei contenuti è necessario sottoscrivere un contratto di licenza di collaborazione (CLA, Contributor License Agreement) che stabilisce che l'utente ha il diritto di concedere, e di fatto concede a Microsoft i diritti d'uso del suo contributo. Per informazioni dettagliate, vedere https://cla.microsoft.com.

Quando si invia una richiesta pull, un bot CLA determina automaticamente se è necessario specificare un contratto CLA e completare la richiesta pull in modo appropriato (ad esempio con un'etichetta e un commento). Seguire le istruzioni specificate dal bot. È sufficiente eseguire questa operazione una sola volta per tutti i repository che usano il contratto CLA Microsoft.

Questo progetto ha adottato il Codice di comportamento di Microsoft per l'open source. Per altre informazioni, vedere Code of Conduct FAQ (Domande frequenti sul Codice di comportamento Open Source di Microsoft) oppure contattare opencode@microsoft.com per eventuali altre domande o commenti.