Gérer les opérations de longue durée

Les APIGoogle Cloud utilisent des opérations de longue durée pour les appels qui devraient prendre beaucoup de temps (par exemple, le provisionnement d'une instance Compute Engine ou l'initialisation d'un pipeline Dataflow). Ces API ne maintiennent pas de connexion active de longue durée ni ne bloquent l'exécution de la tâche. Pour les API LRO, les bibliothèques clientes Cloud pour Java renvoient un future que vous pouvez vérifier ultérieurement.

Déterminer si une API est une LRO

Il existe deux façons principales de déterminer si une API est une LRO :

• Les API LRO ont le suffixe Async (par exemple, createClusterAsync) ou OperationCallable (par exemple, createClusterOperationCallable).
• Les API LRO renvoient un OperationFuture ou un OperationCallable.

L'extrait suivant montre les deux variantes, en utilisant Java-Dataproc comme exemple :

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

Il s'agit de deux variantes de la même API, et non de deux API différentes (les deux appels créent un cluster Dataproc). La variante Async est recommandée.

Flux général d'une LRO

Les API LRO sont essentiellement un appel de requête initial suivi d'une série de petits appels d'interrogation. L'appel initial envoie la requête et crée une "opération" sur le serveur. Tous les appels de vérification ultérieurs au serveur suivent l'état de l'opération. Si l'opération est terminée, la réponse est renvoyée. Sinon, un état incomplet est renvoyé et la bibliothèque cliente détermine s'il faut interroger à nouveau.

Par défaut, le client gère la logique d'interrogation. Vous n'avez pas besoin de configurer le mécanisme d'interrogation, sauf si vous avez des exigences spécifiques.

De votre point de vue, l'appel s'exécute en arrière-plan jusqu'à ce qu'une réponse soit reçue. Les appels d'interrogation et les configurations de délai avant expiration ont des valeurs par défaut préconfigurées par l'équipe du service en fonction du temps prévu pour leurs API. Ces configurations contrôlent de nombreux facteurs, tels que la fréquence d'interrogation et le délai d'attente avant abandon.

Les bibliothèques clientes Cloud pour Java fournissent une interface permettant d'interagir avec l'OLRO à l'aide de OperationFuture.

L'extrait suivant montre comment appeler une opération et attendre une réponse, en utilisant Java-Dataproc comme exemple :

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.
}

Valeurs LRO par défaut

Vous trouverez les valeurs par défaut dans la classe StubSettings de chaque client. La méthode initDefaults() initialise les paramètres LRO dans la classe imbriquée Builder.

Par exemple, dans Java-Aiplatform v3.24.0, l'appel LRO deployModel comporte les paramètres par défaut suivants :

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

Remarque : Les LRO n'utilisent pas de valeurs de délai d'expiration RPC et ont des valeurs par défaut (Duration.ZERO pour les délais d'expiration ou 1.0 pour le multiplicateur).

Les nouvelles tentatives et les LRO partagent la même classe RetrySettings. Le tableau suivant montre le mappage entre les champs de RetrySettings et la fonctionnalité LRO :

RetrySettings	Description
InitialRetryDelay	Délai initial avant le premier sondage.
MaxRetryDelay	Délai maximal entre chaque interrogation.
RetryDelayMultiplier	Multiplicateur pour le délai entre les tentatives d'interrogation.
TotalTimeoutDuration	Temps maximal autorisé pour l'opération de longue durée.

Quand configurer les valeurs LRO

Le principal cas d'utilisation de la configuration manuelle des valeurs LRO consiste à modifier les fréquences d'interrogation en raison des délais d'attente LRO. Bien que les valeurs par défaut soient configurées comme une estimation par l'équipe du service, certains facteurs peuvent entraîner des délais d'attente occasionnels.

Pour réduire le nombre de délais avant expiration, augmentez la valeur du délai avant expiration total. Augmenter les autres valeurs peut également être utile. Vous devez les tester pour vous assurer du comportement attendu.

Configurer les valeurs LRO

Pour configurer les valeurs LRO, créez un objet OperationTimedPollAlgorithm et mettez à jour l'algorithme d'interrogation pour un LRO spécifique. L'extrait suivant utilise Java-Dataproc comme exemple :

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

Cette configuration ne modifie que les valeurs LRO pour le RPC createClusterOperation. Les autres RPC du client utilisent toujours les valeurs LRO préconfigurées pour chaque RPC, sauf si elles sont également modifiées.

Délais avant expiration des LRO

La bibliothèque continue d'interroger tant que le délai d'attente total n'a pas été dépassé. Si le délai avant expiration total est dépassé, la bibliothèque génère une exception java.util.concurrent.CancellationException avec le message "Task was cancelled" (La tâche a été annulée).

Un CancellationException ne signifie pas que la tâche de backend Google Clouda été annulée. Cette exception est générée par la bibliothèque cliente lorsqu'un appel a dépassé le délai avant expiration total et n'a pas reçu de réponse. Même si la tâche est terminée immédiatement après le délai d'expiration, la bibliothèque cliente ne verra pas la réponse.