Creator-API V2 für zeitintensive Vorgänge

Artikel
04/20/2023

Einige APIs in Azure Maps verwenden ein asynchrones Anforderung-Antwort-Muster. Dieses Muster ermöglicht Azure Maps die Bereitstellung hochverfügbarer und reaktionsfähiger Dienste. In diesem Artikel wird die für Azure Maps spezifische Implementierung der zeitintensiven asynchronen Hintergrundverarbeitung erläutert.

Anforderung senden

Eine Clientanwendung startet einen zeitintensiven Vorgang durch den synchronen Aufruf einer HTTP-API. Dieser Befehl erfolgt in der Regel in Form einer HTTP POST-Anforderung. Bei erfolgreicher Erstellung einer asynchronen Workload gibt die API den HTTP-Statuscode 202 zurück, was darauf hinweist, dass die Anforderung akzeptiert wurde. Die Antwort enthält einen Location-Header, der auf einen Endpunkt verweist, den der Client abfragen kann, um den Status des zeitintensiven Vorgangs zu überprüfen.

Beispiel für eine erfolgreiche Antwort

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

Wenn der Aufruf nicht validiert werden konnte, gibt die API die HTTP-Antwort 400 für eine ungültige Anforderung zurück. Der Antworttext liefert dem Client weitere Informationen darüber, warum die Anforderung ungültig war.

Überwachen des Vorgangsstatus

Der in den akzeptierten Antwortheadern angegebene Standortendpunkt kann abgerufen werden, um den Status des zeitintensiven Vorgangs überprüfen. Der Antworttext der Vorgangsstatusanforderung enthält immer die Eigenschaften status und created. Die Eigenschaft status zeigt den aktuellen Status eines zeitintensiven Vorgangs an. Mögliche Werte sind "NotStarted", "Running", "Succeeded" und "Failed". Die Eigenschaft created gibt die Zeit an, zu der die anfängliche Anforderung gesendet wurde, um den zeitintensiven Vorgang zu starten. Wenn der Zustand "NotStarted" oder "Running" lautet, enthält die Antwort auch einen Retry-After-Header. Mithilfe des Headers vom Typ Retry-After (gemessen in Sekunden) kann ermittelt werden, wann der nächste Abfrageaufruf für die Vorgangsstatus-API erfolgen soll.

Beispiel für das Ausführen einer Statusantwort

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

Behandeln des Vorgangsabschlusses

Wenn der zeitintensive Vorgang beendet ist, lautet der Status der Antwort entweder "Succeeded" oder "Failed". Alle Antworten geben einen HTTP 200-Code (OK) zurück. Wenn bei einem zeitintensiven Vorgang eine neue Ressource erstellt wurde, enthält die Antwort auch einen Resource-Location-Header, der auf Metadaten zur Ressource zeigt. Bei einem Fehler enthält die Antwort die Eigenschaft error im Haupttext. Die Fehlerdaten entsprechen der OData-Fehlerspezifikation.

Beispiel für eine Erfolgsantwort

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

Beispiel für eine Fehlerantwort

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

Share via