Tenere traccia delle operazioni asincrone

  • Articolo

Alcune operazioni REST in Azure vengono eseguite in modo asincrono perché non è possibile completarle rapidamente. Questo articolo descrive come tenere traccia dello stato delle operazioni asincrone tramite i valori restituiti nella risposta.

Codici di stato per le operazioni asincrone

Inizialmente, un'operazione asincrona restituisce un codice di stato HTTP del tipo:

  • 201 (Creato) oppure
  • 202 (Accettato)

Tuttavia, il codice di stato non significa necessariamente che l'operazione sia asincrona. Un'operazione asincrona restituisce anche un valore per provisioningState che indica che l'operazione non è stata completata. Il valore può variare in base all'operazione, ma non include Succeeded, Failed o Canceled. Questi tre valori indicano che l'operazione è stata completata. Se non viene restituito alcun valore per provisioningState, l'operazione è stata completata ed è riuscita.

Quando l'operazione viene completata correttamente, viene restituito uno dei codici seguenti:

  • 200 (OK)
  • 204 (No Content (Nessun contenuto))

Consultare la documentazione dell'API REST per visualizzare le risposte dell'operazione in esecuzione.

Dopo aver ottenuto il codice di risposta 201 o 202, è possibile monitorare lo stato dell'operazione.

URL per monitorare lo stato

Esistono due modi diversi per monitorare lo stato dell'operazione asincrona. Per determinare l'approccio corretto, esaminare i valori di intestazione restituiti dalla richiesta originale. Prima di tutto, cercare:

  • Azure-AsyncOperation -URL per verificare lo stato attuale dell'operazione. Se l'operazione restituisce questo valore, usarlo per tenere traccia dello stato dell'operazione.
  • Retry-After -Il numero di secondi di attesa prima di controllare lo stato dell'operazione asincrona.

Se Azure-AsyncOperation non è uno dei valori di intestazione, cercare:

  • Location - URL per determinare quando un'operazione è stata completata. Usare questo valore solo quando non viene restituito Azure-AsyncOperation.
  • Retry-After -Il numero di secondi di attesa prima di controllare lo stato dell'operazione asincrona.

Quando l'intestazione Retry-after non viene restituita, implementare la logica di ripetizione dei tentativi.

Nota

Il client REST deve accettare una dimensione minima dell'URL di 4 kB per Azure-AsyncOperation e Location.

Autorizzazione per il monitoraggio dello stato asincrono

Per monitorare lo stato di un'operazione asincrona, è necessaria un'autorizzazione sufficiente a livello del gruppo di risorse. Se si dispone solo dell'autorizzazione a livello della risorsa, è possibile avviare l'operazione, ma non è possibile monitorarne lo stato. L'autorizzazione a livello del gruppo di risorse è necessaria perché l'URL per il monitoraggio dello stato non ha come ambito la risorsa.

Ad esempio, per avviare una macchina virtuale, è necessario il ruolo Collaboratore macchina virtuale per il gruppo di risorse che la contiene. L'URL per tenere traccia di una richiesta di avvio non include la macchina virtuale nel percorso.

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

Richiesta e risposta di Azure AsyncOperation

Se è disponibile un URL dal valore dell'intestazione Azure-AsyncOperation, inviare una richiesta GET a tale URL. Usare il valore di Retry-After per pianificare la frequenza con cui controllare lo stato. Si ottiene un oggetto risposta che indica lo stato dell'operazione. Quando si controlla lo stato dell'operazione con l'URL Location, viene restituita una risposta diversa. Per altre informazioni sulla risposta di un URL della posizione, vedere Creazione di un account di archiviazione (202 con Location e Retry-After).

Le proprietà della risposta possono variare, ma includono sempre lo stato dell'operazione asincrona.

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

L'esempio seguente mostra altri valori che possono essere restituiti dall'operazione:

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

L'oggetto errore viene restituito quando lo stato è Operazione non riuscita oppure Operazione annullata. Tutti gli altri valori sono facoltativi. La risposta ricevuta potrebbe essere diversa dall'esempio.

Valori provisioningState

Le operazioni di creazione, aggiornamento o eliminazione (INSERISCI, PATCH, ELIMINA) di una risorsa restituiscono in genere un valore provisioningState. Quando un'operazione viene completata, viene restituito uno dei tre valori seguenti:

  • Riuscito
  • Non inviato
  • Operazione annullata

Tutti gli altri valori indicano che l'operazione è ancora in esecuzione. Il provider di risorse può restituire un valore personalizzato che indica lo stato. Ad esempio, potrebbe essere visualizzato Accepted quando la richiesta è stata ricevuta ed è in esecuzione.

Esempi di richieste e risposte

Avviare la macchina virtuale (202 con Azure-AsyncOperation)

In questo esempio viene illustrato come determinare lo stato dell'operazione di avvio per le macchine virtuali. La richiesta iniziale è nel formato seguente:

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

Restituisce il codice di stato 202. Tra i valori di intestazione compare:

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

Per controllare lo stato dell'operazione asincrona, inviare un'altra richiesta all'URL.

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

Il corpo della risposta contiene lo stato dell'operazione:

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

Distribuzione delle risorse (201 con Azure-AsyncOperation)

In questo esempio viene illustrato come determinare lo stato dell'operazione di distribuzione per la distribuzione delle risorse in Azure. La richiesta iniziale è nel formato seguente:

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

Restituisce il codice di stato 201. Il corpo della risposta include:

"provisioningState":"Accepted",

Tra i valori di intestazione compare:

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

Per controllare lo stato dell'operazione asincrona, inviare un'altra richiesta all'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

Il corpo della risposta contiene lo stato dell'operazione:

{
    "status": "Running"
}

Al termine della distribuzione, la risposta contiene:

{
    "status": "Succeeded"
}

Creazione di un account di archiviazione (202 con Location e Retry-After)

In questo esempio viene illustrato come determinare lo stato dell'operazione di creazione per gli account di archiviazione. La richiesta iniziale è nel formato seguente:

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

Il corpo della richiesta contiene le proprietà dell'account di archiviazione:

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

Restituisce il codice di stato 202. Tra i valori di intestazione, vengono visualizzati i due valori seguenti:

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

Dopo aver atteso il numero di secondi specificato in Retry-After, verificare lo stato dell'operazione asincrona inviando un'altra richiesta all'URL.

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

Se la richiesta è ancora in esecuzione, viene visualizzato il codice di stato 202. Se la richiesta è stata completata, si riceve un codice di stato 200. Il corpo della risposta contiene le proprietà dell'account di archiviazione creato.

Passaggi successivi