Modèles d’utilisation des bibliothèques Azure pour 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 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 :
Configurez un environnement virtuel Python. Vous pouvez créer l’environnement virtuel localement ou dans Azure Cloud Shell et y exécuter le code. Veillez à activer l’environnement virtuel pour commencer à l’utiliser.
Utilisez un environnement conda.
Utilisez un conteneur de développement dans Visual Studio Code ou GitHub Codespaces.
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, AioHttpTransport
qui 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_id
que , object_id
et 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.
Commentaires
https://aka.ms/ContentUserFeedback.
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultezEnvoyer et afficher des commentaires pour