Azure 비동기 작업 추적

  • 아티클

일부 Azure REST 작업은 작업을 신속하게 완료할 수 없기 때문에 비동기적으로 실행합니다. 이 문서에서는 응답에서 반환되는 값을 통해 비동기 작업의 상태를 추적하는 방법을 설명합니다.

비동기 작업의 상태 코드

비동기 작업은 처음에 다음 중 하나의 HTTP 상태 코드를 반환합니다.

  • 201(만들어짐)
  • 202(수락됨)

그러나 이 상태 코드가 반드시 작업이 비동기적이면 안 됩니다. 또한 비동기 작업은 provisioningState에 대해 작업이 완료되지 않았다는 값을 반환합니다. 값은 작업에 따라 다를 수 있지만 성공, 실패 또는 취소는 포함되지 않습니다. 이 세 가지 값은 작업이 완료되었음을 나타냅니다. provisioningState에 대해 값이 반환되지 않으면 작업이 완료되고 성공한 것입니다.

작업이 성공적으로 완료되면 다음 중 하나를 반환합니다.

  • 200(OK)
  • 204(내용 없음)

REST API 설명서를 참조하여 실행 중인 작업에 대한 응답을 볼 수 있습니다.

201 또는 202 응답 코드를 가져온 후에는 작업의 상태를 모니터링할 준비가 된 것입니다.

상태를 모니터링할 URL

비동기 작업의 상태를 모니터링 하는 방법에는 두 가지가 있습니다. 원래 요청에서 반환된 헤더 값을 검사하여 올바른 방법을 결정합니다. 먼저 다음을 찾습니다.

  • Azure-AsyncOperation - 작업의 진행 상태를 확인하는 URL입니다. 작업이 이 값을 반환하는 경우 작업의 상태를 추적하는 데 사용합니다.
  • Retry-After - 비동기 작업의 상태를 확인하기 전에 대기할 시간(초)입니다.

Azure-AsyncOperation가 헤더 값 중 하나가 아닌 경우 다음을 찾습니다.

  • Location - 작업 완료 시기를 결정하기 위한 URL입니다. Azure-AsyncOperation이 반환되지 않은 경우 이 값만 사용합니다.
  • Retry-After - 비동기 작업의 상태를 확인하기 전에 대기할 시간(초)입니다.

Retry-after 헤더가 반환되지 않으면 고유의 다시 시도 논리를 구현합니다.

참고 항목

REST 클라이언트는 Azure-AsyncOperation 및 Location에 대해 최소 URL 크기인 4KB를 허용해야 합니다.

비동기 상태 추적을 위한 권한

비동기 작업의 상태를 추적하려면 리소스 그룹 수준에서 충분한 권한이 필요합니다. 리소스 수준의 권한만 있는 경우 작업을 시작할 수 있지만 상태를 추적할 수는 없습니다. 상태 추적을 위한 URL의 범위가 리소스로 지정되지 않으므로 리소스 그룹 수준의 권한이 필요합니다.

예를 들어, 가상 머신을 시작하려면 가상 머신이 포함된 리소스 그룹에 대한 Virtual Machine Contributor 역할이 필요합니다. 시작 요청을 추적하기 위한 URL에는 해당 경로에 가상 머신이 포함되지 않습니다.

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

Azure-AsyncOperation 요청 및 응답

Azure-AsyncOperation 헤더 값의 URL이 있는 경우 해당 URL에 GET 요청을 보냅니다. Retry-After의 값을 사용하여 상태 확인 빈도를 예약합니다. 작업 상태를 나타내는 응답 개체를 가져옵니다. Location URL로 작업 상태를 확인할 때 다른 응답이 반환됩니다. 위치 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}"
    }
}

상태가 실패함 또는 취소됨인 경우 오류 개체가 반환됩니다. 다른 모든 값은 선택 사항입니다. 수신하는 응답은 예제와 다를 수 있습니다.

provisioningState 값

리소스 만들기, 업데이트 또는 삭제(PUT, PATCH, DELETE)하는 작업은 일반적으로 provisioningState 값을 반환합니다. 작업이 완료되면 다음 세 가지 값 중 하나가 반환됩니다.

  • 성공
  • 실패함
  • 취소됨

다른 값은 모두 작업이 계속 실행 중임을 나타냅니다. 리소스 공급자는 해당 상태를 표시하는 사용자 지정된 값을 반환할 수 있습니다. 예를 들어, 요청이 수신되어 실행되면 수락됨이라는 메시지가 표시됩니다.

예제 요청 및 응답

가상 머신 시작(Azure-AsyncOperation에서 202)

이 예제에서는 가상 머신의 시작 작업 상태를 확인하는 방법을 보여줍니다. 초기 요청은 다음 형식으로 되어 있습니다.

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

리소스 배포(Azure-AsyncOperation에서 201)

이 예제에서는 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"
}

스토리지 계정 만들기(위치 및 Retry-After에서 202)

이 예제에서는 스토리지 계정의 만들기 작업 상태를 확인하는 방법을 보여줍니다. 초기 요청은 다음 형식으로 되어 있습니다.

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을 받게 됩니다. 응답 본문에는 생성된 스토리지 계정의 속성이 포함되어 있습니다.

다음 단계