Paginazione e iterazione in Azure SDK per Java

Questo articolo offre una panoramica di come usare la paginazione e l'iterazione di Azure SDK per Java per funzionare in modo efficiente e produttivo con set di dati di grandi dimensioni.

Molte operazioni fornite dalle librerie client all'interno di Azure Java SDK restituiscono più di un risultato. Azure Java SDK definisce un set di tipi restituiti accettabili in questi casi per garantire che l'esperienza di sviluppo sia ottimizzata tramite coerenza. I tipi restituiti usati sono PagedIterable per le API di sincronizzazione e PagedFlux per le API asincrone. Le API differiscono leggermente in base ai diversi casi d'uso, ma concettualmente hanno gli stessi requisiti:

• È possibile eseguire facilmente l'iterazione su ogni elemento della raccolta singolarmente, ignorando eventuali esigenze di impaginazione manuale o rilevamento dei token di continuazione. Sia PagedIterable che PagedFlux semplificano l'iterazione di questa attività su una risposta impaginata deserializzata in un determinato tipo T. PagedIterable implementa l'interfaccia Iterable e offre un'API per ricevere un Streamoggetto , mentre PagedFlux fornisce un oggetto Flux. In tutti i casi, l'azione di impaginazione è trasparente e l'iterazione continua mentre sono ancora presenti risultati iterazione.

• È possibile scorrere in modo esplicito la pagina per pagina. In questo modo è possibile comprendere più chiaramente quando vengono effettuate richieste e consente di accedere alle informazioni di risposta per pagina. Entrambi e PagedFlux dispongono di PagedIterable metodi che restituiscono tipi appropriati per eseguire l'iterazione per pagina, anziché per singolo elemento.

Questo articolo è suddiviso tra le API sincrone e asincrone di Java Azure SDK. Le API di iterazione sincrona vengono visualizzate quando si lavora con i client sincroni e le API di iterazione asincrone quando si lavora con client asincroni.

Paginazione e iterazione sincrona

Questa sezione illustra le API sincrone.

Scorrere i singoli elementi

Come indicato, il caso d'uso più comune consiste nell'eseguire l'iterazione di ogni elemento singolarmente, anziché per pagina. Gli esempi di codice seguenti illustrano come l'API PagedIterable consente di usare lo stile di iterazione preferito per implementare questa funzionalità.

Usare un ciclo for-each

Poiché PagedIterable implementa Iterable, è possibile scorrere gli elementi come illustrato nell'esempio seguente:

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

Usare Stream

Poiché PagedIterable ha un stream() metodo definito su di esso, è possibile chiamarlo per usare le API Di flusso Java standard, come illustrato nell'esempio seguente:

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

Usare Iteratore

Poiché PagedIterable implementa Iterable, include anche un iterator() metodo per consentire lo stile di programmazione dell'iteratore Java, come illustrato nell'esempio seguente:

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

Scorrere le pagine

Quando si lavora con singole pagine, è possibile eseguire l'iterazione per pagina, ad esempio quando sono necessarie informazioni sulla risposta HTTP o quando i token di continuazione sono importanti per conservare la cronologia di iterazione. Indipendentemente dal fatto che l'iterazione venga eseguita in base alla pagina o a ogni elemento, non esiste alcuna differenza nelle prestazioni o nel numero di chiamate effettuate al servizio. L'implementazione sottostante carica la pagina successiva su richiesta e, se si annulla la PagedFlux sottoscrizione a in qualsiasi momento, non sono presenti ulteriori chiamate al servizio.

Usare un ciclo for-each

Quando si chiama listSecrets(), si ottiene un PagedIterableoggetto , che ha un'API iterableByPage() . Questa API produce un anziché Iterable<PagedResponse<Secret>> un oggetto Iterable<Secret>. PagedResponse fornisce i metadati della risposta e l'accesso al token di continuazione, come illustrato nell'esempio seguente:

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

Esiste anche un iterableByPage overload che accetta un token di continuazione. È possibile chiamare questo overload quando si vuole tornare allo stesso punto di iterazione in un secondo momento.

Usare Stream

Nell'esempio seguente viene illustrato come il streamByPage() metodo esegue la stessa operazione illustrata in precedenza. Questa API ha anche un overload del token di continuazione per tornare allo stesso punto di iterazione in un secondo momento.

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

Osservare in modo asincrono pagine e singoli elementi

Questa sezione illustra le API asincrone. Nelle API asincrone, le chiamate di rete vengono eseguite in un thread diverso rispetto al thread principale che chiama subscribe(). Ciò significa che il thread principale può terminare prima che il risultato sia disponibile. È necessario assicurarsi che l'applicazione non venga chiusa prima del completamento dell'operazione asincrona.

Osservare singoli elementi

L'esempio seguente illustra come l'API PagedFlux consente di osservare i singoli elementi in modo asincrono. Esistono diversi modi per sottoscrivere un tipo Flux. Per altre informazioni, vedere Simple Ways to Create a Flux or Mono and Subscribe to It (Modi semplici per creare un flusso o mono) e sottoscriverlo nella Guida di riferimento del Reattore 3. Questo esempio è un'unica varietà in cui sono presenti tre espressioni lambda, una per il consumer, il consumer di errori e il consumer completo. Avere tutte e tre le procedure consigliate, ma in alcuni casi è necessario solo avere il consumer e possibilmente il consumer di errori.

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

Osservare le pagine

L'esempio seguente illustra come l'API PagedFlux consente di osservare ogni pagina in modo asincrono, di nuovo usando un'API byPage() e fornendo un consumer di errore, un consumer di errori e un consumer di completamento.

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

Passaggi successivi

Ora che si ha familiarità con la paginazione e l'iterazione in Azure SDK per Java, è consigliabile esaminare le operazioni a esecuzione prolungata in Azure SDK per Java. Le operazioni a esecuzione prolungata sono operazioni eseguite per una durata maggiore rispetto alla maggior parte delle normali richieste HTTP, in genere perché richiedono un certo impegno sul lato server.