Paginação e iteração no SDK do Azure para Java

  • Artigo

Este artigo fornece uma visão geral de como usar o SDK do Azure para funcionalidade de paginação e iteração Java para trabalhar de forma eficiente e produtiva com grandes conjuntos de dados.

Muitas operações fornecidas pelas bibliotecas de cliente no SDK Java do Azure retornam mais de um resultado. O SDK Java do Azure define um conjunto de tipos de retorno aceitáveis nesses casos para garantir que a experiência do desenvolvedor seja maximizada por meio da consistência. Os tipos de retorno usados são PagedIterable para APIs de sincronização e PagedFlux para APIs assíncronas. As APIs diferem ligeiramente por causa de seus diferentes casos de uso, mas conceitualmente elas têm os mesmos requisitos:

  • Torne possível iterar facilmente sobre cada elemento da coleção individualmente, ignorando qualquer necessidade de paginação manual ou rastreamento de tokens de continuação. Ambos PagedIterable e PagedFlux facilitar essa tarefa iterando sobre uma resposta paginada desserializada em um determinado tipo T. PagedIterableimplementa a Iterable interface e oferece uma API para receber um , enquanto PagedFlux fornece um StreamFluxarquivo . Em todos os casos, o ato de paginação é transparente e a iteração continua enquanto ainda há resultados repetidos.

  • Torne possível iterar explicitamente página por página. Isso permite que você entenda mais claramente quando as solicitações são feitas e permite que você acesse informações de resposta por página. Ambos PagedIterable e PagedFlux têm métodos que retornarão tipos apropriados para iterar por página, em vez de por elemento individual.

Este artigo é dividido entre as APIs síncronas e assíncronas do SDK do Java Azure. Você verá as APIs de iteração síncrona quando trabalhar com clientes síncronos e as APIs de iteração assíncrona quando trabalhar com clientes assíncronos.

Paginação e iteração síncronas

Esta seção aborda as APIs síncronas.

Iterar sobre elementos individuais

Como observado, o caso de uso mais comum é iterar sobre cada elemento individualmente, em vez de por página. Os exemplos de código a seguir mostram como a API permite que você use o estilo de PagedIterable iteração que preferir para implementar essa funcionalidade.

Use um loop para cada

Como PagedIterable implementa Iterableo , você pode iterar através dos elementos conforme mostrado no exemplo a seguir:

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

Usar o Stream

Como PagedIterable tem um stream() método definido nele, você pode chamá-lo para usar as APIs padrão do Java Stream, conforme mostrado no exemplo a seguir:

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

Usar o Iterator

Como PagedIterable implementa , ele também tem um iterator() método para permitir o estilo de Iterableprogramação do iterador Java, como mostra o exemplo a seguir:

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

Iterar sobre páginas

Ao trabalhar com páginas individuais, você pode iterar por página, por exemplo, quando precisar de informações de resposta HTTP ou quando os tokens de continuação forem importantes para manter o histórico de iterações. Independentemente de você iterar por página ou por cada item, não há diferença no desempenho ou no número de chamadas feitas para o serviço. A implementação subjacente carrega a próxima página sob demanda e, se você cancelar a assinatura a PagedFlux qualquer momento, não haverá mais chamadas para o serviço.

Use um loop para cada

Quando você liga listSecrets()para o , recebe um PagedIterable, que tem uma iterableByPage() API. Esta API produz um em vez de um Iterable<PagedResponse<Secret>>Iterable<Secret>arquivo . O PagedResponse fornece os metadados de resposta e acesso ao token de continuação, conforme mostrado no exemplo a seguir:

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

Há também uma iterableByPage sobrecarga que aceita um token de continuação. Você pode chamar essa sobrecarga quando quiser retornar ao mesmo ponto de iteração posteriormente.

Usar o Stream

O exemplo a seguir mostra como o streamByPage() método executa a mesma operação como mostrado acima. Essa API também tem uma sobrecarga de token de continuação para retornar ao mesmo ponto de iteração posteriormente.

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

Observe páginas e elementos individuais de forma assíncrona

Esta seção aborda as APIs assíncronas. Em APIs assíncronas, as chamadas de rede acontecem em um thread diferente do thread principal que chama subscribe(). O que isso significa é que o thread principal pode terminar antes que o resultado esteja disponível. Cabe a você garantir que o aplicativo não saia antes que a operação assíncrona tenha tido tempo de ser concluída.

Observe elementos individuais

O exemplo a seguir mostra como a PagedFlux API permite observar elementos individuais de forma assíncrona. Existem várias formas de subscrever um tipo Flux. Para obter mais informações, consulte Maneiras simples de criar um fluxo ou mono e assiná-lo no Guia de referência do Reator 3. Este exemplo é uma variedade em que existem três expressões lambda, uma para cada consumidor, o consumidor de erro e o consumidor completo. Ter os três é uma boa prática, mas em alguns casos só é necessário ter o consumidor e, possivelmente, o consumidor de erro.

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

Observar páginas

O exemplo a seguir mostra como a PagedFlux API permite observar cada página de forma assíncrona, novamente usando uma byPage() API e fornecendo um consumidor, um consumidor de erro e um consumidor de conclusão.

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

Próximos passos

Agora que você está familiarizado com paginação e iteração no SDK do Azure para Java, considere revisar Operações de longa execução no SDK do Azure para Java. Operações de longa execução são operações que são executadas por um período maior do que a maioria das solicitações HTTP normais, normalmente porque exigem algum esforço no lado do servidor.