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

  • Статья

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

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

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

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

Однако этот код состояния не обязательно означает, что операция является асинхронной. Асинхронная операция также возвращает значение, 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 с расположением и повторными попытками).

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

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

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

Значения provisioningState

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

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

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

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

Запуск виртуальной машины (код 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. В тексте ответа будут содержаться свойства созданной учетной записи хранения.

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