Amazon EC2 API でのページ分割

DescribeInstances など、多数の結果を返す可能性のある記述アクションを呼び出す場合は、ページ分割を使用することをお勧めします。ページ分割を使用すると、記述呼び出しによって返される項目の数と、呼び出しが戻るのにかかる時間が制限されます。多数のリソースがある場合、ページ分割されていない呼び出しはスロットリングされ、タイムアウトする可能性があります。したがって、ページ分割された呼び出しは一貫して成功するため、ページ分割されていない呼び出しよりもページ分割された呼び出しの方が全体的なレイテンシーが優れています。

詳細については、「Amazon EC2 API リファレンス」の「Pagination」(ページネーション) を参照してください。

ベストプラクティス

可能な場合は、記述呼び出しでリソース ID のリストを指定します。これは、多数のリソースを記述する最も速い方法です。1 回の呼び出しで 1,000 を超える ID を指定しないでください。以下に例を示します。

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

記述呼び出しでリソース ID を指定できない場合は、ページ分割を使用することを強くお勧めします。以下に例を示します。

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

ページ分割された呼び出しを再試行する必要がある場合は、ジッターでエクスポネンシャルバックオフを使用します。

一般的な問題

以下は、誤ってページ分割されていない呼び出しを行うコードの例です。

例 問題の例: リソース ID の空のリストを渡す

次のコードは ID のリストを使用します。ただし、リストが空の場合、結果はページ分割されていない呼び出しになります。

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

例 問題の例: MaxResults を設定しない

次のコードは nextToken をチェックして使用しますが、MaxResults を設定しません。

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

この問題を修正するには、次のように withMaxResults を追加します。

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