Condividi tramite

Modelli di utilizzo delle librerie di Azure per Python

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

Tutte le librerie condividono determinate caratteristiche comuni e modelli di utilizzo, 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. Ecco alcune opzioni:

  • Configurare un ambiente virtuale Python usando venv o lo strumento preferito. Per iniziare a usare l'ambiente virtuale, assicurarsi di attivarlo. Per installare Python, vedere Installare Python.

    #!/bin/bash
# Create a virtual environment
python -m venv .venv
# Activate the virtual environment
source .venv/Scripts/activate # only required for Windows (Git Bash)

  • Usa un ambiente conda . Per installare Conda, vedere Installare Miniconda.

  • Usare un contenitore di sviluppo in Visual Studio Code o GitHub Codespaces.

Installazione della libreria

Scegliere il metodo di installazione che corrisponde allo strumento di gestione dell'ambiente Python, pip o conda.

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

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

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

REM Install the azure identity library for Azure authentication
pip install azure-identity

pip install recupera la versione più recente di una libreria nell'ambiente Python corrente.

È anche possibile usare pip per disinstallare le librerie e installare versioni specifiche, incluse le versioni di anteprima. Per altre informazioni, vedere Come installare i 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, che viene usato dalle librerie asincrone, pertanto potrebbe non essere necessario installare aiohttp separatamente.

Il codice seguente illustra come creare un file Python che illustra come creare un client per la versione asincrona della libreria di 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 WebAppsClient.web_apps.begin_create_or_update) restituiscono un poller per operazioni a esecuzione prolungata, LROPoller[<type>], dove <type> è specifico per l'operazione in questione.

Annotazioni

È possibile notare differenze nei nomi dei metodi in una libreria a seconda della versione e se si basa su azure.core. 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 prefisso begin_ ai nomi dei metodi per indicare in modo più chiaro che sono operazioni di polling lunghe. La migrazione del codice precedente a una libreria più recente basata su azure.core significa in genere aggiungere il begin_ prefisso ai nomi dei metodi, perché la maggior parte delle firme dei metodi rimane invariata.

Il LROPoller tipo restituito indica che l'operazione è asincrona. Di conseguenza, è necessario chiamare il metodo del poller per attendere il completamento dell'operazione result e ottenere il relativo risultato.

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



# Step 3: With the plan in place, provision the web app itself, which is the process that can host
# whatever code we want to deploy to it.

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 blocchi try...except attorno alle operazioni della 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 standard logging Python per generare l'output del log. È possibile impostare il livello di registrazione per singole librerie, gruppi di librerie o tutte le librerie. Dopo aver registrato un gestore del flusso di registrazione, è possibile abilitare la registrazione per un oggetto client specifico o un'operazione specifica. Per altre informazioni, vedere Registrazione nelle librerie di Azure.

Configurazione proxy

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

Argomenti facoltativi per oggetti client e metodi

Nella documentazione di riferimento della libreria, si vede spesso 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. Esistono anche alcuni argomenti generali spesso supportati come descritto nelle sezioni seguenti.

Argomenti per le librerie basate su azure.core

Questi argomenti si applicano a tali 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 TIPO Valore predefinito Descrizione
abilita_registrazione Bool Falso Abilita la registrazione. Per altre informazioni, vedere Registrazione nelle librerie di Azure.
Proxy dizionario {} URL del server proxy. Per altre informazioni, vedere Come configurare i proxy.
usa_impostazioni_ambiente Bool Vero Se True, consente l'uso di variabili di HTTP_PROXY ambiente e HTTPS_PROXY per i proxy. Se False, le variabili di ambiente vengono ignorate. Per altre informazioni, vedere Come configurare i proxy.
connection_timeout Int 300 Il timeout espresso 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, cioè il tempo di attesa per una risposta.
ricarica_totale Int 10 Numero di tentativi consentiti per le chiamate API REST. Utilizzare retry_total=0 per disabilitare le ripetizioni.
modalità_ritentare enumerazione esponenziale Applica i tempi di ripetizione dei tentativi in modo lineare o esponenziale. Se impostato su 'singolo', i tentativi vengono eseguiti a intervalli regolari. Se 'esponenziale', ogni tentativo attende il doppio rispetto al 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 di oggetti

Molte operazioni all'interno delle librerie di Azure consentono di esprimere 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 di 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 di oggetto annidati, nel qual caso è anche possibile usare JSON annidato.

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

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 che usa JSON inline viene visualizzata 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é entrambe le forme sono equivalenti, è possibile scegliere qualsiasi cosa si preferisca e persino combinarle. Il codice completo per questi esempi è disponibile in GitHub.

Se il tuo JSON non è formattato correttamente, in genere si riceve l'errore "DeserializationError: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute 'get'". Una causa comune di questo errore è che si sta fornendo una singola stringa per una proprietà quando la libreria prevede un oggetto JSON annidato. Ad esempio, l'uso di 'sku': 'standard' nel precedente esempio genera questo errore perché il parametro sku è un oggetto Sku che si aspetta un JSON dell'oggetto inline, in questo caso {'name': 'standard'}, che corrisponde al tipo previsto SkuName.

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.