Pagination et itération dans le SDK Azure pour Java

  • Article

Cet article fournit une vue d’ensemble de l’utilisation du SDK Azure pour les fonctionnalités de pagination et d’itération Java pour travailler de façon efficace et productive avec des jeux de données volumineux.

De nombreuses opérations fournies par les bibliothèques clientes dans le SDK Azure Java renvoient plusieurs résultats. Le SDK Azure Java définit un ensemble de types de retour acceptables dans ces cas pour garantir l’optimisation de l’expérience des développeurs grâce à plus de cohérence. Les types de retours utilisés sont PagedIterable pour les API synchrones et PagedFlux pour les API non synchrones. Ces API sont légèrement différentes en fonction de leurs différents cas d’utilisation, mais au niveau conceptuel, elles ont les mêmes exigences :

  • Elles permettent d’effectuer facilement une itération sur chaque élément de la collection en ignorant tout besoin de pagination manuelle ou de suivi des jetons de continuation. Aussi bien PagedIterable que PagedFlux simplifient cette tâche en effectuant une itération sur une réponse paginée désérialisée dans un type T donné. PagedIterable implémente l’interface Iterable et offre une API pour recevoir un Stream, tandis que PagedFlux fournit un Flux. Dans tous les cas, l’action de pagination est transparente et l’itération continue tant qu’il existe encore des résultats d’itération.

  • Permet d’effectuer une itération explicite page par page. Cela vous permet de mieux comprendre le moment où les demandes sont effectuées et d’accéder aux informations de réponse par page. PagedIterable et PagedFlux proposent des méthodes qui retournent des types appropriés à itérer par page, plutôt que par élément individuel.

Cet article est divisé entre les API synchrones et asynchrones du SDK Azure pour Java. Vous verrez les API d’itération synchrones lorsque vous travaillez avec des clients synchrones et des API d’itération asynchrones lorsque vous travaillez avec des clients asynchrones.

Pagination et itération synchrones

Cette section traite des API synchrones.

Itération sur des éléments individuels

Comme indiqué, le cas d’usage le plus courant consiste à effectuer une itération sur chaque élément individuellement, plutôt que par page. Les exemples de code suivants montrent comment l’API PagedIterable vous permet d’utiliser le style d’itération que vous préférez pour implémenter cette fonctionnalité.

Utilisation pour une boucle For each

Étant donné que PagedIterable implémente Iterable, vous pouvez effectuer une itération au sein des éléments comme indiqué dans l’exemple suivant :

PagedIterable<Secret> secrets = client.listSecrets();
for (Secret secret : secrets) {
   System.out.println("Secret is: " + secret);
}

Utilisation de Stream

Étant donné que PagedIterable a une méthode stream() définie, vous pouvez l’appeler pour utiliser les API de flux Java standard, comme indiqué dans l’exemple suivant :

client.listSecrets()
      .stream()
      .forEach(secret -> System.out.println("Secret is: " + secret));

Utilisation de l’itérateur

Étant donné que PagedIterable implémente Iterable, il dispose également d’une méthode iterator() pour autoriser le style de programmation avec itérateur Java, comme illustré dans l’exemple suivant :

Iterator<Secret> secrets = client.listSecrets().iterator();
while (it.hasNext()) {
   System.out.println("Secret is: " + it.next());
}

Itération sur des pages

Lorsque vous travaillez avec des pages individuelles, vous pouvez effectuer une itération par page, par exemple lorsque vous avez besoin d’informations de réponse HTTP ou lorsque les jetons de continuation sont importants pour conserver l’historique des itérations. Que vous effectuiez une itération par page ou par élément, il n’y a pas de différence de performances ou de nombre d’appels passés au service. L’implémentation sous-jacente charge la page suivante à la demande, et si vous annulez l’abonnement à PagedFlux à tout moment, aucun autre appel au service n’est nécessaire.

Utilisation pour une boucle For each

Lorsque vous appelez listSecrets(), vous recevez un PagedIterable, qui a une API iterableByPage(). Cette API produit Iterable<PagedResponse<Secret>> au lieu de Iterable<Secret>. PagedResponse fournit les métadonnées de réponse et l’accès au jeton de continuation, comme indiqué dans l’exemple suivant :

Iterable<PagedResponse<Secret>> secretPages = client.listSecrets().iterableByPage();
for (PagedResponse<Secret> page : secretPages) {
   System.out.println("Response code: " + page.getStatusCode());
   System.out.println("Continuation Token: " + page.getContinuationToken());
   page.getElements().forEach(secret -> System.out.println("Secret value: " + secret))
}

Il y a également une surcharge iterableByPage qui accepte un jeton de continuation. Vous pouvez appeler cette surcharge lorsque vous souhaitez revenir ultérieurement au même point d’itération.

Utilisation de Stream

L’exemple suivant montre comment la méthode streamByPage() effectue la même opération que celle présentée ci-dessus. Cette API a également une surcharge de jeton de continuation pour revenir ultérieurement au même point d’itération.

client.listSecrets()
      .streamByPage()
      .forEach(page -> {
          System.out.println("Response code: " + page.getStatusCode());
          System.out.println("Continuation Token: " + page.getContinuationToken());
          page.getElements().forEach(secret -> System.out.println("Secret value: " + secret))
      });

Observation asynchrone des pages et des éléments individuels

Cette section traite des API asynchrones. 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.

Observation des éléments individuels

L’exemple suivant montre comment l’API PagedFlux vous permet d’observer des éléments individuels de manière asynchrone. Il existe plusieurs façons de s’abonner à un type Flux. Pour plus d’informations, consultez Méthodes simples pour créer un flux ou mono et s’y abonner dans le Guide de référence Reactor 3. Cet exemple est une variété dans laquelle il existe trois expressions lambda, une pour le consommateur, le consommateur d’erreur et le consommateur complet. Il est recommandé d’avoir les trois, mais dans certains cas, le consommateur et éventuellement l’erreur consommateur suffisent.

asyncClient.listSecrets()
   .subscribe(secret -> System.out.println("Secret value: " + secret),
       ex -> System.out.println("Error listing secrets: " + ex.getMessage()),
       () -> System.out.println("Successfully listed all secrets"));

Observation des pages

L’exemple suivant montre comment l’API PagedFlux vous permet d’observer chaque page de manière asynchrone, à nouveau à l’aide d’une API byPage() et en fournissant un consommateur, un consommateur d’erreur et un consommateur d’achèvement.

asyncClient.listSecrets().byPage()
  .subscribe(page -> {
          System.out.println("Response code: " + page.getStatusCode());
          System.out.println("Continuation Token: " + page.getContinuationToken());
          page.getElements().forEach(secret -> System.out.println("Secret value: " + secret))
      },
      ex -> System.out.println("Error listing pages with secret: " + ex.getMessage()),
      () -> System.out.println("Successfully listed all pages with secret"));

Étapes suivantes

Maintenant que vous êtes familiarisé avec la pagination et l’itération dans le SDK Azure pour Java, vous pouvez consulter la section Opérations de longue durée dans le SDK Azure pour Java. Les opérations de longue durée sont des opérations qui s’exécutent pendant une durée plus longue que la plupart des requêtes HTTP normales, en général parce qu’elles nécessitent un effort côté serveur.