本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# Amazon EC2 API 中的分頁
<a name="ec2-api-pagination"></a>

我們建議您在呼叫 時使用分頁描述可能傳回大量結果的動作，例如 `DescribeInstances`。使用分頁會限制描述呼叫傳回的項目數量，以及呼叫傳回所需的時間。如果您有大量資源，未分頁的呼叫可能會受到調節，並可能會逾時。因此，分頁呼叫的整體延遲比未分頁呼叫更佳，因為分頁呼叫始終成功。

如需更多資訊，請參閱《Amazon EC2 API 參考》**中的[分頁](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/Query-Requests.html#api-pagination)。

## 最佳實務
<a name="pagination-best-practices"></a>

盡可能在描述呼叫中指定資源 IDs清單。這是描述大量資源最快的方式。請注意，您不應該在單一呼叫中指定超過 1，000 IDs。以下是範例。

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

如果您無法在描述呼叫中指定資源 IDs，我們強烈建議您使用分頁。以下是範例。

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

如果您需要重試分頁呼叫，請使用[指數退避與抖動](ec2-api-throttling.md#api-backoff)。

## 常見問題
<a name="pagination-common-issues"></a>

以下是不小心進行未分頁呼叫的程式碼範例。

**Example 範例問題：傳遞資源 IDs的空清單**  
下列程式碼使用 IDs清單。不過，如果清單是空的，則結果為未分頁的呼叫。  

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

**Example 範例問題：未設定 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;
}
```