Rozhraní API pro operace creatoru Long-Running v2
Některá rozhraní API v Azure Maps používají asynchronní vzor Request-Reply. Tento model umožňuje Azure Maps poskytovat vysoce dostupné a responzivní služby. Tento článek vysvětluje specifickou implementaci dlouhotrvajícího asynchronního zpracování na pozadí ve službě Azure Map.
Odeslat žádost
Klientská aplikace spustí dlouhotrvající operaci prostřednictvím synchronního volání rozhraní HTTP API. Toto volání je obvykle ve formě požadavku HTTP POST. Po úspěšném vytvoření asynchronní úlohy vrátí rozhraní API stavový kód HTTP 202
, který označuje, že požadavek byl přijat. Tato odpověď obsahuje hlavičku Location
ukazující na koncový bod, na který se klient může dotazovat, aby zkontroloval stav dlouhotrvající operace.
Příklad úspěšné odpovědi
Status: 202 Accepted
Operation-Location: https://atlas.microsoft.com/service/operations/{operationId}
Pokud volání neprojde ověřením, vrátí rozhraní API odpověď HTTP 400
pro chybný požadavek. Text odpovědi poskytuje klientovi další informace o tom, proč byl požadavek neplatný.
Monitorování stavu operace
Koncový bod umístění uvedený v hlavičkách akceptovaných odpovědí se dá dotazovat, aby se zkontroloval stav dlouhotrvající operace. Text odpovědi z požadavku na stav operace vždy obsahuje status
vlastnosti a created
. Vlastnost status
zobrazuje aktuální stav dlouhotrvající operace. Mezi možné stavy patří "NotStarted"
, "Succeeded"
"Running"
, a "Failed"
. Vlastnost created
zobrazuje čas, kdy byl proveden počáteční požadavek na spuštění dlouhotrvající operace. Pokud je stav buď "NotStarted"
nebo "Running"
, Retry-After
je s odpovědí k dispozici také hlavička. Hlavička Retry-After
měřená v sekundách se dá použít k určení, kdy se má provést další volání dotazování do rozhraní API pro stav operace.
Příklad spuštění odpovědi na stav
Status: 200 OK
Retry-After: 30
{
"operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
"created": "3/11/2020 8:45:13 PM +00:00",
"status": "Running"
}
Zpracování dokončení operace
Po dokončení dlouhotrvající operace je stav odpovědi buď "Succeeded"
nebo "Failed"
. Všechny odpovědi vrátí kód HTTP 200 OK. Při vytvoření nového prostředku z dlouhotrvající operace obsahuje odpověď také hlavičku Resource-Location
, která odkazuje na metadata o prostředku. V případě selhání má error
odpověď v těle vlastnost. Data o chybách odpovídají specifikaci chyby OData.
Příklad úspěšné odezvy
Status: 200 OK
Resource-Location: "https://atlas.microsoft.com/tileset/{tileset-id}"
{
"operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
"created": "2021-05-06T07:55:19.5256829+00:00",
"status": "Succeeded"
}
Příklad odpovědi na selhání
Status: 200 OK
{
"operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
"created": "3/11/2020 8:45:13 PM +00:00",
"status": "Failed",
"error": {
"code": "InvalidFeature",
"message": "The provided feature is invalid.",
"details": {
"code": "NoGeometry",
"message": "No geometry was provided with the feature."
}
}
}