追蹤非同步 Azure 作業

  • 發行項

某些 Azure REST 作業因為無法快速完成，而以非同步方式執行。 本文說明如何透過回應中傳回的值，以追蹤非同步作業的狀態。

非同步作業的狀態碼

非同步作業最初會傳回下列其中一個 HTTP 狀態碼︰

  • 201 (已建立)
  • 202 (已接受)

不過，該狀態碼不一定表示作業為非同步。 非同步作業也會傳回 provisioningState 值，指出作業尚未完成。 此值可能會因作業而異，但不會包含成功、失敗或取消。 這三個值表示作業已完成。 如果未傳回任何 provisioningState 值，表示作業已完成且成功。

作業成功完成時會傳回下列其中一個狀態碼︰

  • 200 (確定)
  • 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 大小下限為 4 KB。

用於追蹤非同步狀態的權限

若要追蹤非同步作業的狀態，您需要資源群組層級的足夠權限。 如果您只有資源層級的權限，您可以啟動作業，但無法追蹤其狀態。 需要資源群組層級的權限，因為用於追蹤狀態的 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 要求和回應

如果您有來自 Azure-AsyncOperation 標頭值的 URL，請將 GET 要求傳送至該 URL。 使用 Retry-After 的值來排程檢查狀態的頻率。 您將會收到指出作業狀態的回應物件。 使用 Location URL 檢查作業的狀態時，系統會傳回不同的回應。 如需位置 URL 回應的詳細資訊，請參閱建立儲存體帳戶 (位置和 Retry-After 的 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}"
    }
}

當狀態為 Failed 或 Canceled 時會傳回錯誤物件。 其他所有值都是選擇性的。 您收到的回應看起來可能會與範例不同。

provisioningState 值

建立、更新或刪除資源的作業 (PUT、PATCH、DELETE) 通常會傳回 provisioningState 值。 作業完成時會傳回下列三個值之一︰

  • 成功
  • 失敗
  • 已取消

其他所有值表示作業仍在執行中。 資源提供者可以傳回自訂值來指出其狀態。 例如，要求已收到且正在執行時，您會收到 Accepted。

要求和回應範例

啟動虛擬機器 (202 與 Azure-AsyncOperation)

這個範例示範如何判斷虛擬機器啟動作業的狀態。 初始要求是下列格式︰

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)

這個範例示範如何判斷資源部署至 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)

這個範例示範如何判斷儲存體帳戶的建立作業狀態。 初始要求是下列格式︰

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。 回應的本文包含剛建立的儲存體帳戶的屬性。

下一步