Modèles d’utilisation des bibliothèques Azure pour Python

  • Article

Le Kit de développement logiciel (SDK) Azure pour Python est composé de nombreuses bibliothèques indépendantes, qui sont répertoriées dans l’index du package du Kit de développement logiciel (SDK) Python.

Toutes les bibliothèques partagent certaines caractéristiques et certains modèles d’utilisation courants, tels que l’installation et l’utilisation de code JSON inline pour les arguments d’objet.

Configurer votre environnement de développement local

Si ce n’est déjà fait, vous pouvez configurer un environnement dans lequel vous pouvez exécuter ce code. Voici quelques options possibles :

Installation d’une bibliothèque

Pour installer un package de bibliothèque spécifique, utilisez 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 récupère la dernière version d’une bibliothèque dans votre environnement Python actuel.

Vous pouvez également utiliser pip pour désinstaller des bibliothèques et installer des versions spécifiques, y compris des préversions. Pour plus d’informations, consultez Guide pratique pour installer les packages de bibliothèque Azure pour Python.

Opérations asynchrones

Bibliothèques asynchrones

De nombreuses bibliothèques clientes et de gestion fournissent des versions asynchrones (.aio). La asyncio bibliothèque est disponible depuis Python 3.4 et les mot clé asynchrones/await ont été introduites dans Python 3.5. Les versions asynchrones des bibliothèques sont destinées à être utilisées avec Python 3.5 et versions ultérieures.

Voici quelques exemples de bibliothèques de SDK Python Azure avec des versions asynchrones : azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio et azure.mgmt.compute.aio.

Ces bibliothèques ont besoin d’un transport asynchrone tel que aiohttp le travail. La azure-core bibliothèque fournit un transport asynchrone, AioHttpTransportqui est utilisé par les bibliothèques asynchrones.

Le code suivant montre comment créer un client pour la version asynchrone de la bibliothèque Stockage Blob 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’exemple complet se trouve sur GitHub à use_blob_auth_async.py. Pour obtenir la version synchrone de ce code, consultez Exemple : Charger un objet blob.

Opérations de longue durée

Certaines opérations de gestion que vous appelez (par ComputeManagementClient.virtual_machines.begin_create_or_update exemple, et WebSiteManagementClient.web_apps.begin_create_or_update renvoyez un polleur pour les opérations de longue durée, LROPoller[<type>]où <type> est spécifique à l’opération en question.

Remarque

Vous remarquerez peut-être des différences dans les noms de méthode dans une bibliothèque, ce qui est dû à des différences de version. Les bibliothèques plus anciennes qui ne sont pas basées sur azure.core utilisent généralement des noms tels que create_or_update. Les bibliothèques basées sur azure.core ajoutent le begin_ préfixe aux noms de méthode pour mieux indiquer qu’elles sont des opérations d’interrogation longues. La migration de l’ancien code vers une bibliothèque basée sur azure.core plus récente consiste généralement à ajouter le préfixe begin_ aux noms des méthodes, car la plupart des signatures de méthode restent identiques.

Le LROPoller type de retour signifie que l’opération est asynchrone. En conséquence, vous devez appeler la méthode result de l’interrogateur pour attendre que l’opération se termine et obtenir son résultat.

Le code suivant, extrait de l’exemple : Créer et déployer une application web, montre un exemple d’utilisation de l’polleur pour attendre un résultat :

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

Dans ce cas, la valeur de retour de begin_create_or_update type est de type AzureOperationPoller[Site], ce qui signifie que la valeur de retour d’est poller.result() un objet Site.

Exceptions

En règle générale, les bibliothèques Azure déclenchent des exceptions quand des opérations ne s’exécutent pas comme prévu, notamment en cas d’échec de requêtes HTTP vers l’API REST Azure. Pour le code de l’application, vous pouvez utiliser try...except des blocs autour des opérations de bibliothèque.

Pour plus d’informations sur le type d’exceptions qui peuvent être levées, consultez la documentation relative à l’opération en question.

Logging

Les bibliothèques Azure les plus récentes utilisent la bibliothèque Python standard logging pour générer une sortie de journal. Vous pouvez définir le niveau de journalisation pour des bibliothèques spécifiques, des groupes de bibliothèques spécifiques ou toutes les bibliothèques. Une fois que vous avez inscrit un gestionnaire de flux de journalisation, vous pouvez activer la journalisation pour un objet client spécifique ou une opération spécifique. Pour plus d’informations, consultez Journalisation dans les bibliothèques Azure.

Configuration du proxy

Pour spécifier un proxy, vous pouvez utiliser des variables d’environnement ou des arguments facultatifs. Pour plus d’informations, consultez Guide pratique pour configurer des proxys.

Arguments facultatifs pour les méthodes et les objets client

Dans la documentation de référence de bibliothèque, vous voyez souvent un argument **kwargs ou **operation_config dans la signature d’un constructeur d’objet client ou d’une méthode d’opération spécifique. Ces espaces réservés indiquent que l’objet ou la méthode en question peut prendre en charge d’autres arguments nommés. En règle générale, la documentation de référence indique les arguments spécifiques que vous pouvez utiliser. Il y a aussi des arguments généraux qui sont souvent pris en charge comme décrit dans les sections suivantes.

Arguments pour les bibliothèques basées sur azure.core

Ces arguments s’appliquent aux bibliothèques listées dans Python - Nouvelles bibliothèques. Par exemple, voici un sous-ensemble des arguments mot clé pour azure-core. Pour obtenir une liste complète, consultez gitHub README pour azure-core.

Nom Type Default Description
logging_enable bool False Active la journalisation. Pour plus d’informations, consultez Journalisation dans les bibliothèques Azure.
des proxies dict {} URL de serveur proxy. Pour plus d’informations, consultez Guide pratique pour configurer des proxys.
use_env_settings bool True Si la valeur est True, autorise l’utilisation des variables d’environnement HTTP_PROXY et HTTPS_PROXY pour les proxies. Si la valeur est False, les variables d’environnement sont ignorées. Pour plus d’informations, consultez Guide pratique pour configurer des proxys.
connection_timeout int 300 Délai d’attente en secondes pour établir une connexion aux points de terminaison de l’API REST Azure.
read_timeout int 300 Délai d’expiration en secondes pour l’exécution d’une opération de l’API REST Azure (autrement dit, attente d’une réponse).
retry_total int 10 Nombre de nouvelles tentatives autorisées pour les appels de l’API REST. Utilisez retry_total=0 pour désactiver les nouvelles tentatives.
retry_mode enum exponential Applique le minutage des nouvelles tentatives de manière linéaire ou exponentielle. Si vous affectez la valeur « single », les nouvelles tentatives sont effectuées à intervalles réguliers. Si vous affectez la valeur « exponential », chaque nouvelle tentative attend deux fois plus longtemps que la précédente.

Les bibliothèques individuelles ne sont pas tenues de prendre en charge l’un de ces arguments. Consultez donc toujours la documentation de référence de chaque bibliothèque pour obtenir des détails exacts. En outre, chaque bibliothèque peut prendre en charge d’autres arguments. Par exemple, pour les arguments de stockage d’objets blob spécifiques mot clé, consultez gitHub README pour azure-storage-blob.

Modèle JSON inlined pour les arguments d’objet

De nombreuses opérations au sein des bibliothèques Azure vous permettent d’exprimer des arguments d’objet en tant qu’objets discrets ou en tant que code JSON inline.

Par exemple, supposons que vous disposez d’un ResourceManagementClient objet par le biais duquel vous créez un groupe de ressources avec sa create_or_update méthode. Le deuxième argument de cette méthode est de type ResourceGroup.

Pour appeler la create_or_update méthode, vous pouvez créer une instance discrète de ResourceGroup directement avec ses arguments requis (location dans ce cas) :

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

Vous pouvez également transmettre les mêmes paramètres que le format JSON inlined :

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

Lorsque vous utilisez json inline, les bibliothèques Azure convertissent automatiquement le JSON inline en type d’objet approprié pour l’argument en question.

Les objets peuvent également avoir des arguments d’objet imbriqués, auquel cas vous pouvez également utiliser le format JSON imbriqué.

Supposons, par exemple, que vous ayez une instance de l’objet KeyVaultManagementClient et que vous appelez sa méthode create_or_update. Dans ce cas, le troisième argument est de type VaultCreateOrUpdateParameters, qui contient lui-même un argument de type VaultProperties. VaultProperties, à son tour, contient des arguments d’objet de type Sku et list[AccessPolicyEntry]. Une Sku contient un objet SkuName, et chaque AccessPolicyEntry contient un objet Permissions.

Pour appeler begin_create_or_update avec des objets incorporés, vous utilisez du code comme suit (en supposant tenant_idque , object_idet LOCATION sont déjà définis). Vous pouvez également créer les objets nécessaires avant l’appel de fonction.

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

Le même appel à l’aide du format JSON inlined apparaît comme suit :

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

Comme les deux formes sont équivalentes, vous pouvez choisir celle qui vous convient le mieux et même les mélanger. (Le code complet de ces exemples se trouve sur GitHub.)

Si votre JSON n’est pas correctement formé, vous obtenez généralement l’erreur « DeserializationError : Impossible de désérialiser à l’objet : type, AttributeError : l’objet « str » n’a pas d’attribut ' get' ». Une cause courante de cette erreur est que vous fournissez une chaîne unique pour une propriété lorsque la bibliothèque attend un objet JSON imbriqué. Par exemple, l’utilisation de 'sku': 'standard' dans l’exemple précédent génère cette erreur, car le paramètre sku est un objet Sku qui attend un JSON d’objet inlined, dans ce cas {'name': 'standard'}, qui correspond au type SkuName attendu.

Étapes suivantes

Maintenant que vous avez découvert les modèles courants pour l’utilisation des bibliothèques Azure pour Python, consultez les exemples autonomes suivants pour explorer des scénarios de gestion et de bibliothèques clientes spécifiques. Vous pouvez essayer ces exemples dans n’importe quel ordre, car ils ne sont pas séquentiels ou interdépendants.