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 questa attività iterando 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 finché ci sono ancora risultati su cui iterare.

• Consentire di scorrere esplicitamente 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 PagedIterable e PagedFlux dispongono di 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 l'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());
}

Iterare sulle 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, in qualsiasi momento, se si annulla la sottoscrizione a PagedFlux, non verranno effettuate ulteriori chiamate al servizio.

Usare un ciclo for-each

Quando si chiama listSecrets(), si ottiene un PagedIterable oggetto, che ha un'API iterableByPage(). Questa API produce un oggetto Iterable<PagedResponse<Secret>> anziché un 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 sovraccarico del token di continuazione per tornare allo stesso punto di iterazione in un momento successivo.

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. Spetta a te assicurarti che l'applicazione non si chiuda 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 abbonarsi a un tipo di 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 è una varietà in cui sono presenti tre espressioni lambda, una ciascuna per il consumer, il consumer di errori e il consumer completo. Avere tutte e tre è una buona pratica, ma in alcuni casi è necessario avere solo il consumatore e possibilmente il gestore 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 consenta di monitorare ogni pagina in modo asincrono, anche servendosi dell'API byPage() e fornendo un consumer, un consumer di errore 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.