Sledování asynchronních operací Azure

  • Článek

Některé operace Azure REST běží asynchronně, protože operaci nejde rychle dokončit. Tento článek popisuje, jak sledovat stav asynchronních operací prostřednictvím hodnot vrácených v odpovědi.

Stavové kódy pro asynchronní operace

Asynchronní operace zpočátku vrátí stavový kód HTTP:

  • 201 (vytvořeno)
  • 202 (přijato)

Tento stavový kód ale nemusí nutně znamenat, že operace je asynchronní. Asynchronní operace také vrátí hodnotu provisioningState , která označuje, že operace není dokončena. Hodnota se může lišit podle operace, ale nezahrnuje úspěšné, neúspěšné nebo zrušené. Tyto tři hodnoty označují dokončení operace. Pokud není vrácena žádná hodnota , provisioningStateoperace byla dokončena a úspěšná.

Po úspěšném dokončení operace vrátí jednu z těchto operací:

  • 200 (OK)
  • 204 (bez obsahu)

Odpovědi na operaci, kterou spouštíte, najdete v dokumentaci k rozhraní REST API.

Po získání kódu odpovědi 201 nebo 202 jste připraveni monitorovat stav operace.

Adresa URL pro monitorování stavu

Stav asynchronní operace lze monitorovat dvěma různými způsoby. Správný přístup určíte prozkoumáním hodnot hlaviček vrácených z původního požadavku. Nejprve vyhledejte:

  • Azure-AsyncOperation – Adresa URL pro kontrolu probíhajícího stavu operace. Pokud vaše operace vrátí tuto hodnotu, použijte ji ke sledování stavu operace.
  • Retry-After – Počet sekund čekání před kontrolou stavu asynchronní operace.

Pokud Azure-AsyncOperation není jedna z hodnot záhlaví, vyhledejte:

  • Location – Adresa URL pro určení, kdy je operace dokončena. Tuto hodnotu použijte pouze v případě, že Azure-AsyncOperation se nevrátí.
  • Retry-After – Počet sekund čekání před kontrolou stavu asynchronní operace.

Pokud se hlavička Retry-after nevrátí, implementujte vlastní logiku opakování.

Poznámka:

Klient REST musí přijmout minimální velikost adresy URL 4 kB pro Azure-AsyncOperation a Location.

Oprávnění ke sledování stavu asynchronní synchronizace

Ke sledování stavu asynchronní operace potřebujete dostatečná oprávnění na úrovni skupiny prostředků. Pokud máte oprávnění jenom na úrovni prostředku, můžete operaci spustit, ale nemůžete sledovat její stav. Oprávnění na úrovni skupiny prostředků se vyžaduje, protože adresa URL pro sledování stavu není vymezená na prostředek.

Například ke spuštění virtuálního počítače potřebujete roli Přispěvatel virtuálních počítačů pro skupinu prostředků, která obsahuje virtuální počítač. Adresa URL pro sledování počátečního požadavku neobsahuje virtuální počítač v cestě.

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

Požadavek a odpověď Azure-AsyncOperation

Pokud máte adresu URL z Azure-AsyncOperation hodnoty hlavičky, odešlete na tuto adresu URL požadavek GET. Pomocí hodnoty z Retry-After můžete naplánovat, jak často se má stav kontrolovat. Získáte objekt odpovědi, který označuje stav operace. Při kontrole stavu operace s Location adresou URL se vrátí jiná odpověď. Další informace o odpovědi z adresy URL umístění najdete v tématu Vytvoření účtu úložiště (202 s umístěním a opakováním).

Vlastnosti odpovědi se mohou lišit, ale vždy zahrnují stav asynchronní operace.

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

Následující příklad ukazuje další hodnoty, které by mohly být vráceny z operace:

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

Objekt chyby se vrátí, když je stav Selhání nebo Zrušeno. Všechny ostatní hodnoty jsou volitelné. Odpověď, kterou obdržíte, může vypadat jinak než v příkladu.

provisioningState values

Operace, které vytvářejí, aktualizují nebo odstraňou (PUT, PATCH, DELETE) prostředek obvykle vrací provisioningState hodnotu. Po dokončení operace se vrátí jedna z následujících tří hodnot:

  • Úspěch
  • Neúspěšné
  • Zrušeno

Všechny ostatní hodnoty označují, že operace je stále spuštěná. Poskytovatel prostředků může vrátit přizpůsobenou hodnotu, která označuje její stav. Například obdržíte Přijato při přijetí a spuštění požadavku.

Příklady požadavků a odpovědí

Spuštění virtuálního počítače (202 s Azure-AsyncOperation)

Tento příklad ukazuje, jak určit stav operace spuštění pro virtuální počítače. Počáteční požadavek je v následujícím formátu:

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

Vrátí stavový kód 202. Mezi hodnotami záhlaví vidíte:

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

Pokud chcete zkontrolovat stav asynchronní operace, odešlete na adresu URL další požadavek.

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

Text odpovědi obsahuje stav operace:

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

Nasazení prostředků (201 s Využitím Azure-AsyncOperation)

Tento příklad ukazuje, jak určit stav operace nasazení pro nasazení prostředků do Azure. Počáteční požadavek je v následujícím formátu:

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

Vrátí stavový kód 201. Text odpovědi zahrnuje:

"provisioningState":"Accepted",

Mezi hodnotami záhlaví vidíte:

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

Pokud chcete zkontrolovat stav asynchronní operace, odešlete na danou adresu URL další požadavek.

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

Text odpovědi obsahuje stav operace:

{
    "status": "Running"
}

Po dokončení nasazení obsahuje odpověď:

{
    "status": "Succeeded"
}

Vytvoření účtu úložiště (202 s umístěním a opakováním po)

Tento příklad ukazuje, jak určit stav operace vytvoření pro účty úložiště. Počáteční požadavek je v následujícím formátu:

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

Tělo požadavku obsahuje vlastnosti pro účet úložiště:

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

Vrátí stavový kód 202. Mezi hodnotami záhlaví vidíte následující dvě hodnoty:

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

Po čekání na počet sekund zadaných v příkazu Opakovat až po zkontrolujte stav asynchronní operace odesláním dalšího požadavku na danou adresu URL.

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

Pokud požadavek stále běží, obdržíte stavový kód 202. Pokud je žádost dokončena, obdržíte stavový kód 200. Tělo odpovědi obsahuje vlastnosti vytvořeného účtu úložiště.

Další kroky