Opérations de longue durée dans le SDK Azure pour Java
Cet article fournit une vue d’ensemble de l’utilisation des opérations de longue durée avec le SDK Azure pour Java.
L’exécution de certaines opérations sur Azure peut prendre un certain temps. Ces opérations sont en dehors du style HTTP standard du workflow de demande/réponse rapide. Par exemple, la copie de données d’une URL source vers un objet de stockage blob ou l’apprentissage d’un modèle pour reconnaître des formulaires sont des opérations qui peuvent prendre quelques secondes à plusieurs minutes. Ces opérations sont appelées opérations de longue durée et sont souvent abrégées en « LRO ». Une opération de longue durée peut durer quelques secondes, quelques minutes, quelques heures, quelques jours ou plus encore, en fonction de l’opération demandée et du processus qui doit être effectué côté serveur.
Dans les bibliothèques clientes Java pour Azure, il existe une convention selon laquelle toutes les opérations de longue durée commencent par le préfixe begin. Ce préfixe indique que cette opération est de longue durée et que le moyen d’interaction avec cette opération est légèrement différent de celui du processus de demande/réponse habituel. Avec le préfixe begin, le type de retour de l’opération est également différent par rapport à d’habitude, pour activer l’ensemble de la plage des fonctionnalités des opérations de longue durée. Comme avec la plupart des éléments du 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 instance
SyncPoller. - Dans les clients asynchrones, les opérations de longue durée retournent une instance
PollerFlux.
SyncPoller et PollerFlux sont des abstractions côté client destinées à simplifier l’interaction avec les opérations de longue durée côté serveur. Le reste de cet article décrit les meilleures pratiques en cas d’utilisation de ces types.
Opérations de longue durée synchrones
L’appel d’une API qui retourne SyncPoller démarre immédiatement l’opération de longue durée. Cette API retourne immédiatement SyncPoller, 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 de 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 SyncPoller pour récupérer les 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 pourrait prendre des décisions en fonction de cet état.
La méthode getRetryAfter() retourne des informations sur la durée d’attente avant la prochaine interrogation. 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 appeler waitForCompletion(). Cet appel bloquera le thread actuel jusqu’à ce que l’opération de longue durée se termine et retourne la dernière réponse :
PollResponse<UploadBlobProgress> response = poller.waitForCompletion();
Si la dernière réponse indique que l’opération de longue durée s’est correctement terminée, vous pouvez récupérer le résultat final à l’aide de getFinalResult() :
if (LongRunningOperationStatus.SUCCESSFULLY_COMPLETED == response.getStatus()) {
UploadedBlobProperties result = poller.getFinalResult();
}
Voici d’autres API utiles dans SyncPoller :
waitForCompletion(Duration): attend la fin de l’opération de longue durée, conformément au délai d’attente donné.waitUntil(LongRunningOperationStatus): attend la réception de l’état de l’opération de longue durée.waitUntil(LongRunningOperationStatus, Duration): attend la réception de l’état de l’opération de longue durée ou l’expiration de la durée du délai d’attente donné.
Opérations de longue durée asynchrones
L’exemple ci-dessous montre comment PollerFlux vous permet d’observer une opération de longue durée. Dans les API asynchrones, les appels réseau se produisent dans un autre thread que le 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 se termine pas avant que l’opération asynchrone ait eu le temps de se terminer.
L’API asynchrone retourne immédiatement PollerFlux, mais l’opération de longue durée ne démarre pas tant que vous n’êtes pas abonné à PollerFlux. Ce processus est le fonctionnement de toutes les API basées sur Flux. L’exemple suivant illustre 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 recevrez des informations d’état de façon intermittente lors de l’opération de longue durée. Vous pouvez utiliser ces informations pour déterminer si l’opération de longue durée continue à fonctionner de la façon attendue. Cet exemple imprime l’état dans la console, mais une meilleure implémentation pourrait prendre des décisions sur la gestion des erreurs en fonction de cet état.
Si vous n’êtes pas intéressé par informations d’état intermédiaires et que vous souhaitez simplement être informé du résultat final lorsqu’il arrive, vous pouvez un code similaire à celui de 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 de longue durée du SDK Azure pour Java, consultez Configurer des proxys dans le SDK Azure pour Java pour savoir comment personnaliser le client HTTP que vous utilisez.