Compartir a través de

Paginación e iteración en el SDK de Azure para Java

En este artículo se proporciona información general sobre cómo usar la funcionalidad de paginación e iteración de Azure SDK para Java para trabajar de forma eficaz y productiva con grandes conjuntos de datos.

Muchas operaciones proporcionadas por las bibliotecas cliente dentro del SDK de Java de Azure devuelven más de un resultado. El SDK de Java de Azure define un conjunto de tipos de valor devuelto aceptables en estos casos para asegurarse de que la experiencia del desarrollador se maximiza a través de la coherencia. Los tipos de valor devuelto que se usan son PagedIterable para las API de sincronización y PagedFlux para las API asincrónicas. Las API difieren ligeramente en función de sus distintos casos de uso, pero conceptualmente tienen los mismos requisitos:

  • Permite iterar fácilmente todos los elementos de la colección de forma individual, ignorando la necesidad de paginación manual o seguimiento de los tokens de continuación. Tanto PagedIterable como PagedFlux facilitan esta tarea mediante la iteración de una respuesta paginada deserializada en un tipo T determinado. PagedIterableimplementa la Iterable interfaz y ofrece una API para recibir un Stream, mientras que PagedFlux proporciona .Flux En todos los casos, el acto de la paginación es transparente y la iteración continúa mientras haya resultados en los que realizar la iteración.

  • Permite realizar una iteración página a página de forma explícita. Al hacerlo, podrá comprender más claramente cuándo se realizan las solicitudes y le permite acceder a la información de respuesta por página. Tanto PagedIterable como PagedFlux tienen métodos que devolverán los tipos adecuados para iterar por página, en lugar de por elemento individual.

Este artículo se divide entre las API sincrónicas y asincrónicas del SDK de Azure para Java. Verá las API de iteración sincrónicas cuando trabaje con clientes sincrónicos y API de iteración asincrónicas al trabajar con clientes asincrónicos.

Paginación y iteración sincrónicas

En esta sección se tratan las API sincrónicas.

Iteración de elementos individuales

Como se ha indicado, lo más habitual es que las iteraciones se realicen en cada elemento individualmente, en lugar de por página. En los ejemplos de código siguientes se muestra cómo la PagedIterable API le permite usar el estilo de iteración que prefiere implementar esta funcionalidad.

Uso de un bucle "for-each"

Dado que PagedIterable implementa Iterable, puede iterar los elementos como se muestra en el siguiente ejemplo.

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

Uso de Stream

Como PagedIterable tiene un método stream() definido, puedes llamarlo para usar las API estándar de Java Stream, como se muestra en el siguiente ejemplo:

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

Uso de Iterator

Dado que PagedIterable implementa Iterable, también tiene un método iterator() para permitir el estilo de programación del iterador Java, como se muestra en el siguiente ejemplo.

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

Iteración en páginas

Al trabajar con páginas individuales, puede realizar una iteración página por página, por ejemplo, cuando necesita información de respuesta HTTP, o bien cuando los tokens de continuación son importantes para conservar el historial de iteración. Independientemente de si se itera por página o por elemento, no hay diferencia alguna en el rendimiento ni en el número de llamadas hechas al servicio. La implementación subyacente carga la página siguiente a petición y, si cancela la suscripción PagedFlux en cualquier momento, no hay más llamadas al servicio.

Uso de un bucle "for-each"

Cuando llamas a listSecrets(), obtienes un PagedIterable, que tiene una API iterableByPage(). Esta API produce un Iterable<PagedResponse<Secret>> en lugar de un Iterable<Secret>. PagedResponse proporciona los metadatos de respuesta y el acceso al token de continuación, como se muestra en el ejemplo siguiente:

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

También hay una sobrecarga de iterableByPage que acepta un token de continuación. Si se desea volver al mismo punto de iteración más adelante, se puede llamar a esta sobrecarga.

Uso de Stream

En el ejemplo siguiente se muestra cómo el streamByPage() método realiza la misma operación que se muestra anteriormente. Esta API también tiene una sobrecarga de token de continuación que permite retomar la iteración desde el mismo punto en un momento posterior.

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

Observar de forma asincrónica páginas y elementos individuales

En esta sección se describen las API asincrónicas. En las API asincrónicas, las llamadas de red se producen en un subproceso diferente del subproceso principal que llama a subscribe(). Esto significa que el subproceso principal puede finalizar antes de que el resultado esté disponible. Es necesario asegurarse de que la aplicación no se cierre antes de que la operación asincrónica haya tenido tiempo de completarse.

Observar elementos individuales

En el ejemplo siguiente se muestra cómo la PagedFlux API le permite observar elementos individuales de forma asincrónica. Hay varias maneras de suscribirse a un tipo de flujo. Para obtener más información, vea Formas sencillas de crear un flujo o Mono y suscribirse a él en la Guía de referencia de Reactor 3. Este ejemplo es una variedad en la que hay tres expresiones lambda, una para el consumidor, otra para el consumidor de errores y una tercera para el consumidor de finalización. Se recomienda tener las tres, pero en algunos casos solo es necesario tener la primera y, posiblemente, la segunda.

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

Observación de páginas

En el ejemplo siguiente se muestra la forma en que PagedFlux API permite observar cada página asincrónicamente, una vez más mediante una API byPage() y proporcionando un consumidor, un consumidor de errores y un consumidor de finalización.

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

Pasos siguientes

Ahora que tiene ciertas nociones de paginación y iteración en Azure SDK para Java, considere la posibilidad de leer el artículo Operaciones de larga duración en Azure SDK para Java. Las operaciones de larga duración son operaciones que se ejecutan durante más tiempo que la mayoría de las solicitudes HTTP normales, normalmente porque requieren algún esfuerzo en el lado servidor.