Operaciones de larga duración en el SDK de Azure para Java

En este artículo se proporciona información general sobre el uso de operaciones de ejecución prolongada con el SDK de Azure para Java.

Algunas operaciones en Azure pueden tardar mucho tiempo en completarse. Estas operaciones están fuera del estilo HTTP estándar de flujo de solicitud o respuesta rápida. Por ejemplo, copiar datos de una dirección URL de origen a un blob de Storage o entrenar un modelo para reconocer formularios, son operaciones que pueden tardar unos segundos en varios minutos. Estas operaciones se conocen como operaciones de Long-Running y a menudo se abrevian como "LRO". Un LRO puede tardar segundos, minutos, horas, días o más en completarse, en función de la operación solicitada y el proceso que se debe realizar en el servidor.

En las bibliotecas cliente de Java para Azure, existe una convención que indica que todas las operaciones de ejecución prolongada comienzan con el begin prefijo . Este prefijo indica que esta operación es de larga duración y que el medio de interacción con esta operación es ligeramente diferente que el flujo de solicitud o respuesta habitual. Junto con el prefijo begin, el tipo de valor devuelto por la operación también es diferente de lo habitual para habilitar todas las funcionalidades de una operación de larga duración. Al igual que sucede con la mayoría de las cosas del SDK de Azure para Java, hay API sincrónicas y asincrónicas para operaciones de larga duración:

• En los clientes sincrónicos, las operaciones de larga duración devolverán una instancia de SyncPoller.
• En los clientes asincrónicos, las operaciones de ejecución prolongada devolverán una instancia PollerFlux.

Tanto SyncPoller como PollerFlux son las abstracciones del lado cliente diseñadas para simplificar la interacción con las operaciones del lado servidor de larga duración. En el resto de este artículo se describen los procedimientos recomendados al trabajar con estos tipos.

Operaciones sincrónicas de larga duración

Llamar a cualquier API que devuelva un SyncPoller iniciará inmediatamente la operación de ejecución prolongada. La API devolverá inmediatamente SyncPoller , lo que le permitirá supervisar el progreso de la operación de ejecución prolongada y recuperar el resultado final. En el ejemplo siguiente se muestra cómo supervisar el progreso de una operación de ejecución prolongada mediante .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());

En este ejemplo se usa el método poll() en SyncPoller para recuperar información sobre el progreso de la operación prolongada. Este código imprime el estado en la consola, pero una mejor implementación tomaría decisiones pertinentes en función de este estado.

El getRetryAfter() método devuelve información sobre cuánto tiempo se debe esperar antes del próximo sondeo. La mayoría de las operaciones de ejecución prolongada de Azure devuelven la demora de sondeo como parte de su respuesta HTTP (es decir, el encabezado retry-after utilizado habitualmente). Si la respuesta no contiene el retraso del sondeo, el getRetryAfter() método devuelve la duración especificada en el momento de invocar la operación de larga duración.

El ejemplo anterior utiliza un bucle do..while para sondear repetidamente hasta que se complete la operación prolongada. Si no está interesado en estos resultados intermedios, puede llamar a waitForCompletion(). Esta llamada bloqueará el subproceso actual hasta que se complete la operación de larga duración y devuelva la última respuesta de sondeo:

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

Si la última respuesta de sondeo indica que la operación de ejecución prolongada se ha completado correctamente, puede recuperar el resultado final mediante getFinalResult():

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

Otras API útiles de SyncPoller incluyen:

1. waitForCompletion(Duration): esperar a que se complete la operación de larga duración para la duración de tiempo de espera especificada.
2. waitUntil(LongRunningOperationStatus): esperar hasta que se reciba el estado de la operación de larga duración especificada.
3. waitUntil(LongRunningOperationStatus, Duration): espere hasta que se reciba el estado de la operación de larga duración especificado o hasta que expire la duración de tiempo de espera especificada.

Operaciones asincrónicas de larga duración

En el ejemplo siguiente se muestra cómo el elemento PollerFlux le permite observar una operación de larga duración. En las API asincrónicas, las llamadas de red se producen en un subproceso diferente del subproceso principal que llama a subscribe(). Esto significa que el subproceso principal puede finalizar antes de que el resultado esté disponible. Es necesario asegurarse de que la aplicación no se cierre antes de que la operación asincrónica haya tenido tiempo de completarse.

La API asincrónica devuelve un elemento PollerFlux inmediatamente, pero la propia operación de larga duración no se iniciará hasta que se suscriba al elemento PollerFlux. Este proceso es el modo en que funcionan todas las API basadas en Flux. En el ejemplo siguiente se muestra una operación asincrónica de larga duración:

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

En el ejemplo siguiente, obtendrá actualizaciones de estado intermitentes en la operación de larga duración. Puede usar estas actualizaciones para determinar si la operación de ejecución prolongada sigue funcionando de la manera esperada. En este ejemplo se imprime el estado en la consola, pero una mejor implementación tomaría decisiones relevantes sobre el control de errores en función de este estado.

Si no está interesado en las actualizaciones de estado intermedios y solo desea recibir una notificación del resultado final cuando llegue, puede usar código similar al ejemplo siguiente:

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

En este código, se recupera el resultado final de la operación de ejecución prolongada llamando a last(). Esta llamada indica al elemento PollerFlux que desea esperar a que se complete todo el sondeo, momento en el que la operación de larga duración ha alcanzado el estado de finalización y puede inspeccionar su estado para determinar el resultado. Si el sondeador indica que la operación de larga duración se completó correctamente, puede recuperar el resultado final y pasárselo al consumidor en la llamada a subscribe.

Pasos siguientes

Ahora que está familiarizado con las API de ejecución prolongada en El SDK de Azure para Java, consulte Configuración de servidores proxy en El SDK de Azure para Java para obtener información sobre cómo personalizar aún más el cliente HTTP.