Sidnumrering och iteration i Azure SDK för Java

  • Artikel

Den här artikeln innehåller en översikt över hur du använder Azure SDK för Java-sidnumrering och iterationsfunktioner för att arbeta effektivt och produktivt med stora datamängder.

Många åtgärder som tillhandahålls av klientbiblioteken i Azure Java SDK returnerar mer än ett resultat. Azure Java SDK definierar en uppsättning godtagbara returtyper i dessa fall för att säkerställa att utvecklarupplevelsen maximeras genom konsekvens. De returtyper som används är PagedIterable för synkroniserings-API:er och PagedFlux för asynkrona API:er. API:erna skiljer sig något beroende på deras olika användningsfall, men begreppsmässigt har de samma krav:

  • Gör det möjligt att enkelt iterera över varje element i samlingen individuellt och ignorera eventuella behov av manuell sidnumrering eller spårning av fortsättningstoken. Både PagedIterable och PagedFlux gör den här uppgiften enkel genom att iterera över ett sidnumrerat svar som deserialiserats till en viss typ T. PagedIterable implementerar Iterable gränssnittet och erbjuder ett API för att ta emot en Stream, medan PagedFlux tillhandahåller en Flux. I samtliga fall är sidnumreringen transparent och iterationen fortsätter medan det fortfarande finns resultat iterera över.

  • Gör det möjligt att iterera explicit sida för sida. På så sätt kan du bättre förstå när begäranden görs och du kan komma åt svarsinformation per sida. Både PagedIterable och PagedFlux har metoder som returnerar lämpliga typer för att iterera efter sida, i stället för efter enskilda element.

Den här artikeln är uppdelad mellan Synkrona och asynkrona API:er för Java Azure SDK. Du ser synkrona iterations-API:er när du arbetar med synkrona klienter och asynkrona iterations-API:er när du arbetar med asynkrona klienter.

Synkron sidnumrering och iteration

Det här avsnittet beskriver synkrona API:er.

Iterera över enskilda element

Som nämnts är det vanligaste användningsfallet att iterera över varje element individuellt, snarare än per sida. Följande kodexempel visar hur API:et PagedIterable låter dig använda iterationsformatet som du föredrar för att implementera den här funktionen.

Använda en for-each-loop

Eftersom PagedIterable implementerar Iterablekan du iterera genom elementen enligt följande exempel:

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

Använda Stream

Eftersom PagedIterable en stream() metod har definierats för den kan du anropa den för att använda Java Stream-standard-API:er, som du ser i följande exempel:

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

Använda iterator

Eftersom PagedIterable implementerar Iterablehar den också en iterator() metod för att tillåta programmeringsstilen Java-iterator, vilket visas i följande exempel:

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

Iterera över sidor

När du arbetar med enskilda sidor kan du iterera per sida, till exempel när du behöver HTTP-svarsinformation eller när fortsättningstoken är viktiga för att behålla iterationshistoriken. Oavsett om du itererar efter sida eller varje objekt finns det ingen skillnad i prestanda eller antalet anrop som görs till tjänsten. Den underliggande implementeringen läser in nästa sida på begäran, och om du avregistrerar dig från den PagedFlux när som helst finns det inga ytterligare anrop till tjänsten.

Använda en for-each-loop

När du anropar listSecrets()får du en PagedIterable, som har ett iterableByPage() API. Det här API:et genererar en Iterable<PagedResponse<Secret>> i stället för en Iterable<Secret>. PagedResponse Ger svarsmetadata och åtkomst till fortsättningstoken, som du ser i följande exempel:

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

Det finns också en iterableByPage överlagring som accepterar en fortsättningstoken. Du kan anropa den här överbelastningen när du vill återgå till samma iteration vid ett senare tillfälle.

Använda Stream

I följande exempel visas hur streamByPage() metoden utför samma åtgärd som ovan. Det här API:et har också en fortsättningstokenöverlagring för att återgå till samma iterationsplats vid ett senare tillfälle.

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

Observera sidor och enskilda element asynkront

Det här avsnittet beskriver asynkrona API:er. I asynkrona API:er sker nätverksanropen i en annan tråd än huvudtråden som anropar subscribe(). Det innebär att huvudtråden kan avslutas innan resultatet är tillgängligt. Det är upp till dig att se till att programmet inte avslutas innan asynkroniseringsåtgärden har haft tid att slutföras.

Observera enskilda element

I följande exempel visas hur API:et PagedFlux låter dig observera enskilda element asynkront. Det finns olika sätt att prenumerera på en Flux-typ. Mer information finns i Enkla sätt att skapa en flux eller mono och prenumerera på den i referensguiden för Reactor 3. Det här exemplet är en variant där det finns tre lambda-uttryck, ett var för konsumenten, felkonsumenten och den fullständiga konsumenten. Att ha alla tre är bra praxis, men i vissa fall är det bara nödvändigt att ha konsumenten, och eventuellt felkonsumenten.

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

Observera sidor

I följande exempel visas hur API:et PagedFlux låter dig observera varje sida asynkront, igen med hjälp av ett byPage() API och genom att tillhandahålla en konsument, felkonsument och en slutförande konsument.

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

Nästa steg

Nu när du är bekant med sidnumrering och iteration i Azure SDK för Java kan du överväga att granska långvariga åtgärder i Azure SDK för Java. Långvariga åtgärder är åtgärder som körs under en längre tid än de flesta vanliga HTTP-begäranden, vanligtvis eftersom de kräver viss ansträngning på serversidan.