Administra operaciones de larga duración

Cloud de Confiance by S3NS Las APIs usan operaciones de larga duración (LRO) para las llamadas que se espera que tarden un tiempo considerable en completarse (por ejemplo, aprovisionar una instancia de Compute Engine o inicializar un canalización de Dataflow). Estas APIs no mantienen una conexión activa de larga duración ni se bloquean mientras se ejecuta la tarea. Para las APIs de LRO, las bibliotecas cliente de Cloud para Java muestran un future para que lo verifiques más tarde.

Cómo determinar si una API es una LRO

Hay dos formas principales de determinar si una API es una LRO:

• Las APIs de LRO tienen el sufijo Async (por ejemplo, createClusterAsync) o OperationCallable (por ejemplo, createClusterOperationCallable).
• Las APIs de LRO muestran un OperationFuture o OperationCallable.

En el siguiente fragmento, se muestran las dos variaciones con Java-Dataproc como ejemplo:

// Async suffix (#1) returns OperationFuture (#2)
public final OperationFuture<Cluster, ClusterOperationMetadata> createClusterAsync(CreateClusterRequest request)

// OperationCallable suffix (#1) returns OperationCallable (#2)
public final OperationCallable<CreateClusterRequest, Cluster, ClusterOperationMetadata> createClusterOperationCallable()

Estas son dos variaciones para la misma API y no dos APIs diferentes (ambas llamadas crean un clúster de Dataproc). Se recomienda la variante Async.

Flujo de alto nivel de una LRO

Las APIs de LRO son esencialmente una llamada de solicitud inicial seguida de una serie de pequeñas llamadas de sondeo. La llamada inicial envía la solicitud y crea una "operación" en el servidor. Todas las llamadas de sondeo posteriores al servidor hacen un seguimiento del estado de la operación. Si la operación finaliza, se muestra la respuesta. De lo contrario, se muestra un estado incompleto y la biblioteca cliente determina si se debe volver a sondear.

De forma predeterminada, el cliente controla la lógica de sondeo, y no es necesario configurar el mecanismo de sondeo, a menos que tengas requisitos específicos.

Desde tu perspectiva, la llamada se ejecuta en segundo plano hasta que se recibe una respuesta. Las llamadas de sondeo y las configuraciones de tiempo de espera tienen valores predeterminados que el equipo de servicio preconfigura en función del tiempo esperado para sus APIs. Estas configuraciones controlan muchos factores, como la frecuencia con la que se debe sondear y cuánto tiempo se debe esperar antes de abandonar.

Las bibliotecas cliente de Cloud para Java proporcionan una interfaz para interactuar con la LRO mediante OperationFuture.

En el siguiente fragmento, se muestra cómo llamar a una operación y esperar una respuesta con Java-Dataproc como ejemplo:

try (ClusterControllerClient clusterControllerClient = ClusterControllerClient.create()) {
  CreateClusterRequest request =
      CreateClusterRequest.newBuilder().build();
  OperationFuture<Cluster, ClusterOperationMetadata> future =
      clusterControllerClient.createClusterAsync(request);
  // Blocks until there is a response
  Cluster response = future.get();
} catch (CancellationException e) {
  // Exceeded the timeout without the Operation completing.
  // Library is no longer polling for the Operation's status.
}

Valores predeterminados de LRO

Puedes encontrar los valores predeterminados dentro de la clase StubSettings de cada cliente. El método initDefaults() inicializa la configuración de LRO dentro de la clase Builder anidada.

Por ejemplo, en Java-Aiplatform v3.24.0, la llamada de LRO deployModel tiene los siguientes parámetros predeterminados:

OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(5000L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(45000L))
    .setTotalTimeoutDuration(Duration.ofMillis(300000L))
    .setInitialRpcTimeoutDuration(Duration.ZERO) // not used
    .setRpcTimeoutMultiplier(1.0) // not used
    .setMaxRpcTimeoutDuration(Duration.ZERO) // not used
    .build()));

Tanto los reintentos como las LRO comparten la misma clase RetrySettings. En la siguiente tabla, se muestra la asignación entre los campos dentro de RetrySettings y la funcionalidad de LRO:

Cuándo configurar los valores de LRO

El caso de uso principal para configurar manualmente los valores de LRO es modificar las frecuencias de sondeo debido a los tiempos de espera de LRO. Si bien el equipo de servicio configura los valores predeterminados como una estimación, ciertos factores pueden provocar tiempos de espera ocasionales.

Para reducir la cantidad de tiempos de espera, aumenta el valor total del tiempo de espera. Aumentar los otros valores también puede ayudar, y debes probarlos para garantizar el comportamiento esperado.

Cómo configurar los valores de LRO

Para configurar los valores de LRO, crea un objeto OperationTimedPollAlgorithm y actualiza el algoritmo de sondeo para una LRO específica. En el siguiente fragmento, se usa Java-Dataproc como ejemplo:

ClusterControllerSettings.Builder settingsBuilder = ClusterControllerSettings.newBuilder();
// Create a new OperationTimedPollAlgorithm object
TimedRetryAlgorithm timedRetryAlgorithm = OperationTimedPollAlgorithm.create(
  RetrySettings.newBuilder()
    .setInitialRetryDelayDuration(Duration.ofMillis(500L))
    .setRetryDelayMultiplier(1.5)
    .setMaxRetryDelayDuration(Duration.ofMillis(5000L))
    .setTotalTimeoutDuration(Duration.ofHours(24L))
    .build());
// Set the new polling settings for the specific LRO API 
settingsBuilder.createClusterOperationSettings().setPollingAlgorithm(timedRetryAlgorithm);
ClusterControllerClient clusterControllerClient = ClusterControllerClient.create(settingsBuilder.build());

Esta configuración solo modifica los valores de LRO para la RPC createClusterOperation. Las otras RPCs del cliente aún usan los valores de LRO preconfigurados para cada RPC, a menos que también se modifiquen.

Tiempos de espera de LRO

La biblioteca continúa sondeando mientras no se supere el tiempo de espera total. Si se superó el tiempo de espera total, la biblioteca arroja una java.util.concurrent.CancellationException con el mensaje "Se canceló la tarea".

Una CancellationException no significa que se haya cancelado la tarea de backend Cloud de Confiance by S3NS. Esta excepción se arroja desde la biblioteca cliente cuando una llamada superó el tiempo de espera total y no recibió una respuesta. Incluso si la tarea se completa inmediatamente después del tiempo de espera, la biblioteca cliente no verá la respuesta.