Compartilhar via

Operações de longa duração no SDK do Azure para Java

Este artigo fornece uma visão geral do uso de operações de execução longa com o SDK do Azure para Java.

Determinadas operações no Azure podem levar muito tempo para serem concluídas. Essas operações estão fora do estilo HTTP padrão do fluxo de solicitação/resposta rápida. Por exemplo, copiar dados de uma URL de origem para um blob de Armazenamento ou treinar um modelo para reconhecer formulários são operações que podem levar alguns segundos a vários minutos. Essas operações são conhecidas como operações de Long-Running e geralmente são abreviadas como 'LRO'. Um LRO pode levar segundos, minutos, horas, dias ou mais para ser concluído, dependendo da operação solicitada e do processo que deve ser executado no lado do servidor.

Nas bibliotecas de cliente Java para o Azure, existe uma convenção de que todas as operações de longa duração começam com o prefixo begin. Esse prefixo indica que essa operação é de execução prolongada e que os meios de interação com essa operação são ligeiramente diferentes do fluxo de solicitação/resposta usual. Junto com o prefixo begin, o tipo retornado da operação também é diferente do usual para habilitar toda a gama de funcionalidades da operação de execução longa. Assim como acontece com a maioria das coisas no SDK do Azure para Java, há APIs síncronas e assíncronas para operações de longa execução:

  • Em clientes síncronos, as operações de execução longa retornarão uma instância de SyncPoller.
  • Em clientes assíncronos, as operações de execução longa retornarão uma instância de PollerFlux.

Ambas SyncPoller e PollerFlux são as abstrações do lado do cliente destinadas a simplificar a interação com operações do servidor que são de execução prolongada. O restante deste artigo descreve as práticas recomendadas ao trabalhar com esses tipos.

Operações sincronas de longa duração

Chamar qualquer API que retorna um SyncPoller iniciará imediatamente a operação de execução longa. A API retornará imediatamente SyncPoller , permitindo que você monitore o progresso da operação de longa execução e recupere o resultado final. O exemplo a seguir mostra como monitorar o progresso de uma operação de execução longa usando o 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());

Este exemplo usa o método poll() no SyncPoller para recuperar informações sobre o progresso da operação de execução longa. Esse código imprime o status no console, mas uma implementação melhor tomaria decisões relevantes com base nesse status.

O getRetryAfter() método retorna informações sobre quanto tempo esperar antes da próxima votação. As operações de longa duração do Azure geralmente retornam o tempo de espera para a consulta como parte de sua resposta HTTP, ou seja, no cabeçalho comumente usado retry-after. Se a resposta não contiver o atraso de sondagem, o método getRetryAfter() retornará a duração fornecida no momento da invocação da operação de execução longa.

O exemplo acima usa um do..while loop para sondar repetidamente até que a operação de longa execução seja concluída. Se você não estiver interessado nesses resultados intermediários, poderá chamar waitForCompletion(). Essa chamada bloqueará o thread atual até que a operação de execução longa seja concluída e retorne a última resposta de sondagem:

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

Se a última resposta da pesquisa indicar que a operação de longa duração foi concluída com êxito, você poderá obter o resultado final usando getFinalResult().

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

Outras APIs úteis incluem SyncPoller :

  1. waitForCompletion(Duration): aguardar a conclusão da operação de execução longa pela duração do tempo limite especificada.
  2. waitUntil(LongRunningOperationStatus): aguardar até que o status da operação de execução longa seja recebido.
  3. waitUntil(LongRunningOperationStatus, Duration): aguardar até que o status da operação de execução longa seja recebido ou a duração do tempo limite determinada expire.

Operações de execução longa assíncronas

O exemplo a seguir mostra como o PollerFlux permite observar uma operação de execução longa. Em APIs assíncronas, as chamadas de rede ocorrem em um thread diferente do thread principal que chama subscribe(). O que isso significa é que o thread principal pode ser encerrado antes que o resultado esteja disponível. Cabe a você garantir que o aplicativo não saia antes que a operação assíncrona tenha tido tempo de ser concluída.

A API assíncrona retorna um PollerFlux imediatamente, mas a operação de execução longa em si não será iniciada até que você assine o PollerFlux. Esse processo é como todas as APIs baseadas em Flux operam. O exemplo a seguir mostra uma operação assíncrona de longa duração:

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

No exemplo a seguir, você obterá atualizações de status intermitentes na operação de execução longa. Você pode usar essas atualizações para determinar se a operação de longa duração ainda está operando da maneira esperada. Este exemplo imprime o status no console, mas uma implementação melhor tomaria decisões relevantes de tratamento de erros com base nesse status.

Se você não estiver interessado nas atualizações de status intermediário e quiser apenas ser notificado sobre o resultado final quando ele chegar, poderá usar um código semelhante ao exemplo a seguir:

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());

Neste código, você recupera o resultado final da operação de execução longa chamando last(). Essa chamada informa o PollerFlux que você deseja aguardar até que toda a sondagem seja concluída; nesse ponto, a operação de execução longa atingiu um estado de terminal e você pode inspecionar seu status para determinar o resultado. Se o verificador indicar que a operação de execução longa foi concluída com êxito, você poderá recuperar o resultado final e passá-lo para o consumidor na chamada de assinatura.

Próximas etapas

Agora que você está familiarizado com as APIs de longa execução no SDK do Azure para Java, consulte Configurar proxies no SDK do Azure para Java para saber como personalizar ainda mais o cliente HTTP.