Compartilhar via

Rastrear operações assíncronas no 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 com rapidez. Este artigo descreve como controlar o status das operações assíncronas por meio de valores retornados na resposta.

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

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

  • 201 (Criado)
  • 202 (Aceito)

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

Quando a operação for concluída com êxito, ela retorna um dos seguintes:

  • 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ê estará 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 ‑ A URL para verificar o status da operação em andamento. Se a operação retornar esse valor, sempre o use para acompanhar o status da operação.
  • Retry-After ‑ O número de segundos de espera antes de verificar o status 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 de espera antes de verificar o status da operação assíncrona.

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

Observação

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 rastrear o status de uma operação assíncrona, você precisa de permissão suficiente no nível do grupo de recursos. Se você tiver permissão apenas 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 o URL para rastrear o status 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 acompanhamento de 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 de Azure-AsyncOperation

Se você tiver uma URL no valor de cabeçalho Azure-AsyncOperation, 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 URL Location. Para obter mais informações sobre a resposta de uma URL de localização, veja Criar conta de armazenamento (202 com Location e Retry-After).

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 que você recebe pode ter uma aparência diferente em relação à do exemplo.

Valores de provisioningState

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

  • Com sucesso
  • Falha
  • Canceled

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 o estado. Por exemplo, você recebe Aceito quando a solicitação é recebida e está em execução.

Exemplo de solicitações e respostas

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

Este exemplo mostra como determinar o status da operação start para máquinas virtuais. A solicitação 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 um código de status 202. Entre os valores de cabeçalho, você verá:

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 deployments para implantação de recursos no Azure. A solicitação 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 um código de status 201. O corpo da resposta inclui:

"provisioningState":"Accepted",

Entre os valores de cabeçalho, você 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 verificar o status da operação assíncrona, envie outra solicitação para a 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 for concluída, a resposta conterá:

{
    "status": "Succeeded"
}

Criar conta de armazenamento (202 com Location e Retry-After)

Este exemplo mostra como determinar o status da operação create para contas de armazenamento. A solicitação 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 as propriedades da conta de armazenamento:

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

Ele retorna um 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 a 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óximas etapas