Nachverfolgen asynchroner Vorgänge in Azure

  • Artikel

Einige Azure-REST-Vorgänge werden asynchron ausgeführt, da sie nicht schnell abgeschlossen werden können. In diesem Artikel wird beschrieben, wie der Status asynchroner Vorgänge mithilfe von Werten nachverfolgt wird, die in der Antwort zurückgegeben werden.

Statuscodes für asynchrone Vorgänge

Ein asynchroner Vorgang gibt anfänglich einen dieser HTTP-Statuscodes zurück:

  • 201 (Erstellt)
  • 202 (Akzeptiert)

Dieser Statuscode bedeutet jedoch nicht notwendigerweise, dass der Vorgang asynchron ist. Ein asynchroner Vorgang gibt auch einen Wert für provisioningState zurück, der angibt, dass der Vorgang noch nicht abgeschlossen ist. Der Wert kann je nach Vorgang variieren, enthält jedoch nicht die Angabe Erfolgreich, Fehlerhaft oder Abgebrochen. Diese drei Werte zeigen an, dass der Vorgang abgeschlossen wurde. Wird kein Wert für provisioningState zurückgegeben, wurde der Vorgang abgeschlossen und war erfolgreich.

Wenn der Vorgang erfolgreich abgeschlossen wurde, wird einer dieser Statuscodes zurückgegeben:

  • 200 (OK)
  • 204 (Kein Inhalt)

In der REST-API-Dokumentation finden Sie Informationen zu den Antworten für den Vorgang, den Sie ausführen.

Nachdem Sie den Antwortcode 201 oder 202 erhalten haben, können Sie den Status des Vorgangs überwachen.

URL zur Überwachung des Status

Es gibt zwei verschiedene Möglichkeiten, den Status des asynchronen Vorgangs zu überwachen. Sie bestimmen den richtigen Ansatz, indem Sie die Headerwerte untersuchen, die von der ursprünglichen Anforderung zurückgegeben werden. Schauen Sie zuerst nach:

  • Azure-AsyncOperation: URL zur Überprüfung des aktuellen Status des Vorgangs. Wenn der Vorgang diesen Wert zurückgibt, verwenden Sie ihn, um den Status des Vorgangs nachzuverfolgen.
  • Retry-After: Abzuwartende Anzahl von Sekunden vor dem Überprüfen des Status des asynchronen Vorgangs.

Wenn Azure-AsyncOperation keiner der Headerwerte ist, suchen Sie nach:

  • Location: URL zum Bestimmen, wann ein Vorgang abgeschlossen wurde. Verwenden Sie diesen Wert, wenn Azure-AsyncOperation nicht zurückgegeben wird.
  • Retry-After: Abzuwartende Anzahl von Sekunden vor dem Überprüfen des Status des asynchronen Vorgangs.

Wenn der Retry-after-Header nicht zurückgegeben wird, implementieren Sie Ihre eigene Wiederholungslogik.

Hinweis

Ihr REST-Client muss eine Mindestgröße der URL von 4 KB für Azure-AsyncOperation und Location akzeptieren.

Berechtigung zum Nachverfolgen des asynchronen Status

Um den Status eines asynchronen Vorgangs nachzuverfolgen, benötigen Sie ausreichende Berechtigungen auf der Ebene der Ressourcengruppe. Wenn Sie über eine Berechtigung nur auf der Ebene der Ressource verfügen, können Sie den Vorgang zwar starten, aber den Status nicht nachverfolgen. Die Berechtigung auf Ebene der Ressourcengruppe ist erforderlich, da die URL für den Nachverfolgungsstatus nicht auf die Ressource eingegrenzt ist.

Um beispielsweise eine VM zu starten, benötigen Sie die Rolle „Mitwirkender für VM“ für die Ressourcengruppe mit der VM. Die URL zum Nachverfolgen einer Startanforderung enthält in ihrem Pfad nicht die VM.

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

Anforderung „Azure-AsyncOperation“ und Antwort

Wenn Sie über eine URL aus dem Headerwert Azure-AsyncOperation verfügen, senden Sie eine GET-Anforderung an die URL. Verwenden Sie den Wert aus Retry-After, um zu planen, wie oft der Status überprüft werden soll. Sie erhalten ein Antwortobjekt, das den Status des Vorgangs angibt. Beim Überprüfen des Status des Vorgangs mit der Location-URL wird eine andere Antwort zurückgegeben. Weitere Informationen zur Antwort von einer Location-URL finden Sie unter Erstellen eines Speicherkontos (202 bei „Location“ und „Retry-After“).

Die Antworteigenschaften können variieren, schließen aber immer den Status des asynchronen Vorgangs ein.

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

Das folgende Beispiel zeigt andere Werte, die vom Vorgang zurückgegeben werden könnten:

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

Das Fehlerobjekt wird zurückgegeben, wenn der Status „Failed“ oder „Canceled“ ist. Alle anderen Werte sind optional. Die Antwort, die Sie erhalten, kann sich vom Beispiel unterscheiden.

„provisioningState“-Werte

Vorgänge zum Erstellen, Aktualisieren oder Löschen (PUT, PATCH, DELETE) einer Ressource geben in der Regel einen provisioningState-Wert zurück. Wenn ein Vorgang abgeschlossen wurde, wird einer der folgenden drei Werte zurückgegeben:

  • Erfolgreich
  • Fehler
  • Canceled

Alle anderen Werte bedeuten, dass der Vorgang noch ausgeführt wird. Der Ressourcenanbieter kann einen benutzerdefinierten Wert zurückgeben, der seinen Status angibt. Sie erhalten z. B. Accepted, wenn die Anforderung empfangen wurde und ausgeführt wird.

Beispielanforderungen und -antworten

Starten des virtuellen Computers (202 bei „Azure-AsyncOperation“)

In diesem Beispiel wird gezeigt, wie der Status des Vorgangs Starten für virtuelle Computer bestimmt wird. Die ursprüngliche Anforderung hat das folgende Format:

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

Sie gibt den Statuscode 202 zurück. Unter den Headerwerten finden Sie:

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

Um den Status des asynchronen Vorgangs zu überprüfen, senden Sie eine weitere Anforderung an diese URL.

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

Der Antworttext enthält den Status des Vorgangs:

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

Bereitstellen von Ressourcen (201 bei „Azure-AsyncOperation“)

In diesem Beispiel wird gezeigt, wie der Status des Vorgangs Bereitstellung für die Bereitstellung von Ressourcen in Azure bestimmt wird. Die ursprüngliche Anforderung hat das folgende Format:

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

Sie gibt den Statuscode 201 zurück. Der Antworttext enthält Folgendes:

"provisioningState":"Accepted",

Unter den Headerwerten finden Sie:

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

Um den Status des asynchronen Vorgangs zu überprüfen, senden Sie eine weitere Anforderung an diese URL.

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

Der Antworttext enthält den Status des Vorgangs:

{
    "status": "Running"
}

Wenn die Bereitstellung abgeschlossen ist, enthält die Antwort Folgendes:

{
    "status": "Succeeded"
}

Erstellen eines Speicherkontos (202 bei „Location“ und „Retry-After“)

In diesem Beispiel wird gezeigt, wie der Status des Vorgangs Erstellen für Speicherkonten bestimmt wird. Die ursprüngliche Anforderung hat das folgende Format:

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

Und der Anforderungstext enthält Eigenschaften für das Speicherkonto:

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

Sie gibt den Statuscode 202 zurück. In den Headerwerten finden Sie die folgenden beiden Werte:

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

Überprüfen Sie nach Abwarten der in „Retry-After“ angegebenen Anzahl von Sekunden den Status des asynchronen Vorgangs, indem Sie eine weitere Anforderung an diese URL senden.

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

Wenn die Anforderung noch ausgeführt wird, erhalten Sie den Statuscode 202. Wenn die Anforderung abgeschlossen ist, erhalten Sie den Statuscode 200. Der Textkörper der Antwort enthält die Eigenschaften des erstellten Speicherkontos.

Nächste Schritte