Отслеживание асинхронных операций Azure

Некоторые операции REST выполняются в Azure асинхронно, поскольку не могут быть быстро завершены. Из этой статьи вы узнаете, как отслеживать состояние асинхронных операций, используя возвращаемые в ответе значения.

Коды состояния для асинхронных операций

Изначально асинхронная операция возвращает один из следующих кодов состояния HTTP:

  • 201 Created (создано);
  • 202 (Принято)

Однако этот код состояния не обязательно означает, что операция является асинхронной. Асинхронная операция также возвращает значение, provisioningState указывающее, что операция не завершена. Значение может отличаться по операции, но не включает в себя успешное выполнение, сбой или отмену. Эти три значения указывают на завершение операции. Если значение не возвращается для provisioningState, это операция завершена, и выполнена успешно.

После успешного завершения операции возвращаются следующие коды:

  • 200 OK;
  • 204 No Content (нет содержимого).

Ответы по выполняемой операции описаны в разделе Документация по REST API.

После получения кода ответа 201 или 202 вы можете отслеживать состояние операции.

URL-адрес для отслеживания состояния

Существует два разных способа отслеживания состояния асинхронной операции. Правильный подход определяется путем проверки значений заголовков, возвращаемых в ответ на ваш исходный запрос. Вначале найдите:

  • Azure-AsyncOperation — это URL-адрес для проверки текущего состояния операции. Если ваша операция возвращает это значение, используйте его для отслеживания статуса операции.
  • Retry-After — это количество секунд ожидания перед проверкой состояния асинхронной операции.

Если Azure-AsyncOperation не является одним из значений заголовка, найдите:

  • Location — URL-адрес для определения завершения операции. Используйте это значение только в том случае, если Azure-AsyncOperation не возвращается.
  • Retry-After — это количество секунд ожидания перед проверкой состояния асинхронной операции.

Retry-after Если заголовок не возвращается, реализуйте собственную логику повторных попыток.

Примечание.

Клиент REST должен принимать минимальный размер URL-адреса в 4 КБ для Azure-AsyncOperation и Location.

Разрешение для отслеживания асинхронного состояния

Чтобы отслеживать состояние асинхронной операции, необходимо достаточное разрешение на уровне группы ресурсов. Если у вас есть разрешение только на уровне ресурса, можно запустить операцию, но не удается отслеживать его состояние. Требуется разрешение на уровне группы ресурсов, так как URL-адрес для отслеживания состояния не ограничен ресурсом.

Например, чтобы запустить виртуальную машину, потребуется роль участника виртуальной машины для группы ресурсов, содержащей виртуальную машину. URL для отслеживания запроса запуска не включает виртуальную машину в своем пути.

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

Запрос и ответ с использованием Azure-AsyncOperation

Если у вас есть URL из значения заголовка Azure-AsyncOperation, отправьте GET-запрос на этот URL. Используйте значение из Retry-After, чтобы запланировать частоту проверки состояния. Вы получите объект ответа, указывающий состояние операции. При проверке состояния операции с URL-адресом Location возвращается другой ответ. Дополнительные сведения об ответе с URL-адресом местоположения см. в статье Создание учетной записи хранения (202 с Location и Retry-After).

Свойства ответа могут быть различными, но всегда содержать состояние асинхронной операции.

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

В следующем примере показаны другие значения, которые могут быть возвращены операцией:

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

Объект ошибки возвращается в том случае, если операция находится в состоянии сбоя (Failed) или отмены (Canceled). Все остальные значения необязательны. Полученный ответ может выглядеть не так, как в примере.

Значения состояния выделения ресурсов

Операции, которые создают, обновляют или удаляют ресурсы (PUT, PATCH, DELETE), обычно возвращают значение provisioningState. После завершения операции возвращается одно из следующих трех значений:

  • Выполнено успешно
  • Неудачно
  • Отменена

Любое другое значение означает, что операция еще выполняется. Поставщик ресурсов может возвращать настраиваемое значение, указывающее его состояние. Например, вы получаете Accepted, когда запрос получен и выполняется.

Примеры запросов и ответов

Запуск виртуальной машины (202 с Azure-AsyncOperation)

Здесь показано, как можно проверить состояние операции Start для виртуальных машин. Исходный запрос имеет следующий формат:

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

В ответ получен код состояния 202. Среди значений в заголовке вы видите:

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

Чтобы проверить состояние асинхронной операции, отправьте еще один запрос на этот URL-адрес.

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

Текст ответа содержит состояние операции:

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

Развертывание ресурсов (201 с Azure-AsyncOperation)

Здесь показано, как можно проверить состояние операции deployments для развертывания ресурсов в Azure. Исходный запрос имеет следующий формат:

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

В ответ получен код состояния 201. Текст ответа включает следующие данные:

"provisioningState":"Accepted",

Среди значений в заголовке вы видите:

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

Чтобы проверить состояние асинхронной операции, отправьте еще один запрос на 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

Текст ответа содержит состояние операции:

{
    "status": "Running"
}

После завершения развертывания возвращается ответ с такими данными:

{
    "status": "Succeeded"
}

Создание учетной записи хранения (код 202, значения Location и Retry-After)

Здесь показано, как можно проверить состояние операции create для учетных записей хранения. Исходный запрос имеет следующий формат:

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

Текст запроса содержит свойства для учетной записи хранения:

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

В ответ получен код состояния 202. Среди значений заголовка вы увидите следующие два значения:

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

После ожидания количества секунд, указанных в Retry-Afterзапросе, проверьте состояние асинхронной операции, отправив другой запрос на этот URL-адрес.

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

Если запрос все еще выполняется, вы получите код состояния 202. Если запрос завершен, вы получите код состояния 200. В тексте ответа будут содержаться свойства созданной учетной записи хранения.

Следующие шаги

  • Last updated on