Seguimiento de las operaciones asincrónicas de Azure

  • Artículo

Algunas operaciones de REST de Azure se ejecutan asincrónicamente porque la operación no se puede completar rápidamente. En este artículo se describe cómo realizar un seguimiento del estado de las operaciones asincrónicas a través de los valores devueltos en la respuesta.

Códigos de estado para las operaciones asincrónicas

Una operación asincrónica devuelve inicialmente un código de estado HTTP de alguno de estos tipos:

  • 201 (Created)
  • 202 (Accepted)

Sin embargo, ese código de estado no significa necesariamente que la operación sea asincrónica. Una operación asincrónica también devuelve un valor para provisioningState que indica que la operación no ha finalizado. El valor puede variar según la operación, pero no incluye Correcto, Error ni Cancelado. Esos tres valores indican que la operación finalizó. Si no se devuelve ningún valor para provisioningState, la operación finalizó correctamente.

Cuando la operación se completa correctamente, devuelve:

  • 200 (OK)
  • 204 (No Content)

Consulte la documentación de la API REST para ver respuestas para la operación que está ejecutando.

Después de obtener el código de respuesta 201 o 202, estará listo para supervisar el estado de la operación.

Dirección URL para supervisar el estado

Hay dos maneras diferentes de supervisar el estado de la operación asincrónica. Puede determinar el enfoque correcto al examinar los valores de encabezado que devuelve la solicitud original. En primer lugar, busque:

  • Azure-AsyncOperation: dirección URL para comprobar el estado actual de la operación. Si la operación devuelve este valor, úselo para realizar un seguimiento del estado de la operación.
  • Retry-After: el número de segundos que deben transcurrir antes de comprobar el estado de la operación asincrónica.

Si Azure-AsyncOperation no es uno de los valores del encabezado, busque:

  • Location: dirección URL para determinar cuándo se completa una operación. Use este valor solo cuando no se devuelva Azure-AsyncOperation.
  • Retry-After: el número de segundos que deben transcurrir antes de comprobar el estado de la operación asincrónica.

Cuando no se devuelve el encabezado Retry-after, implemente su propia lógica de reintento.

Nota:

El cliente REST debe aceptar un tamaño de dirección URL mínimo de 4 KB para Azure-AsyncOperation y Location.

Permiso para realizar el seguimiento del estado asincrónico

Para realizar un seguimiento del estado de una operación asincrónica, necesita permiso suficiente en el nivel del grupo de recursos. Si solo tiene permiso en el nivel del recurso, puede iniciar la operación, pero no puede realizar el seguimiento de su estado. Se requiere tener permiso en el nivel del grupo de recursos porque la dirección URL para el estado de seguimiento no tiene como ámbito el recurso.

Por ejemplo, para iniciar una máquina virtual, necesita el rol Colaborador de máquina virtual para el grupo de recursos que contiene la máquina virtual. La dirección URL para realizar el seguimiento de una solicitud de inicio no incluye la máquina virtual en su ruta de acceso.

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

Solicitud y respuesta de Azure-AsyncOperation

Si tiene una dirección URL del valor Azure-AsyncOperation del encabezado, envíe una solicitud GET a esa dirección URL. Use el valor de Retry-After para programar la frecuencia con la que se comprobará el estado. Recibe un objeto de respuesta que indica el estado de la operación. Se devuelve una respuesta diferente al comprobar el estado de la operación con la dirección URL de Location. Para obtener más información acerca de la respuesta de una dirección URL de ubicación, consulte Creación de cuenta de almacenamiento (202 con Location y Retry-After).

Las propiedades de la respuesta pueden variar, pero siempre incluyen el estado de la operación asincrónica.

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

En el ejemplo siguiente se muestran otros valores que puede devolver la operación:

{
    "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}"
    }
}

El objeto de error se devuelve cuando el estado es Failed o Canceled. Todos los demás valores son opcionales. La respuesta que reciba puede ser diferente del ejemplo.

Valores ProvisioningState

Las operaciones que crean, actualizan o eliminan (PUT, PATCH, DELETE) un recurso, normalmente devuelven un valor provisioningState. Cuando una operación finaliza, se devuelve uno de tres valores siguientes:

  • Correcto
  • Errónea
  • Canceled

Todos los demás valores indican que la operación todavía se está ejecutando. El proveedor de recursos puede devolver un valor personalizado que indica su estado. Por ejemplo, recibe Aceptada cuando la solicitud se ha recibido y está en ejecución.

Solicitudes y respuestas de ejemplo

Inicio de máquina virtual (202 con Azure-AsyncOperation)

En este ejemplo se muestra cómo determinar el estado de la operación start para máquinas virtuales. La solicitud inicial está en el formato siguiente:

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

Devuelve el código de estado 202. Entre los valores de encabezado, verá:

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

Para comprobar el estado de la operación asincrónica, envíe otra solicitud a esa dirección URL.

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

El cuerpo de respuesta contiene el estado de la operación:

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

Implementación de recursos (201 con Azure-AsyncOperation)

En este ejemplo se muestra cómo determinar el estado de la operación deployments para implementar recursos en Azure. La solicitud inicial está en el formato siguiente:

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

Devuelve el código de estado 201. El cuerpo de la respuesta incluye:

"provisioningState":"Accepted",

Entre los valores de encabezado, verá:

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

Para comprobar el estado de la operación asincrónica, envíe otra solicitud a esa dirección 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

El cuerpo de respuesta contiene el estado de la operación:

{
    "status": "Running"
}

Cuando haya finalizado la implementación, la respuesta contiene:

{
    "status": "Succeeded"
}

Creación de cuenta de almacenamiento (202 con Location y Retry-After)

Este ejemplo muestra cómo determinar el estado de la operación create para cuentas de almacenamiento. La solicitud inicial está en el formato siguiente:

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

Y el cuerpo de solicitud contiene las propiedades de la cuenta de almacenamiento:

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

Devuelve el código de estado 202. Entre los valores de encabezado, vea los dos valores siguientes:

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

Después de esperar el número de segundos especificados en Retry-After, compruebe el estado de la operación asincrónica mediante el envío de otra solicitud a esa dirección URL.

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

Si la solicitud aún se está ejecutando, recibe un código de estado 202. Si la solicitud se ha completado, recibirá un código de estado 200. El cuerpo de la respuesta contiene las propiedades de la cuenta de almacenamiento que se ha creado.

Pasos siguientes