Modelli di utilizzo delle librerie di Azure per Python

Articolo
10/23/2023

Azure SDK per Python è costituito da molte librerie indipendenti, elencate nell'indice dei pacchetti Python SDK.

Tutte le librerie condividono alcune caratteristiche e modelli di utilizzo comuni, ad esempio l'installazione e l'uso di JSON inline per gli argomenti oggetto.

Configurare un ambiente di sviluppo locale

Se non è già stato fatto, è possibile configurare un ambiente in cui è possibile eseguire questo codice. Di seguito sono riportate alcuni opzioni:

Configurare un ambiente virtuale Python. È possibile creare l'ambiente virtuale in locale o in Azure Cloud Shell ed eseguire il codice. Assicurarsi di attivare l'ambiente virtuale per iniziare a usarlo.
Usare un ambiente conda.
Usare un contenitore di sviluppo in Visual Studio Code o GitHub Codespaces.

Per installare un pacchetto di libreria specifico, usare pip install:

# Install the management library for Azure Storage
pip install azure-mgmt-storage

# Install the client library for Azure Blob Storage
pip install azure-storage-blob

pip install recupera l'ultima versione di una libreria nell'ambiente Python corrente.

È anche possibile usare pip per disinstallare le librerie e installare versioni specifiche, incluse quelle di anteprima. Per altre informazioni, vedere Come installare i pacchetti di librerie di Azure per Python.

Per installare un pacchetto di libreria specifico in un ambiente Conda, usare conda install:

# Install the Azure management library package
conda install azure-mgmt

# Install the client library for Azure Storage
conda install azure-storage

conda install recupera la versione più recente di un pacchetto nell'ambiente Conda corrente.

Per altre informazioni, tra cui come rimuovere pacchetti o installare versioni specifiche, vedere Come installare pacchetti di libreria di Azure per Python.

Operazioni asincrone

Librerie asincrone

Molte librerie client e di gestione forniscono versioni asincrone (.aio). La asyncio libreria è disponibile a partire da Python 3.4 e le parole chiave async/await sono state introdotte in Python 3.5. Le versioni asincrone delle librerie devono essere usate con Python 3.5 e versioni successive.

Esempi di librerie di Azure Python SDK con versioni asincrone includono: azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio e azure.mgmt.compute.aio.

Queste librerie necessitano di un trasporto asincrono, aiohttp ad esempio per funzionare. La azure-core libreria fornisce un trasporto asincrono, AioHttpTransport, usato dalle librerie asincrone.

Il codice seguente illustra come creare un client per la versione asincrona della libreria Archiviazione BLOB di Azure:

credential = DefaultAzureCredential()

async def run():

    async with BlobClient(
        storage_url,
        container_name="blob-container-01",
        blob_name=f"sample-blob-{str(uuid.uuid4())[0:5]}.txt",
        credential=credential,
    ) as blob_client:

        # Open a local file and upload its contents to Blob Storage
        with open("./sample-source.txt", "rb") as data:
            await blob_client.upload_blob(data)
            print(f"Uploaded sample-source.txt to {blob_client.url}")

        # Close credential
        await credential.close()

asyncio.run(run())

L'esempio completo è disponibile in GitHub in use_blob_auth_async.py. Per la versione sincrona di questo codice, vedere Esempio: Caricare un BLOB.

Operazioni a esecuzione prolungata

Alcune operazioni di gestione richiamate, ad esempio ComputeManagementClient.virtual_machines.begin_create_or_update e WebSiteManagementClient.web_apps.begin_create_or_update restituiscono un poller per operazioni a esecuzione prolungata, , LROPoller[<type>]dove <type> è specifico dell'operazione in questione.

Nota

È possibile notare differenze nei nomi dei metodi in una libreria, a causa delle differenze di versione. Le librerie meno recenti non basate su azure.core usano in genere nomi come create_or_update. Le librerie basate su azure.core aggiungono il begin_ prefisso ai nomi dei metodi per indicare meglio che sono operazioni di polling lunghe. La migrazione del codice precedente a una libreria basata su azure.core più recente indica in genere l'aggiunta del prefisso begin_ ai nomi dei metodi, perché la maggior parte delle firme del metodo rimane invariata.

Il LROPoller tipo restituito indica che l'operazione è asincrona. Di conseguenza, è necessario chiamare il metodo result dello strumento per il polling per attendere la conclusione dell'operazione e l'ottenimento del risultato.

Il codice seguente, tratto da Esempio: Creare e distribuire un'app Web, mostra un esempio di uso del poller per attendere un risultato:

poller = app_service_client.web_apps.begin_create_or_update(RESOURCE_GROUP_NAME,
    WEB_APP_NAME,
    {
        "location": LOCATION,
        "server_farm_id": plan_result.id,
        "site_config": {
            "linux_fx_version": "python|3.8"
        }
    }
)

web_app_result = poller.result()

In questo caso, il valore restituito di begin_create_or_update è di tipo AzureOperationPoller[Site], il che significa che il valore restituito di poller.result() è un oggetto Site.

Eccezioni

In generale, le librerie di Azure generano eccezioni quando le operazioni non vengono eseguite come previsto, incluse le richieste HTTP non riuscite all'API REST di Azure. Per il codice dell'app, è possibile usare try...except blocchi per le operazioni di libreria.

Per altre informazioni sul tipo di eccezioni che possono essere generate, vedere la documentazione relativa all'operazione in questione.

Registrazione

Le librerie di Azure più recenti usano la libreria logging standard Python per generare l'output di registrazione. È possibile impostare il livello di registrazione per singole librerie, per gruppi di librerie o per tutte le librerie. Dopo aver registrato un gestore del flusso di registrazione, è possibile abilitare la registrazione per un oggetto client specifico o per un'operazione specifica. Per altre informazioni, vedere Configurare la registrazione nelle librerie di Azure per Python.

Configurazione proxy

Per specificare un proxy, è possibile usare variabili di ambiente o argomenti facoltativi. Per altre informazioni, vedere Come configurare i proxy per le librerie di Azure.

Argomenti facoltativi per oggetti client e metodi

Nella documentazione di riferimento delle librerie viene spesso visualizzato un argomento **kwargs o **operation_config nella firma di un costruttore di oggetti client o di un metodo di operazione specifico. Questi segnaposto indicano che l'oggetto o il metodo in questione può supportare altri argomenti denominati. In genere la documentazione di riferimento indica gli argomenti specifici che è possibile usare. Sono inoltre spesso supportati alcuni argomenti generali descritti nelle sezioni seguenti.

Argomenti per le librerie basate su azure.core

Questi argomenti si applicano alle librerie elencate in Python - Nuove librerie. Di seguito, ad esempio, è riportato un subset degli argomenti della parola chiave per azure-core. Per un elenco completo, vedere il file README di GitHub per azure-core.

Nome	Type	Default	Descrizione
logging_enable	bool	Falso	Abilita la registrazione. Per altre informazioni, vedere Configurare la registrazione nelle librerie di Azure per Python.
Proxy	dict	{}	URL del server proxy. Per altre informazioni, vedere Come configurare i proxy per le librerie di Azure.
use_env_settings	bool	Vero	Se True, consente l'uso delle variabili di ambiente `HTTP_PROXY` e `HTTPS_PROXY` per i proxy. Se False, le variabili di ambiente vengono ignorate. Per altre informazioni, vedere Come configurare i proxy per le librerie di Azure.
connection_timeout	int	300	Timeout in secondi per stabilire una connessione agli endpoint dell'API REST di Azure.
read_timeout	int	300	Timeout in secondi per il completamento di un'operazione dell'API REST di Azure (ovvero attesa di una risposta).
retry_total	int	10	Numero di nuovi tentativi consentiti per le chiamate all'API REST. Usare `retry_total=0` per disabilitare i tentativi.
retry_mode	enum	exponential	Applica l'intervallo dei tentativi in un modo lineare o esponenziale. Se "single", i tentativi vengono eseguiti a intervalli regolari. Se "exponential", ogni ripetizione attende il doppio del tempo del tentativo precedente.

Le singole librerie non sono tenute a supportare nessuno di questi argomenti, quindi consultare sempre la documentazione di riferimento per ogni raccolta per ottenere dettagli esatti. Inoltre, ogni libreria può supportare altri argomenti. Ad esempio, per argomenti di parole chiave specifici dell'archiviazione BLOB, vedere readME di GitHub per azure-storage-blob.

Modello JSON inline per argomenti oggetto

Molte operazioni all'interno di Azure SDK consentono di esprimere gli argomenti oggetto come oggetti discreti o come JSON inline.

Si supponga, ad esempio, di avere un ResourceManagementClient oggetto tramite il quale si crea un gruppo di risorse con il relativo create_or_update metodo. Il secondo argomento di questo metodo è di tipo ResourceGroup.

Per chiamare il create_or_update metodo, è possibile creare un'istanza discreta di ResourceGroup direttamente con gli argomenti necessari (location in questo caso):

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonSDKExample-rg",
    ResourceGroup(location="centralus")
)

In alternativa, è possibile passare gli stessi parametri come JSON inline:

# Provision the resource group.
rg_result = resource_client.resource_groups.create_or_update(
    "PythonAzureExample-rg", {"location": "centralus"}
)

Quando si usa JSON inline, le librerie di Azure converteno automaticamente il codice JSON inline nel tipo di oggetto appropriato per l'argomento in questione.

Gli oggetti possono anche avere argomenti oggetto annidati, nel qual caso si può anche usare codice JSON annidato.

Si supponga, ad esempio, di avere un'istanza dell'oggetto KeyVaultManagementClient e di chiamare il relativo metodo create_or_update. In questo caso, il terzo argomento è di tipo VaultCreateOrUpdateParameters, che contiene un argomento di tipo VaultProperties. VaultProperties, a sua volta, contiene gli argomenti oggetto di tipo Sku e list[AccessPolicyEntry]. Sku contiene un oggetto SkuName e ogni oggetto AccessPolicyEntry contiene un oggetto Permissions.

Per chiamare begin_create_or_update con oggetti incorporati, usare codice simile al seguente (presupponendo tenant_idche , object_ide LOCATION siano già definiti). È anche possibile creare gli oggetti necessari prima della chiamata di funzione.

# Provision a Key Vault using inline parameters
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_A,
    VaultCreateOrUpdateParameters(
        location = LOCATION,
        properties = VaultProperties(
            tenant_id = tenant_id,
            sku = Sku(
                name="standard",
                family="A"
            ),            
            access_policies = [
                AccessPolicyEntry(
                    tenant_id = tenant_id,
                    object_id = object_id,
                    permissions = Permissions(
                        keys = ['all'],
                        secrets = ['all']
                    )
                )
            ]
        )
    )
)

key_vault1 = poller.result()

La stessa chiamata usando JSON inline sarà come segue:

# Provision a Key Vault using inline JSON
poller = keyvault_client.vaults.begin_create_or_update(
    RESOURCE_GROUP_NAME,
    KEY_VAULT_NAME_B,
    {
        'location': LOCATION,
        'properties': {
            'sku': {
                'name': 'standard',
                'family': 'A'
            },
            'tenant_id': tenant_id,
            'access_policies': [{
                'tenant_id': tenant_id,
                'object_id': object_id,                
                'permissions': {
                    'keys': ['all'],
                    'secrets': ['all']
                }
            }]
        }
    }
)

key_vault2 = poller.result()

Poiché i due formati sono equivalenti, è possibile scegliere quello che si preferisce usare e persino combinarli. (Il codice completo per questi esempi è disponibile in GitHub.

Se il formato JSON non è corretto, in genere viene visualizzato l'errore "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". Una causa comune di questo errore è che si specifica una singola stringa di una proprietà quando la libreria prevede un oggetto JSON annidato. Se ad esempio si usa 'sku': 'standard' nell'esempio precedente, questo errore viene generato perché il parametro sku è un oggetto Sku che prevede un oggetto JSON inline, in questo caso {'name': 'standard'}, che è mappato al tipo SkuName previsto.

Passaggi successivi

Ora che si conoscono i modelli comuni per l'uso delle librerie di Azure per Python, vedere gli esempi autonomi seguenti per esplorare scenari specifici di gestione e libreria client. È possibile provare questi esempi in qualsiasi ordine perché non sono sequenziali o interdipendenti.