Paginering en iteratie in de Azure SDK voor Java

Dit artikel bevat een overzicht van het gebruik van de Azure SDK voor java-paginering en iteratiefunctionaliteit om efficiënt en productief te werken met grote gegevenssets.

Veel bewerkingen die door de clientbibliotheken in de Azure Java SDK worden geleverd, retourneren meer dan één resultaat. De Azure Java SDK definieert in deze gevallen een set acceptabele retourtypen om ervoor te zorgen dat de ontwikkelaarservaring wordt gemaximaliseerd via consistentie. De gebruikte retourtypen zijn PagedIterable voor synchronisatie-API's en PagedFlux voor asynchrone API's. De API's verschillen enigszins vanwege hun verschillende gebruiksvoorbeelden, maar conceptueel hebben ze dezelfde vereisten:

• Maak het mogelijk om elk element in de verzameling afzonderlijk te herhalen, waarbij handmatige paginering of tracering van vervolgtokens wordt genegeerd. Beide PagedIterable en PagedFlux maken deze taak eenvoudig door een gepagineerd antwoord gedeserialiseerd in een bepaald type Tte herhalen. PagedIterable implementeert de Iterable interface en biedt een API voor het ontvangen van een Stream, terwijl PagedFlux een Flux. In alle gevallen is de handeling van paginering transparant en wordt de iteratie voortgezet terwijl er nog steeds resultaten worden herhaald.

• Maak het mogelijk om expliciet pagina-per-pagina te herhalen. Als u dit doet, krijgt u meer inzicht wanneer er aanvragen worden ingediend en hebt u toegang tot antwoordinformatie per pagina. Beide PagedIterable en PagedFlux hebben methoden die de juiste typen retourneren om per pagina te herhalen, in plaats van per afzonderlijk element.

Dit artikel is verdeeld over de synchrone en asynchrone API's van de Java Azure SDK. U ziet de synchrone iteratie-API's wanneer u werkt met synchrone clients en asynchrone iteratie-API's wanneer u met asynchrone clients werkt.

Synchrone paginering en iteratie

In deze sectie worden de synchrone API's behandeld.

Herhalen over afzonderlijke elementen

Zoals vermeld, is de meest voorkomende use-case het afzonderlijk herhalen van elk element in plaats van per pagina. In de volgende codevoorbeelden ziet u hoe u met de PagedIterable API de iteratiestijl kunt gebruiken die u liever wilt implementeren.

Een for-each-lus gebruiken

Omdat PagedIterable dit wordt geïmplementeerd Iterable, kunt u de elementen herhalen, zoals wordt weergegeven in het volgende voorbeeld:

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

Stream gebruiken

Omdat PagedIterable er een stream() methode is gedefinieerd, kunt u deze aanroepen om de standaard Java Stream-API's te gebruiken, zoals wordt weergegeven in het volgende voorbeeld:

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

Iterator gebruiken

Omdat PagedIterable deze wordt geïmplementeerd Iterable, heeft het ook een iterator() methode om de Java-iterator-programmeerstijl toe te staan, zoals wordt weergegeven in het volgende voorbeeld:

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

Pagina's herhalen

Wanneer u met afzonderlijke pagina's werkt, kunt u per pagina herhalen, bijvoorbeeld wanneer u HTTP-antwoordgegevens nodig hebt of wanneer vervolgtokens belangrijk zijn om de iteratiegeschiedenis te behouden. Ongeacht of u per pagina of elk item itereert, is er geen verschil in prestaties of het aantal aanroepen naar de service. De onderliggende implementatie laadt de volgende pagina op aanvraag en als u zich op elk moment afmeldt voor de PagedFlux service, zijn er geen verdere aanroepen naar de service.

Een for-each-lus gebruiken

Wanneer u aanroept listSecrets(), krijgt u een PagedIterable, die een iterableByPage() API heeft. Deze API produceert een Iterable<PagedResponse<Secret>> in plaats van een Iterable<Secret>. De PagedResponse functie bevat de metagegevens van het antwoord en toegang tot het vervolgtoken, zoals wordt weergegeven in het volgende voorbeeld:

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))
}

Er is ook een iterableByPage overbelasting die een vervolgtoken accepteert. U kunt deze overbelasting aanroepen wanneer u op een later tijdstip wilt terugkeren naar hetzelfde iteratiepunt.

Stream gebruiken

In het volgende voorbeeld ziet u hoe de streamByPage() methode dezelfde bewerking uitvoert als hierboven. Deze API heeft ook een overbelasting van het vervolgtoken voor het terugkeren naar hetzelfde iteratiepunt op een later tijdstip.

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

Asynchroon pagina's en afzonderlijke elementen observeren

In deze sectie worden de asynchrone API's behandeld. In asynchrone API's vinden de netwerkoproepen plaats in een andere thread dan de hoofdthread die aanroept subscribe(). Dit betekent dat de hoofdthread kan worden beëindigd voordat het resultaat beschikbaar is. Het is aan u om ervoor te zorgen dat de toepassing niet wordt afgesloten voordat de asynchrone bewerking is voltooid.

Afzonderlijke elementen observeren

In het volgende voorbeeld ziet u hoe u met de PagedFlux API afzonderlijke elementen asynchroon kunt observeren. Er zijn verschillende manieren om u te abonneren op een Flux-type. Zie Simple Ways to Create a Flux or Mono and Subscribe to It in the Reactor 3 Reference Guide (Eenvoudige manieren om een flux of mono te maken) voor meer informatie. Dit voorbeeld is één variëteit waarbij er drie lambda-expressies zijn, één voor de consument, de foutconsumer en de volledige consument. Het is een goede gewoonte om alle drie te gebruiken, maar in sommige gevallen is het alleen nodig om de consument en mogelijk de foutconsumer te hebben.

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

Pagina's observeren

In het volgende voorbeeld ziet u hoe u met de PagedFlux API elke pagina asynchroon kunt bekijken, opnieuw met behulp van een byPage() API en door een consument, foutconsumer en een voltooiingsconsumer op te geven.

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

Volgende stappen

Nu u bekend bent met paginering en iteratie in de Azure SDK voor Java, kunt u overwegen om langlopende bewerkingen te bekijken in de Azure SDK voor Java. Langlopende bewerkingen zijn bewerkingen die worden uitgevoerd voor een langere duur dan de meeste normale HTTP-aanvragen, meestal omdat ze enige inspanning aan de serverzijde vereisen.