Interfejs API operacji Long-Running twórcy w wersji 2

Niektóre interfejsy API w Azure Maps używają asynchronicznego wzorca Request-Reply. Ten wzorzec umożliwia Azure Maps zapewnienie wysokiej dostępności i dynamicznych usług. W tym artykule opisano konkretną implementację usługi Azure Map długotrwałego przetwarzania asynchronicznego w tle.

Prześlij żądanie

Aplikacja kliencka uruchamia długotrwałą operację za pośrednictwem synchronicznego wywołania interfejsu API HTTP. Zazwyczaj to wywołanie jest w postaci żądania HTTP POST. Po pomyślnym utworzeniu obciążenia asynchronicznego interfejs API zwraca kod stanu HTTP 202 wskazujący, że żądanie zostało zaakceptowane. Ta odpowiedź zawiera nagłówek wskazujący Location punkt końcowy, który klient może sondować, aby sprawdzić stan długotrwałej operacji.

Przykład odpowiedzi na powodzenie

Status: 202 Accepted
Operation-Location: https://atlas.microsoft.com/service/operations/{operationId} 

Jeśli wywołanie nie przejdzie walidacji, interfejs API zwróci odpowiedź HTTP 400 dla nieprawidłowego żądania. Treść odpowiedzi zawiera więcej informacji o tym, dlaczego żądanie było nieprawidłowe.

Monitorowanie stanu operacji

Punkt końcowy lokalizacji podany w akceptowanych nagłówkach odpowiedzi można sondować, aby sprawdzić stan długotrwałej operacji. Treść odpowiedzi z żądania stanu operacji zawsze zawiera status właściwości i created . Właściwość status pokazuje bieżący stan długotrwałej operacji. Możliwe stany obejmują "NotStarted", , "Succeeded""Running"i "Failed". Właściwość created pokazuje czas wykonania początkowego żądania, aby rozpocząć długotrwałą operację. Gdy stan to "NotStarted" lub "Running", Retry-After nagłówek jest również dostarczany z odpowiedzią. Nagłówek Retry-After mierzony w sekundach może służyć do określenia, kiedy powinno zostać wykonane następne wywołanie sondowania do interfejsu API stanu operacji.

Przykład uruchamiania odpowiedzi o stanie

Status: 200 OK
Retry-After: 30
{
    "operationId": "c587574e-add9-4ef7-9788-1635bed9a87e",
    "created": "3/11/2020 8:45:13 PM +00:00",
    "status": "Running"
}

Obsługa ukończenia operacji

Po zakończeniu długotrwałej operacji stan odpowiedzi to "Succeeded" lub "Failed". Wszystkie odpowiedzi zwracają kod HTTP 200 OK. Po utworzeniu nowego zasobu na podstawie długotrwałej operacji odpowiedź zawiera Resource-Location również nagłówek wskazujący metadane dotyczące zasobu. Po awarii odpowiedź ma error właściwość w treści. Dane o błędach są zgodne ze specyfikacją błędu OData.

Przykład odpowiedzi na powodzenie

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

Przykład odpowiedzi na błędy

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