Asynchrone Azure-bewerkingen bijhouden

  • Artikel

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 bijhoudt 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 de volgende opties:

  • 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 bekijken voor de bewerking die u uitvoert.

Nadat u de responscode 201 of 202 hebt ontvangen, kunt u de status van de bewerking 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 op basis van uw oorspronkelijke aanvraag. Zoek eerst naar:

  • Azure-AsyncOperation - URL voor het controleren van de doorlopende status van de bewerking. Als uw 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 naar:

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

Wanneer de Retry-after header niet wordt geretourneerd, implementeert u uw eigen logica voor opnieuw proberen.

Notitie

Uw REST-client moet een minimale URL-grootte van 4 kB accepteren voor Azure-AsyncOperation en Location.

Machtiging voor het bijhouden van asynchrone status

Als u de status van een asynchrone bewerking wilt bijhouden, hebt u voldoende machtigingen nodig op het niveau van de resourcegroep. Als u alleen gemachtigd bent op het niveau van de resource, kunt u de bewerking starten, maar kunt u de status ervan niet bijhouden. Machtiging op het niveau van de resourcegroep is vereist omdat de URL voor het bijhouden van de status niet is afgestemd op de resource.

Als u bijvoorbeeld een virtuele machine wilt starten, hebt u de rol Inzender voor virtuele machines nodig voor de resourcegroep die de virtuele machine bevat. De URL voor het bijhouden van een startaanvraag bevat niet de virtuele machine in het pad.

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

Azure-AsyncOperation-aanvraag en -antwoord

Als u een URL van de Azure-AsyncOperation headerwaarde hebt, verzendt 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 door 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, ziet er mogelijk anders uit 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 steeds wordt uitgevoerd. De resourceprovider kan een aangepaste waarde retourneren die de status aangeeft. U ontvangt bijvoorbeeld Geaccepteerd 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 van de implementatiebewerking voor het implementeren van resources in Azure kunt bepalen. 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 maakbewerking voor 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

De hoofdtekst van de aanvraag 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