Paginação na API do Amazon EC2

Recomendamos que você use a paginação ao chamar ações de descrição que podem exibir um grande número de resultados, como DescribeInstances. O uso da paginação limita o número de itens exibidos por uma chamada de descrição e o tempo necessário para o retorno da chamada. Se você tiver um grande número de recursos, chamadas não paginadas poderão ter controle de utilização e atingir o tempo limite. Portanto, a latência geral é melhor com chamadas paginadas do que com chamadas não paginadas porque as chamadas paginadas são consistentemente bem-sucedidas.

Para obter mais informações, consulte Pagination (Paginação) em Amazon EC2 API Reference (Referência de API do Amazon EC2).

Práticas recomendadas

Sempre que possível, especifique uma lista de IDs de recursos em suas chamadas de descrição. Essa é a maneira mais rápida de descrever um grande número de recursos. Observe que você não deve especificar mais de mil IDs em uma única chamada. Veja um exemplo a seguir.

private List<Reservation> describeMyInstances(List<String> ids){
    if (ids == null || ids.isEmpty()) {
        return ImmutableList.of();
    }
        
    final DescribeInstancesRequest request = new DescribeInstancesRequest()
            .withInstanceIds(ids);

    return ec2.describeInstances(request).getReservations();
}

Caso você não possa especificar IDs de recursos em suas chamadas de descrição, é altamente recomendável usar a paginação. Veja um exemplo a seguir.

private List<Reservation> describeMyInstances(final Collection<Filter> filters){
    final DescribeInstancesRequest request = new DescribeInstancesRequest()
            .withFilters(filters)
            .withMaxResults(1000);

    List<Reservation> reservations = new ArrayList<>();
    String nextToken = null;
    do {
        request.setNextToken(nextToken);
        final DescribeInstancesResult response = ec2.describeInstances(request);
        reservations.addAll(response.getReservations());
        nextToken = response.getNextToken();
    } while (nextToken != null);

    return reservations;
}

Se você precisar repetir uma chamada paginada, use o recuo exponencial com instabilidade.

Problemas comuns

Veja a seguir exemplos de código que inadvertidamente faz chamadas não paginadas.

private List<Reservation> describeMyInstances(List<String> ids){
    final DescribeInstancesRequest request = new DescribeInstancesRequest()
            .withInstanceIds(ids);

    return ec2.describeInstances(request).getReservations();
}

private List<Reservation> describeMyInstances(List<String> ids){
    if (ids == null || ids.isEmpty()) {
        return ImmutableList.of();
        // OR
        return Lists.newArrayList();
        // OR
        return new ArrayList<>();
    }
        
    final DescribeInstancesRequest request = new DescribeInstancesRequest()
            .withInstanceIds(ids);

    return ec2.describeInstances(request).getReservations();
}

private List<Reservation> describeMyInstances(final Collection<Filter> filters){
    final DescribeInstancesRequest request = new DescribeInstancesRequest()
            .withFilters(filters);

    List<Reservation> reservations = new ArrayList<>();
    String nextToken = null;
    do {
        request.setNextToken(nextToken);
        final DescribeInstancesResult response = ec2.describeInstances(request);
        reservations.addAll(response.getReservations());
        nextToken = response.getNextToken();
    } while (nextToken != null);

    return reservations;
}

private List<Reservation> describeMyInstances(final Collection<Filter> filters){
    final DescribeInstancesRequest request = new DescribeInstancesRequest()
            .withFilters(filters)
            .withMaxResults(1000);

    List<Reservation> reservations = new ArrayList<>();
    String nextToken = null;
    do {
        request.setNextToken(nextToken);
        final DescribeInstancesResult response = ec2.describeInstances(request);
        reservations.addAll(response.getReservations());
        nextToken = response.getNextToken();
    } while (nextToken != null);

    return reservations;
}