Partager via

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

  • Article

Le SDK Azure pour Python est composé de nombreuses bibliothèques indépendantes, qui sont listées sur l’index des packages Python SDK.

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 pas déjà fait, vous pouvez configurer un environnement où 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 async (.aio). La bibliothèque asyncio est disponible depuis Python 3.4, et les mots-clés async/await ont été introduits dans Python 3.5. Les versions async des bibliothèques sont destinées à être utilisées avec Python 3.5 et les versions ultérieures.

Des exemples de bibliothèques Azure Python SDK avec des versions async incluent : azure.storage.blob.aio, azure.servicebus.aio, azure.mgmt.keyvault.aio, et azure.mgmt.compute.aio.

Ces bibliothèques nécessitent un transport async tel que aiohttp pour fonctionner. La bibliothèque azure-core fournit un transport async, AioHttpTransport, qui est utilisé par les bibliothèques async.

Le code suivant montre comment créer un client pour la version async de la bibliothèque Azure Blob Storage :

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 est sur GitHub à use_blob_auth_async.py. Pour la version synchrone de ce code, veuillez consulter la section Exemple : Téléverser un blob.

Opérations de longue durée

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

Remarque

Vous pouvez remarquer des différences dans les noms de méthodes dans une bibliothèque, ce qui est dû aux différences de version. Les anciennes bibliothèques qui ne sont pas basées sur azure.core utilisent généralement des noms comme create_or_update. Les bibliothèques basées sur azure.core ajoutent le préfixe begin_ aux noms des méthodes pour mieux indiquer qu’il s’agit d’opérations de long polling. 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 type de retour LROPoller 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, tiré de Exemple : Créer et déployer une application web, montre un exemple d’utilisation du poller 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 est de type AzureOperationPoller[Site], ce qui signifie que la valeur de retour de poller.result() est 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 des blocs try...except autour des opérations de la bibliothèque.

Pour plus d’informations sur le type d’exceptions qui peuvent être levées, consultez la documentation de 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 optionnels. 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 placeholders indiquent que l’objet ou la méthode en question peut supporter 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 de mot-clé pour azure-core. Pour une liste complète, consultez le README GitHub 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 obligées de supporter l’un de ces arguments, alors consultez toujours la documentation de référence pour chaque bibliothèque pour des détails exacts. De plus, chaque bibliothèque peut supporter d’autres arguments. Par exemple, pour des arguments spécifiques au stockage de blobs, consultez le README GitHub 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 ayez un objet ResourceManagementClient à travers lequel vous créez un groupe de ressources avec sa méthode create_or_update. Le deuxième argument de cette méthode est de type ResourceGroup.

Pour appeler la méthode create_or_update, vous pouvez créer une instance distincte 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 en ligne, les bibliothèques Azure convertissent automatiquement le JSON en ligne 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 imbriqués, vous utilisez un code comme le suivant (en supposant que tenant_id, object_id et LOCATION soient 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: Unable to deserialize to object: type, AttributeError: 'str' object has no attribute '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 ni interdépendants.