Suivre les opérations asynchrones Azure

  • Article

Certaines opérations REST Azure s’exécutent de façon asynchrone, car elles ne peuvent pas être effectuées rapidement. Cet article explique comment effectuer le suivi de l’état des opérations asynchrones via les valeurs retournées dans la réponse.

Codes d’état pour les opérations asynchrones

Initialement, une opération asynchrone retourne un code d’état HTTP de type :

  • 201 (créé)
  • 202 (accepté)

Toutefois, ce code d’état ne signifie pas nécessairement que l’opération est asynchrone. Une opération asynchrone retourne également une valeur pour provisioningState qui indique que l’opération n’est pas terminée. La valeur peut varier selon l’opération, mais elle n’inclut pas Succeeded (Réussite), Failed (Échec) ou Canceled (Annulation). Ces trois valeurs indiquent que l’opération est terminée. Si aucune valeur n’est retournée pour provisioningState, c’est que l’opération est terminée et a réussi.

Lorsque l’opération se termine correctement, elle renvoie :

  • 200 (OK)
  • 204 (Pas de contenu)

Reportez-vous à la documentation de l’API REST pour voir les réponses liées à l’opération que vous exécutez.

Une fois le code de réponse 201 ou 202 obtenu, vous êtes prêt à superviser l’état de l’opération.

URL pour superviser l’état

Il existe deux manières différentes de superviser l’état de l’opération asynchrone. Pour déterminer l’approche correcte, vous devez examiner les valeurs d’en-tête retournées par votre requête d’origine. Tout d’abord, recherchez :

  • Azure-AsyncOperation- URL pour vérifier l’état de l’opération en cours. Si votre opération retourne cette valeur, utilisez-la pour suivre l’état de l’opération.
  • Retry-After- Le nombre de secondes à attendre avant de vérifier l’état de l’opération asynchrone.

Si Azure-AsyncOperation n’est pas l’une des valeurs d’en-tête, recherchez :

  • Location– URL pour déterminer si une opération est terminée. Utilisez cette valeur uniquement lorsque Azure-AsyncOperation n'est pas renvoyée.
  • Retry-After- Le nombre de secondes à attendre avant de vérifier l’état de l’opération asynchrone.

Quand l’en-tête Retry-after n’est pas retourné, implémentez votre propre logique de nouvelle tentative.

Remarque

Votre client REST doit accepter une taille d'URL minimale de 4 Ko pour Azure-AsyncOperation et Location.

Autorisation pour le suivi de l’état asynchrone

Pour suivre l’état d’une opération asynchrone, vous avez besoin d’une autorisation suffisante au niveau du groupe de ressources. Si vous avez seulement une autorisation au niveau de la ressource, vous pouvez démarrer l’opération, mais vous ne pouvez pas suivre son état. L’autorisation au niveau du groupe de ressources est nécessaire, car l’URL pour le suivi de l’état n’a pas la ressource comme étendue.

Par exemple, pour démarrer une machine virtuelle, vous avez besoin du rôle Contributeur de machine virtuelle pour le groupe de ressources qui contient la machine virtuelle. L’URL pour le suivi d’une demande de démarrage n’inclut pas la machine virtuelle dans son chemin.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Demande et réponse Azure-AsyncOperation

Si vous avez une URL de la valeur d’en-tête Azure-AsyncOperation, envoyez une requête GET à cette URL. Utilisez la valeur de Retry-After pour planifier la fréquence de vérification de l’état. Vous obtenez un objet de réponse qui indique l’état de l’opération. Une réponse différente est retournée lors de la vérification de l’état de l’opération avec l’URL de Location. Pour plus d’informations sur la réponse à partir d’une URL d’emplacement, consultez Créer le compte de stockage (202 avec Location et Retry-After).

Les propriétés de la réponse peuvent varier, mais incluent toujours l’état de l’opération asynchrone.

{
    "status": "{status-value}"
}

L’exemple suivant montre d’autres valeurs qui peuvent être retournées par l’opération :

{
    "id": "{resource path from GET operation}",
    "name": "{operation-id}",
    "status" : "Succeeded | Failed | Canceled | {resource provider values}",
    "startTime": "2017-01-06T20:56:36.002812+00:00",
    "endTime": "2017-01-06T20:56:56.002812+00:00",
    "percentComplete": {double between 0 and 100 },
    "properties": {
        /* Specific resource provider values for successful operations */
    },
    "error" : {
        "code": "{error code}",  
        "message": "{error description}"
    }
}

L’objet d’erreur est retourné lorsque l’état indique que l'opération a échoué (Failed) ou a été annulée (Canceled). Toutes les autres valeurs sont facultatives. La réponse que vous recevez peut être différente de l’exemple.

Valeurs provisioningState

Les opérations qui créent, mettent à jour ou suppriment (PUT, PATCH, DELETE) une ressource retournent généralement une valeur provisioningState. Quand une opération se termine, une des trois valeurs suivantes est retournée :

  • Opération réussie
  • Échec
  • Opération annulée

Toutes les autres valeurs indiquent que l’opération est en cours d’exécution. Le fournisseur de ressources peut retourner une valeur personnalisée qui indique son état. Par exemple, vous recevez Accepted (Accepté) quand la demande est reçue et en cours d’exécution.

Exemples de demandes et de réponses

Démarrez la machine virtuelle (202 avec Azure-AsyncOperation)

Cet exemple montre comment déterminer l’état de l'opération start pour les machines virtuelles. La demande initiale présente le format suivant :

POST 
https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Compute/virtualMachines/{vm-name}/start?api-version=2019-12-01

Renvoie le code d’état 202. Les valeurs d’en-tête incluent :

Azure-AsyncOperation : https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Pour vérifier l’état de l’opération asynchrone, envoyez une autre demande à cette URL.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Compute/locations/{region}/operations/{operation-id}?api-version=2019-12-01

Le corps de la réponse contient l’état de l’opération :

{
  "startTime": "2017-01-06T18:58:24.7596323+00:00",
  "status": "InProgress",
  "name": "9a062a88-e463-4697-bef2-fe039df73a02"
}

Déployer des ressources (201 avec Azure-AsyncOperation)

Cet exemple montre comment déterminer l’état de l'opération deployments pour le déploiement de ressources sur Azure. La demande initiale présente le format suivant :

PUT
https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/microsoft.resources/deployments/{deployment-name}?api-version=2020-06-01

Il renvoie le code d’état 201. Le corps de la réponse inclut :

"provisioningState":"Accepted",

Les valeurs d’en-tête incluent :

Azure-AsyncOperation: https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/Microsoft.Resources/deployments/{deployment-name}/operationStatuses/{operation-id}?api-version=2020-06-01

Pour vérifier l’état de l’opération asynchrone, l’envoi d’une autre demande à cette URL.

GET 
https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group}/providers/Microsoft.Resources/deployments/{deployment-name}/operationStatuses/{operation-id}?api-version=2020-06-01

Le corps de la réponse contient l’état de l’opération :

{
    "status": "Running"
}

Lorsque le déploiement est terminé, la réponse contient :

{
    "status": "Succeeded"
}

Créer le compte de stockage (202 avec Location et Retry-After)

Cet exemple montre comment déterminer l’état de l'opération create pour les comptes de stockage. La demande initiale présente le format suivant :

PUT
https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group}/providers/Microsoft.Storage/storageAccounts/{storage-name}?api-version=2019-06-01

Et le corps de la demande contient les propriétés du compte de stockage :

{
    "location": "South Central US",
    "properties": {},
    "sku": {
        "name": "Standard_LRS"
    },
    "kind": "Storage"
}

Renvoie le code d’état 202. Les valeurs d’en-tête incluent les deux valeurs suivantes :

Location: https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Storage/operations/{operation-id}?monitor=true&api-version=2019-06-01
Retry-After: 17

Une fois le nombre de secondes spécifié dans Retry-After écoulé, vérifiez l’état de l’opération asynchrone en envoyant une autre demande à cette URL.

GET 
https://management.azure.com/subscriptions/{subscription-id}/providers/Microsoft.Storage/operations/{operation-id}?monitor=true&api-version=2019-06-01

Si la demande est toujours en cours d’exécution, vous recevez un code d’état 202. Si la demande est terminée, vous recevez un code d’état 200. Le corps de la réponse contient les propriétés du compte de stockage qui a été créé.

Étapes suivantes