Partager via

Bibliothèques Azure pour les modèles d’utilisation Python

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 modèles d’utilisation courants, tels que l’installation et l’utilisation de 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 :

  • Configurez un environnement virtuel Python à l’aide de venv ou de votre outil de choix. Pour commencer à utiliser l’environnement virtuel, veillez à l’activer. Pour installer Python, consultez Installer 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)

  • Utilisez un environnement conda. Pour installer Conda, consultez Installer Miniconda.

  • Utilisez un conteneur de développement dans Visual Studio Code ou GitHub Codespaces.

Installation de la bibliothèque

Choisissez la méthode d’installation qui correspond à votre outil de gestion de l’environnement Python, pip ou conda.

Pour installer un package de bibliothèque spécifique, utilisez 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 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 versions préliminaires. Pour plus d’informations, consultez Comment installer des 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 a été disponible depuis Python 3.4 et les mots clés async/await ont été introduits 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 pour fonctionner. La azure-core bibliothèque fournit un transport asynchrone, AioHttpTransportqui est utilisé par les bibliothèques asynchrones, de sorte que vous n’avez peut-être pas besoin d’installer aiohttp séparément.

Le code suivant montre comment créer un fichier Python qui 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 exemple ComputeManagementClient.virtual_machines.begin_create_or_update et WebAppsClient.web_apps.begin_create_or_update) retournent 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éthodes d’une bibliothèque en fonction de sa version et de sa base sur azure.core. 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 préfixe begin_ aux noms de méthode pour mieux indiquer qu'il s'agit d'opérations de sondage long. La migration d’un ancien code vers une bibliothèque azure.core plus récente signifie généralement l’ajout du begin_ préfixe aux noms de méthode, 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, illustre un exemple d'utilisation du poller pour attendre un résultat :



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

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 lorsque les opérations ne sont pas effectuées comme prévu, y compris les requêtes HTTP ayant échoué sur l’API REST Azure. Pour le code de l’application, vous pouvez utiliser les blocs try...except 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.

Exploitation forestière

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 les bibliothèques individuelles, les groupes de bibliothèques 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 Comment configurer des proxys.

Arguments facultatifs pour les objets et méthodes clients

Dans la documentation de référence de la bibliothèque, vous voyez souvent un **kwargs ou un **operation_config argument dans la signature d'un constructeur pour un 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 existe également certains 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 à ces bibliothèques répertoriées sur Python - Nouvelles bibliothèques. Par exemple, voici un sous-ensemble des arguments de mot clé pour azure-core. Pour obtenir une liste complète, consultez gitHub README pour azure-core.

Nom Catégorie Par défaut Descriptif
logging_enable Bool Faux Active la journalisation. Pour plus d’informations, consultez Journalisation dans les bibliothèques Azure.
mandataires dictionnaire {} URL du serveur proxy. Pour plus d’informations, consultez Comment configurer des proxys.
utiliser_les_paramètres_d'environnement Bool Vrai Si la valeur est True, autorise l'utilisation des variables d'environnement HTTP_PROXY et HTTPS_PROXY pour les proxys. Si la valeur est False, les variables d’environnement sont ignorées. Pour plus d’informations, consultez Comment configurer des proxys.
connection_timeout Int 300 Délai d’expiration 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 terminer une opération d’API REST Azure (autrement dit, en attente d’une réponse).
retry_total Int 10 Nombre de nouvelles tentatives autorisées pour les appels d’API REST. Utilisez retry_total=0 pour désactiver les nouvelles tentatives.
mode de réessai énumération exponentiel Applique le minutage des nouvelles tentatives de manière linéaire ou exponentielle. Si elle est « unique », les nouvelles tentatives sont effectuées à intervalles réguliers. Si elle est « exponentielle », chaque nouvelle tentative attend deux fois plus longtemps que la nouvelle tentative 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 spécifiques de mot-clé du stockage blob, consultez le README GitHub pour azure-storage-blob.

Modèle JSON inline pour les arguments d’objet

De nombreuses opérations dans les bibliothèques Azure vous permettent d’exprimer des arguments d’objet en tant qu’objets discrets ou au format 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 json imbriqué.

Par exemple, supposons que vous disposez d’une instance de l’objet KeyVaultManagementClient et que vous appelez son 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]. Un Sku objet contient un SkuName objet et chacun AccessPolicyEntry contient un Permissions objet.

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 utilisant JSON inline s’affiche 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()

Étant donné que les deux formes sont équivalentes, vous pouvez choisir selon ce que vous préférez et même les mélanger. (Le code complet de ces exemples est disponible 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 'sku': 'standard' dans l’exemple précédent génère cette erreur, car le sku paramètre est un Sku objet qui s’attend à un objet inline JSON, dans ce cas {'name': 'standard'}, qui correspond au type attendu SkuName .

Étapes suivantes

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