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

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

Muitas operações fornecidas pelas bibliotecas de cliente no SDK do Java do Azure retornam mais de um resultado. O SDK do 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:

• Tornar possível iterar facilmente em cada elemento na coleção individualmente, ignorando qualquer necessidade de paginação manual ou acompanhamento de tokens de continuação. Tanto PagedIterable quanto PagedFlux facilitam essa tarefa ao iterar uma resposta paginada desserializada em um determinado tipo T. PagedIterable implementa a Iterable interface e oferece uma API para receber um Stream, enquanto PagedFlux fornece um Flux. Em todos os casos, o ato de paginação é transparente e a iteração continua enquanto ainda há resultados iterados.

• Permita 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 iteração por página, ao invés de elemento individual.

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

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

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

Iterar em elementos individuais

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

Usar um loop for each

Como PagedIterable implementa Iterable, você pode iterar por meio dos elementos, conforme mostrado no exemplo a seguir:

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

Usar fluxo

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

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

Usar iterador

Como PagedIterable implementa Iterable, ele também tem um iterator() método para permitir o estilo de programação do iterador Java, conforme mostrado no exemplo a seguir:

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

Iterar em páginas

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

Usar um loop for each

Quando você chama listSecrets(), você recebe um PagedIterable, que possui uma API iterableByPage(). Essa API produz um Iterable<PagedResponse<Secret>> em vez de um Iterable<Secret>. O PagedResponse fornece os metadados de resposta e o 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 sobrecarga iterableByPage que aceita um token de continuação. Você pode chamar essa sobrecarga quando quiser retornar ao mesmo ponto de iteração posteriormente.

Usar fluxo

O exemplo a seguir mostra como o streamByPage() método executa a mesma operação, conforme 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))
      });

Observar assíncronamente páginas e elementos individuais

Esta seção aborda as APIs assíncronas. Em APIs assíncronas, as chamadas de rede ocorrem em um thread diferente do thread principal que chama subscribe(). O que isso significa é que o thread principal pode ser encerrado 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.

Observar elementos individuais

O exemplo a seguir mostra como a PagedFlux API permite observar elementos individuais de forma assíncrona. Há várias maneiras de assinar um tipo Flux. Para obter mais informações, confira Maneiras simples de criar um Flux ou Mono e assiná-lo no Guia de referência do Reactor 3. Este exemplo é uma variedade em que há três expressões lambda, uma de cada para o consumidor, o consumidor de erro e o consumidor completo. Ter as três é uma melhor prática, porém, 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 cliente, um cliente de erro e um cliente 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óximas etapas

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