Asynchrone Azure-bewerkingen bijhouden

Sommige Azure REST-bewerkingen worden asynchroon uitgevoerd omdat de bewerking niet snel kan worden voltooid. In dit artikel wordt beschreven hoe u de status van asynchrone bewerkingen kunt bijhouden via waarden die in het antwoord worden geretourneerd.

Statuscodes voor asynchrone bewerkingen

Een asynchrone bewerking retourneert in eerste instantie een HTTP-statuscode van een van beide:

  • 201 (gemaakt)
  • 202 (geaccepteerd)

Deze statuscode betekent echter niet noodzakelijkerwijs dat de bewerking asynchroon is. Een asynchrone bewerking retourneert ook een waarde waarmee provisioningState wordt aangegeven dat de bewerking niet is voltooid. De waarde kan per bewerking variƫren, maar bevat geen geslaagde, mislukte of geannuleerde waarde. Deze drie waarden geven aan dat de bewerking is voltooid. Als er geen waarde wordt geretourneerd voor provisioningState, is de bewerking voltooid en geslaagd.

Wanneer de bewerking is voltooid, wordt het volgende geretourneerd:

  • 200 (OK)
  • 204 (geen inhoud)

Raadpleeg de REST API-documentatie om de antwoorden te zien voor de bewerking die u uitvoert.

Nadat u de reactiecode 201 of 202 hebt ontvangen, bent u klaar om de status van de bewerking te controleren.

URL voor het bewaken van de status

Er zijn twee verschillende manieren om de status van de asynchrone bewerking te bewaken. U bepaalt de juiste benadering door de headerwaarden te onderzoeken die worden geretourneerd uit uw oorspronkelijke aanvraag. Zoek eerst naar:

  • Azure-AsyncOperation - URL voor het controleren van de lopende status van de bewerking. Als de bewerking deze waarde retourneert, gebruikt u deze om de status van de bewerking bij te houden.
  • Retry-After - Het aantal seconden dat moet worden gewacht voordat de status van de asynchrone bewerking wordt gecontroleerd.

Als Azure-AsyncOperation dit geen van de headerwaarden is, zoekt u het volgende:

  • Location - URL voor het bepalen wanneer een bewerking is voltooid. Gebruik deze waarde alleen wanneer Azure-AsyncOperation niet wordt geretourneerd.
  • Retry-After - Het aantal seconden dat moet worden gewacht voordat de status van de asynchrone bewerking wordt gecontroleerd.

Azure-AsyncOperation aanvraag en antwoord

Als u een URL van de Azure-AsyncOperation headerwaarde hebt, stuurt u een GET-aanvraag naar die URL. Gebruik de waarde van waaruit Retry-After u wilt plannen hoe vaak de status moet worden gecontroleerd. U krijgt een antwoordobject dat de status van de bewerking aangeeft. Er wordt een ander antwoord geretourneerd bij het controleren van de status van de bewerking met de Location URL. Zie Opslagaccount maken (202 met Locatie en Opnieuw proberen na) voor meer informatie over het antwoord van een locatie-URL.

De antwoordeigenschappen kunnen variƫren, maar bevatten altijd de status van de asynchrone bewerking.

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

In het volgende voorbeeld ziet u andere waarden die kunnen worden geretourneerd uit de bewerking:

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

Het foutobject wordt geretourneerd wanneer de status Mislukt of Geannuleerd is. Alle andere waarden zijn optioneel. Het antwoord dat u ontvangt, kan er anders uitzien dan het voorbeeld.

provisioningState-waarden

Bewerkingen die een resource maken, bijwerken of verwijderen (PUT, PATCH, DELETE) retourneren doorgaans een provisioningState waarde. Wanneer een bewerking is voltooid, wordt een van de volgende drie waarden geretourneerd:

  • Geslaagd
  • Mislukt
  • Geannuleerd

Alle andere waarden geven aan dat de bewerking nog actief is. De resourceprovider kan een aangepaste waarde retourneren die de status aangeeft. U kunt bijvoorbeeld Geaccepteerd ontvangen wanneer de aanvraag wordt ontvangen en wordt uitgevoerd.

Voorbeeldaanvragen en antwoorden

Virtuele machine starten (202 met Azure-AsyncOperation)

In dit voorbeeld ziet u hoe u de status van de startbewerking voor virtuele machines kunt bepalen. De eerste aanvraag heeft de volgende indeling:

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

De statuscode 202 wordt geretourneerd. Onder de headerwaarden ziet u:

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

Als u de status van de asynchrone bewerking wilt controleren, verzendt u een andere aanvraag naar die URL.

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

De hoofdtekst van het antwoord bevat de status van de bewerking:

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

Resources implementeren (201 met Azure-AsyncOperation)

In dit voorbeeld ziet u hoe u de status bepaalt van de implementatiebewerking voor het implementeren van resources in Azure. De eerste aanvraag heeft de volgende indeling:

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

De statuscode 201 wordt geretourneerd. De hoofdtekst van het antwoord bevat:

"provisioningState":"Accepted",

Onder de headerwaarden ziet u:

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

Als u de status van de asynchrone bewerking wilt controleren, verzendt u een andere aanvraag naar die 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

De hoofdtekst van het antwoord bevat de status van de bewerking:

{
    "status": "Running"
}

Wanneer de implementatie is voltooid, bevat het antwoord:

{
    "status": "Succeeded"
}

Opslagaccount maken (202 met Locatie en Opnieuw proberen na)

In dit voorbeeld ziet u hoe u de status van de bewerking voor het maken van opslagaccounts kunt bepalen. De eerste aanvraag heeft de volgende indeling:

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

En de aanvraagbody bevat eigenschappen voor het opslagaccount:

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

De statuscode 202 wordt geretourneerd. Onder de headerwaarden ziet u de volgende twee waarden:

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

Nadat u hebt gewacht op het aantal seconden dat is opgegeven in Opnieuw proberen na, controleert u de status van de asynchrone bewerking door een andere aanvraag naar die URL te verzenden.

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

Als de aanvraag nog steeds wordt uitgevoerd, ontvangt u een statuscode 202. Als de aanvraag is voltooid, ontvangt u een statuscode 200. De hoofdtekst van het antwoord bevat de eigenschappen van het opslagaccount dat is gemaakt.

Volgende stappen