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

Google Cloud Les API utilisent des opérations de longue durée (LRO, Long-Running Operations) 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 conservent 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 pourrez 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 Managed Service for Apache Spark). La variante Async est recommandée.

Flux de haut niveau 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 d'interrogation suivants 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, et 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 qui sont préconfigurées par l'équipe de 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 d'abandonner.

Les bibliothèques clientes Cloud pour Java fournissent une interface permettant d'interagir avec la LRO à l'aide d'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 Builder imbriquée.

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 les valeurs de délai avant expiration RPC et ont des valeurs par défaut (Duration.ZERO pour les délais avant 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 la première interrogation.
MaxRetryDelay	Délai maximal entre chaque interrogation.
RetryDelayMultiplier	Multiplicateur pour le délai de nouvelle tentative d'interrogation entre les interrogations.
TotalTimeoutDuration	Temps maximal autorisé pour l'opération de longue durée.

Quand configurer les valeurs LRO

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

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

Comment configurer les valeurs LRO

Pour configurer les valeurs LRO, créez un objet OperationTimedPollAlgorithm et mettez à jour l'algorithme d'interrogation pour une 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 les valeurs LRO que 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 LRO

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

Une CancellationException ne signifie pas que la tâche de backend Google Cloud a é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 avant expiration, la réponse ne sera pas visible par la bibliothèque cliente.