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