Operazioni a esecuzione prolungata in Azure SDK per Java

Questo articolo illustra le operazioni a esecuzione prolungata nel Azure SDK per Java e illustra come tenere traccia dello stato di avanzamento e recuperare i risultati finali con una logica di polling meno manuale.

Alcune operazioni su Azure richiedono tempo prolungato per il completamento. Queste operazioni non seguono lo stile HTTP standard del flusso di richiesta e risposta rapida. Ad esempio, la copia di dati da un URL di origine a un BLOB di archiviazione o il training di un modello per riconoscere i moduli sono operazioni che potrebbero richiedere alcuni secondi a diversi minuti. Queste operazioni sono operazioni a esecuzione prolungata, spesso abbreviate come LRO. Il completamento di un LRO può richiedere secondi, minuti, ore, giorni o più, a seconda dell'operazione richiesta e del processo che il server deve eseguire.

Nelle librerie client Java per Azure tutte le operazioni a esecuzione prolungata iniziano con il begin prefisso . Questo prefisso indica che l'operazione è a esecuzione prolungata e che il mezzo di interazione con questa operazione è leggermente diverso dal normale flusso di richiesta e risposta. Insieme al prefisso begin, anche il tipo di ritorno dell'operazione è diverso dal solito, per abilitare tutta la gamma di funzionalità dell'operazione a esecuzione prolungata. Come per la maggior parte degli elementi nella Azure SDK per Java, le operazioni a esecuzione prolungata hanno API sincrone e asincrone:

  • Nei client sincroni, le operazioni a esecuzione prolungata restituiscono un'istanza di SyncPoller.
  • Nei client asincroni, le operazioni a esecuzione prolungata restituiscono un'istanza PollerFlux.

Sia SyncPoller che PollerFlux sono astrazioni lato client che semplificano l'interazione con operazioni lato server a esecuzione prolungata. Nella parte restante di questo articolo vengono descritte le procedure consigliate per l'uso di questi tipi.

Operazioni sincrone di lunga durata

Quando si chiama un'API che restituisce un SyncPoller, l'operazione di lunga durata si avvia immediatamente. L'API restituisce immediatamente SyncPoller, in modo da poter monitorare l'avanzamento dell'operazione di lunga durata e ottenere il risultato finale. Nell'esempio seguente viene illustrato come monitorare lo stato di avanzamento di un'operazione a esecuzione prolungata usando .SyncPoller

SyncPoller<UploadBlobProgress, UploadedBlobProperties> poller = syncClient.beginUploadFromUri(<URI to upload from>);
PollResponse<UploadBlobProgress> response;

do {
    response = poller.poll();
    System.out.println("Status of long running upload operation: " + response.getStatus());
    Duration pollInterval = response.getRetryAfter();
    TimeUnit.MILLISECONDS.sleep(pollInterval.toMillis());
} while (!response.getStatus().isComplete());

In questo esempio viene utilizzato il metodo poll() in SyncPoller per ottenere informazioni sull'avanzamento dell'operazione di lunga durata. Questo codice stampa lo stato nella console, ma un'implementazione migliore prende decisioni pertinenti in base a questo stato.

Il getRetryAfter() metodo restituisce informazioni sulla durata dell'attesa prima del polling successivo. La maggior parte delle operazioni a esecuzione prolungata di Azure restituisce il ritardo del polling come parte della risposta HTTP, ovvero l'intestazione comunemente usata retry-after . Se la risposta non contiene il ritardo del polling, il getRetryAfter() metodo restituisce la durata specificata quando si richiama l'operazione a esecuzione prolungata.

Nell'esempio precedente viene utilizzato un ciclo do..while per eseguire ripetutamente il polling fino al termine dell'operazione di lunga durata. Se non si è interessati a questi risultati intermedi, è invece possibile chiamare waitForCompletion(). Questa chiamata blocca il thread corrente fino al termine dell'operazione di lunga durata e restituisce l'ultima risposta di polling:

PollResponse<UploadBlobProgress> response = poller.waitForCompletion();

Se l'ultima risposta di polling indica che l'operazione di lunga durata si conclude con successo, è possibile ottenere il risultato finale tramite getFinalResult():

if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
    UploadedBlobProperties result = poller.getFinalResult();
}

Altre API utili in SyncPoller includono:

  • waitForCompletion(Duration): attendere il completamento dell'operazione di lunga durata entro il timeout specificato.
  • waitUntil(LongRunningOperationStatus): attendere che si riceva lo stato dell'operazione in corso specificata.
  • waitUntil(LongRunningOperationStatus, Duration): attendere fino alla ricezione dello stato dell'operazione a esecuzione prolungata specificata o fino alla scadenza della durata del timeout specificata.

Operazioni asincrone a lungo termine

L'esempio seguente mostra come PollerFlux consente di osservare un'operazione di lunga durata. Nelle API asincrone, le chiamate di rete vengono eseguite in un thread diverso rispetto al thread principale che chiama subscribe(). Questa architettura significa che il thread principale potrebbe terminare prima che il risultato sia disponibile. È necessario assicurarsi che l'applicazione non venga chiusa prima del completamento dell'operazione asincrona.

L'API asincrona restituisce immediatamente un PollerFlux, ma l'operazione di lunga durata vera e propria non si avvia finché non ci si sottoscrive a PollerFlux. Il modo in cui funzionano tutte le API basate su Flux è attraverso questo processo. L'esempio seguente mostra un'operazione asincrona a esecuzione prolungata:

asyncClient.beginUploadFromUri(...)
    .subscribe(response -> System.out.println("Status of long running upload operation: " + response.getStatus()));

Nell'esempio seguente si ricevono aggiornamenti intermittenti dello stato dell'operazione di lunga durata. È possibile usare questi aggiornamenti per determinare se l'operazione a esecuzione prolungata è ancora operativa nel modo previsto. In questo esempio lo stato viene stampato nella console, ma un'implementazione migliore potrebbe prendere decisioni rilevanti per la gestione degli errori in base a questo stato.

Se non si è interessati agli aggiornamenti dello stato intermedio e si vuole ricevere una notifica del risultato finale quando arriva, usare codice simile all'esempio seguente:

asyncClient.beginUploadFromUri(...)
    .last()
    .flatMap(response -> {
        if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
            return response.getFinalResult();
        }
        return Mono.error(new IllegalStateException("Polling completed unsuccessfully with status: "+ response.getStatus()));
    })
    .subscribe(
        finalResult -> processFormPages(finalResult),
        ex -> countDownLatch.countDown(),
        () -> countDownLatch.countDown());

In questo codice si recupera il risultato finale dell'operazione a esecuzione prolungata chiamando last(). Questa chiamata segnala a PollerFlux che si vuole attendere il completamento di tutte le operazioni di polling. A questo punto, l'operazione a esecuzione prolungata raggiunge uno stato terminale ed è possibile controllarne lo stato per determinare il risultato. Se il poller indica che l'operazione di lunga durata si è completata con successo, è possibile recuperare il risultato finale e passarlo al consumer nella chiamata subscribe.

Passaggi successivi

Ora che si ha familiarità con le API a esecuzione prolungata nel Azure SDK per Java, consultare Configurare i proxy nell'Azure SDK per Java per scoprire come personalizzare ulteriormente il client HTTP.

  • Last updated on