Opérations de longue durée dans le Kit de développement logiciel (SDK) Azure pour Java

Cet article fournit une vue d’ensemble de l’utilisation d’opérations longues avec le Kit de développement logiciel (SDK) Azure pour Java.

Certaines opérations sur Azure peuvent prendre beaucoup de temps. Ces opérations sont en dehors du style HTTP standard du flux de requête/réponse rapide. Par exemple, la copie de données d’une URL source vers un objet blob de stockage ou l’apprentissage d’un modèle pour reconnaître les formulaires, sont des opérations qui peuvent prendre quelques secondes à plusieurs minutes. Ces opérations sont appelées opérations Long-Running et sont souvent abrégées sous le nom de « LRO ». Un LRO peut prendre des secondes, des minutes, des heures, des jours ou plus longtemps, selon l’opération demandée et le processus qui doit être effectué côté serveur.

Dans les bibliothèques clientes Java pour Azure, une convention existe que toutes les opérations de longue durée commencent par le begin préfixe. Ce préfixe indique que cette opération est longue et que le moyen d’interaction avec cette opération est légèrement différent du flux de requête/réponse habituel. En plus du préfixe begin, le type de retour de l’opération est également différent de la normale, permettant d'exploiter pleinement les fonctionnalités des opérations de longue durée. Comme pour la plupart des éléments du Kit de développement logiciel (SDK) Azure pour Java, il existe des API synchrones et asynchrones pour les opérations de longue durée :

• Dans les clients synchrones, les opérations de longue durée retournent une SyncPoller instance.
• Dans les clients asynchrones, les opérations de longue durée retournent une instance PollerFlux.

SyncPoller et PollerFlux sont les abstractions côté client destinées à simplifier l’interaction avec les opérations côté serveur de longue durée. Le reste de cet article décrit les meilleures pratiques lors de l’utilisation de ces types.

Opérations de longue durée synchrones

L'appel à une API qui retourne une SyncPoller déclenche immédiatement une opération de longue durée. L’API retourne SyncPoller immédiatement, ce qui vous permet de surveiller la progression de l’opération de longue durée et de récupérer le résultat final. L’exemple suivant montre comment surveiller la progression d’une opération de longue durée à l’aide du 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());

Cet exemple utilise la méthode poll() sur le SyncPoller pour récupérer des informations sur la progression de l'opération de longue durée. Ce code imprime l’état dans la console, mais une meilleure implémentation prend des décisions pertinentes en fonction de cet état.

La getRetryAfter() méthode retourne des informations sur la durée d’attente avant le prochain sondage. La plupart des opérations Azure de longue durée renvoient le délai d’interrogation dans le cadre de leur réponse HTTP (autrement dit, l’en-tête retry-after couramment utilisé). Si la réponse ne contient pas de délai d’interrogation, la méthode getRetryAfter() retourne la durée donnée au moment de l’appel de l’opération de longue durée.

L’exemple ci-dessus utilise une boucle do..while pour réitérer l’interrogation jusqu’à ce que l’opération de longue durée soit terminée. Si vous n’êtes pas intéressé par ces résultats intermédiaires, vous pouvez plutôt appeler waitForCompletion(). Cet appel bloque le thread actuel jusqu’à ce que l’opération de longue durée se termine et retourne la dernière réponse de sondage :

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

Si la dernière réponse de sondage indique que l’opération de longue durée s’est terminée avec succès, vous pouvez récupérer le résultat final à l’aide getFinalResult()de :

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

Voici d’autres API SyncPoller utiles :

1. waitForCompletion(Duration): Attendez que l’opération de longue durée se termine, pendant la durée du délai d’expiration spécifié.
2. waitUntil(LongRunningOperationStatus): Attendez jusqu’à ce que le statut de l’opération longue durée soit reçu.
3. waitUntil(LongRunningOperationStatus, Duration): Attendez que le statut de l’opération longue durée soit reçu ou que le délai d’expiration spécifié expire.

Opérations de longue durée asynchrones

L'exemple ci-dessous montre comment le PollerFlux vous permet d'observer une opération de longue durée. Dans les API asynchrones, les appels réseau se produisent dans un thread différent du thread principal qui appelle subscribe(). Cela signifie que le thread principal peut se terminer avant que le résultat soit disponible. C’est à vous de vous assurer que l’application ne s’arrête pas avant que l’opération asynchrone n’ait eu le temps de se terminer.

L'API asynchrone retourne immédiatement un PollerFlux, mais l'opération de longue durée elle-même ne démarrera pas tant que vous ne vous serez pas abonné à PollerFlux. Ce processus est la façon dont fonctionnent toutes les API basées sur Flux. L’exemple suivant montre une opération asynchrone de longue durée :

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

Dans l’exemple suivant, vous obtiendrez des mises à jour d’état intermittentes sur l’opération qui dure longtemps. Vous pouvez utiliser ces mises à jour pour déterminer si l’opération de longue durée fonctionne toujours de la manière attendue. Cet exemple montre comment imprimer l’état dans la console, mais une meilleure implémentation permettrait de prendre des décisions pertinentes en matière de gestion des erreurs en fonction de cet état.

Si vous n’êtes pas intéressé par les mises à jour d’état intermédiaires et que vous souhaitez simplement recevoir une notification du résultat final lorsqu’il arrive, vous pouvez utiliser du code similaire à l’exemple suivant :

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

Dans ce code, vous récupérez le résultat final de l’opération de longue durée en appelant last(). Cet appel indique à PollerFlux que vous souhaitez attendre la fin de l’interrogation, auquel cas l’opération de longue durée est arrivée à son terme, et vous pouvez inspecter son état pour déterminer le résultat. Si l’opération de longue durée s’est correctement terminée, vous pouvez récupérer le résultat final et le transmettre au consommateur dans l’appel d’abonnement.

Étapes suivantes

Maintenant que vous êtes familiarisé avec les API fonctionnant sur une longue période dans le SDK Azure pour Java, consultez Configurer des proxys dans le SDK Azure pour Java pour apprendre comment personnaliser davantage le client HTTP.