Pagination et itération dans le Kit de développement logiciel (SDK) Azure pour Java

Cet article fournit une vue d’ensemble de l’utilisation du Kit de développement logiciel (SDK) Azure pour la pagination et l’itération Java afin de fonctionner efficacement et efficacement avec de grands jeux de données.

De nombreuses opérations fournies par les bibliothèques clientes dans le Kit de développement logiciel (SDK) Java Azure retournent plusieurs résultats. Le Kit de développement logiciel (SDK) Java Azure définit un ensemble de types de retour acceptables dans ces cas pour garantir que l’expérience du développeur est agrandie par le biais de la cohérence. Les types de retour utilisés sont PagedIterable utilisés pour les API de synchronisation et PagedFlux pour les API asynchrones. Les API diffèrent légèrement en fonction de leurs différents cas d’usage, mais conceptuellement, elles ont les mêmes exigences :

• Permet d’itérer facilement chaque élément de la collection individuellement, 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’itérer explicitement une page par page. Cela vous permet de comprendre plus clairement quand les demandes sont effectuées et vous permet d’accéder aux informations de réponse par page. Les éléments PagedIterable et PagedFlux ont des méthodes qui retournent des types appropriés pour itérer par page, plutôt que par élément individuel.

Cet article est divisé entre les API synchrones et asynchrones du Kit de développement logiciel (SDK) Azure Java. Vous verrez les API d’itération synchrone 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.

Parcourir chaque élément individuellement

Comme indiqué, le cas d’usage le plus courant consiste à itérer 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 implémenter cette fonctionnalité.

Utiliser une boucle for-each

Comme PagedIterable l’implémente Iterable, vous pouvez effectuer une itération au sein des éléments, comme illustré dans l’exemple suivant :

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

Utilisation de Stream

Étant donné qu’une PagedIterablestream() méthode est définie dessus, vous pouvez l’appeler pour utiliser les API Java Stream standard, comme illustré dans l’exemple suivant :

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

Utiliser itérateur

Comme PagedIterable l’implémente Iterable, il a également une méthode iterator() pour permettre le style de programmation des itérateurs Java, comme le montre l'exemple suivant :

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

Itération dans les pages

Lorsque vous utilisez des pages individuelles, vous pouvez itérer 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 itéreriez par page ou par chaque élément, il n’y a aucune différence de performances ou de nombre d’appels effectués au service. L’implémentation sous-jacente charge la page suivante à la demande et, si vous vous désabonnez de PagedFlux à tout moment, il n’y a aucun autre appel au service.

Utiliser une boucle for-each

Lorsque vous appelez listSecrets(), vous obtenez un PagedIterable, qui a une iterableByPage() API. Cette API produit un Iterable<PagedResponse<Secret>> au lieu d’un Iterable<Secret>. PagedResponse fournit les métadonnées de réponse et l'accès au jeton de continuation, comme illustré 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 au même point d'itération à un moment ultérieur.

Utilisation de Stream

L’exemple suivant montre comment la streamByPage() méthode effectue la même opération que celle indiqué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))
      });

Observer de manière 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 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.

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 différentes 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, en utilisant à nouveau l’API byPage() et en fournissant un consommateur, un consommateur d’erreurs, et un consommateur de fin.

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 Kit de développement logiciel (SDK) Azure pour Java, envisagez d’examiner les 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, généralement parce qu’elles nécessitent un certain effort côté serveur.