Controlar operações assíncronas do Azure

  • Artigo

Algumas operações REST do Azure são executadas de forma assíncrona porque a operação não pode ser concluída rapidamente. Este artigo descreve como controlar o status de operações assíncronas por meio de valores retornados na resposta.

Códigos de status para operações assíncronas

Uma operação assíncrona inicialmente retorna um código de status HTTP de:

  • 201 (Criado)
  • 202 (Aceito)

No entanto, esse código de status não significa necessariamente que a operação é assíncrona. Uma operação assíncrona também retorna um valor que indica que provisioningState a operação não foi concluída. O valor pode variar de acordo com a operação, mas não inclui Êxito, Falha ou Cancelado. Esses três valores indicam a operação concluída. Se nenhum valor for retornado para provisioningState, a operação foi concluída e bem-sucedida.

Quando a operação é concluída com êxito, ela retorna:

  • 200 (OK)
  • 204 (Sem conteúdo)

Consulte a documentação da API REST para ver as respostas para a operação que você está executando.

Depois de obter o código de resposta 201 ou 202, você está pronto para monitorar o status da operação.

URL para monitorar o status

Há duas maneiras diferentes de monitorar o status da operação assíncrona. Você determina a abordagem correta examinando os valores de cabeçalho retornados da solicitação original. Primeiro, procure:

  • Azure-AsyncOperation - URL para verificar o estado em curso da operação. Se sua operação retornar esse valor, use-o para acompanhar o status da operação.
  • Retry-After - O número de segundos a aguardar antes de verificar o estado da operação assíncrona.

Se Azure-AsyncOperation não for um dos valores de cabeçalho, procure:

  • Location - URL para determinar quando uma operação é concluída. Use esse valor somente quando Azure-AsyncOperation não for retornado.
  • Retry-After - O número de segundos a aguardar antes de verificar o estado da operação assíncrona.

Quando o Retry-after cabeçalho não for retornado, implemente sua própria lógica de repetição.

Nota

Seu cliente REST deve aceitar um tamanho mínimo de URL de 4 KB para Azure-AsyncOperation e Location.

Permissão para rastrear o status assíncrono

Para controlar o status de uma operação assíncrona, você precisa de permissão suficiente no nível do grupo de recursos. Se você só tiver permissão no nível do recurso, poderá iniciar a operação, mas não poderá acompanhar seu status. A permissão no nível do grupo de recursos é necessária porque a URL para o status de acompanhamento não tem escopo para o recurso.

Por exemplo, para iniciar uma máquina virtual, você precisa da função de Colaborador de Máquina Virtual para o grupo de recursos que contém a máquina virtual. A URL para rastrear uma solicitação de início não inclui a máquina virtual em seu caminho.

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

Solicitação e resposta Azure-AsyncOperation

Se você tiver uma URL do valor do Azure-AsyncOperation cabeçalho, envie uma solicitação GET para essa URL. Use o valor de Retry-After para agendar com que frequência verificar o status. Você obtém um objeto de resposta que indica o status da operação. Uma resposta diferente é retornada ao verificar o status da operação com a Location URL. Para obter mais informações sobre a resposta de uma URL de local, consulte Criar conta de armazenamento (202 com Localização e Repetir Depois).

As propriedades de resposta podem variar, mas sempre incluem o status da operação assíncrona.

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

O exemplo a seguir mostra outros valores que podem ser retornados da operação:

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

O objeto de erro é retornado quando o status é Falha ou Cancelado. Todos os outros valores são opcionais. A resposta recebida pode parecer diferente do exemplo.

provisioningState valores

As operações que criam, atualizam ou excluem (PUT, PATCH, DELETE) um recurso normalmente retornam um provisioningState valor. Quando uma operação é concluída, um dos três valores a seguir é retornado:

  • Efetuado com êxito
  • Falha
  • Cancelado

Todos os outros valores indicam que a operação ainda está em execução. O provedor de recursos pode retornar um valor personalizado que indica seu estado. Por exemplo, você recebe Aceito quando a solicitação é recebida e executada.

Exemplos de pedidos e respostas

Iniciar máquina virtual (202 com Azure-AsyncOperation)

Este exemplo mostra como determinar o status da operação de início para máquinas virtuais. O pedido inicial está no seguinte formato:

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

Ele retorna o código de status 202. Entre os valores de cabeçalho, você vê:

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

Para verificar o status da operação assíncrona, envie outra solicitação para essa URL.

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

O corpo da resposta contém o status da operação:

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

Implantar recursos (201 com Azure-AsyncOperation)

Este exemplo mostra como determinar o status da operação de implantações para implantar recursos no Azure. O pedido inicial está no seguinte formato:

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

Ele retorna o código de status 201. O corpo da resposta inclui:

"provisioningState":"Accepted",

Entre os valores de cabeçalho, você vê:

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 verificar o status da operação assíncrona, envie outra solicitação para essa 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

O corpo da resposta contém o status da operação:

{
    "status": "Running"
}

Quando a implantação estiver concluída, a resposta contém:

{
    "status": "Succeeded"
}

Criar conta de armazenamento (202 com Localização e Repetir-Depois)

Este exemplo mostra como determinar o status da operação de criação para contas de armazenamento. O pedido inicial está no seguinte formato:

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

E o corpo da solicitação contém propriedades para a conta de armazenamento:

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

Ele retorna o código de status 202. Entre os valores de cabeçalho, você verá os dois valores a seguir:

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

Depois de aguardar o número de segundos especificado em Retry-After, verifique o status da operação assíncrona enviando outra solicitação para essa URL.

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

Se a solicitação ainda estiver em execução, você receberá um código de status 202. Se a solicitação for concluída, você receberá um código de status 200. O corpo da resposta contém as propriedades da conta de armazenamento que foi criada.

Próximos passos