本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用分頁結果：掃描和查詢
DynamoDB 增強型用戶端 API 的 `scan``query`和 `batch`方法會傳回具有一或多個*頁面*的回應。頁面包含一或多個項目。您的程式碼可以根據每一頁處理回應，也可以處理個別項目。
同步`DynamoDbEnhancedClient`用戶端傳回的分頁回應會傳回 [PageIterable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/PageIterable.html) 物件，而非同步傳回的回應則會`DynamoDbEnhancedAsyncClient`傳回 [PagePublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/PagePublisher.html) 物件。
本節會查看處理分頁結果，並提供使用掃描和查詢 APIs的範例。
## 掃描資料表
SDK 的 [https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbAsyncTable.html#scan(java.util.function.Consumer)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbAsyncTable.html#scan(java.util.function.Consumer))方法對應至相同名稱的 [DynamoDB 操作](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Scan.html)。DynamoDB 增強型用戶端 API 提供相同的選項，但它使用熟悉的物件模型並為您處理分頁。
首先，我們透過查看同步映射類別 [DynamoDbTable](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html) `scan`的方法來探索`PageIterable`界面。
### 使用同步 API
下列範例顯示使用 [表達](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/Expression.html)式篩選傳回項目`scan`的方法。[ProductCatalog](ddb-en-client-use.md#ddb-en-client-use-compare-cs3) 是先前顯示的模型物件。
註解行 2 之後顯示的篩選表達式會將傳回`ProductCatalog`的項目限制為價格值介於 8.00 到 80.00 的項目。
此範例也會使用註解行 1 之後顯示`attributesToProject`的方法排除`isbn`值。
在註解行 3 之後， `PageIterable` 物件 `pagedResults`會由 `scan`方法傳回。的 `stream`方法會`PageIterable`傳回[https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Stream.html)物件，您可以用來處理頁面。在此範例中，會計算並記錄頁數。
從註解行 4 開始，範例顯示存取`ProductCatalog`項目的兩種變化。註解行 4a 後的版本會串流瀏覽每個頁面，並排序和記錄每個頁面上的項目。註解行 4b 後的版本會略過頁面反覆運算，並直接存取項目。
由於 和 兩個父介面[https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html](https://docs.oracle.com/javase/8/docs/api/java/lang/Iterable.html)，`PageIterable`介面提供多種處理結果的方法[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/pagination/sync/SdkIterable.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/pagination/sync/SdkIterable.html)。 `Iterable`帶來 `forEach`、 `iterator`和 `spliterator`方法， `SdkIterable`帶來 `stream`方法。
```
public static void scanSync(DynamoDbTable productCatalog) {
Map expressionValues = Map.of(
":min_value", numberValue(8.00),
":max_value", numberValue(80.00));
ScanEnhancedRequest request = ScanEnhancedRequest.builder()
.consistentRead(true)
// 1. the 'attributesToProject()' method allows you to specify which values you want returned.
.attributesToProject("id", "title", "authors", "price")
// 2. Filter expression limits the items returned that match the provided criteria.
.filterExpression(Expression.builder()
.expression("price >= :min_value AND price <= :max_value")
.expressionValues(expressionValues)
.build())
.build();
// 3. A PageIterable object is returned by the scan method.
PageIterable pagedResults = productCatalog.scan(request);
logger.info("page count: {}", pagedResults.stream().count());
// 4. Log the returned ProductCatalog items using two variations.
// 4a. This version sorts and logs the items of each page.
pagedResults.stream().forEach(p -> p.items().stream()
.sorted(Comparator.comparing(ProductCatalog::price))
.forEach(
item -> logger.info(item.toString())
));
// 4b. This version sorts and logs all items for all pages.
pagedResults.items().stream()
.sorted(Comparator.comparing(ProductCatalog::price))
.forEach(
item -> logger.info(item.toString())
);
}
```
### 使用非同步 API
非同步`scan`方法會將結果傳回為`PagePublisher`物件。`PagePublisher` 界面有兩種`subscribe`方法來處理回應頁面。一種`subscribe`方法來自`org.reactivestreams.Publisher`父界面。若要使用此第一個選項處理頁面，請將`[Subscriber](https://www.reactive-streams.org/reactive-streams-1.0.0-javadoc/org/reactivestreams/Subscriber.html)`執行個體傳遞至 `subscribe`方法。以下的第一個範例顯示 `subscribe`方法的使用方式。
第二個`subscribe`方法來自 [SdkPublisher](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/core/async/SdkPublisher.html) 界面。此版本的 `subscribe`接受 [https://docs.oracle.com/javase/8/docs/api/java/util/function/Consumer.html](https://docs.oracle.com/javase/8/docs/api/java/util/function/Consumer.html)而非 `Subscriber`。此`subscribe`方法變化會顯示在以下第二個範例中。
下列範例顯示使用上一個範例中所示相同篩選條件表達式的 `scan`方法的非同步版本。
在註解行 3 之後， `DynamoDbAsyncTable.scan` 會傳回`PagePublisher`物件。在下一行，程式碼會建立`org.reactivestreams.Subscriber`界面的執行個體 `ProductCatalogSubscriber`，其會在註解行 4 `PagePublisher`之後訂閱 。
`Subscriber` 物件會在`ProductCatalogSubscriber`類別範例中的註解行 8 之後，收集`onNext`方法中每個頁面`ProductCatalog`的項目。這些項目存放在私有`List`變數中，並使用 `ProductCatalogSubscriber.getSubscribedItems()`方法在呼叫程式碼中存取。這會在註解行 5 之後呼叫。
擷取清單之後，程式碼會依價格排序所有`ProductCatalog`項目，並記錄每個項目。
`ProductCatalogSubscriber` 類別中的 [CountDownLatch](https://docs.oracle.com/javase/7/docs/api/java/util/concurrent/CountDownLatch.html) 會封鎖呼叫執行緒，直到所有項目都新增至清單，然後在註解行 5 之後繼續。
```
public static void scanAsync(DynamoDbAsyncTable productCatalog) {
ScanEnhancedRequest request = ScanEnhancedRequest.builder()
.consistentRead(true)
.attributesToProject("id", "title", "authors", "price")
.filterExpression(Expression.builder()
// 1. :min_value and :max_value are placeholders for the values provided by the map
.expression("price >= :min_value AND price <= :max_value")
// 2. Two values are needed for the expression and each is supplied as a map entry.
.expressionValues(
Map.of( ":min_value", numberValue(8.00),
":max_value", numberValue(400_000.00)))
.build())
.build();
// 3. A PagePublisher object is returned by the scan method.
PagePublisher pagePublisher = productCatalog.scan(request);
ProductCatalogSubscriber subscriber = new ProductCatalogSubscriber();
// 4. Subscribe the ProductCatalogSubscriber to the PagePublisher.
pagePublisher.subscribe(subscriber);
// 5. Retrieve all collected ProductCatalog items accumulated by the subscriber.
subscriber.getSubscribedItems().stream()
.sorted(Comparator.comparing(ProductCatalog::price))
.forEach(item ->
logger.info(item.toString()));
// 6. Use a Consumer to work through each page.
pagePublisher.subscribe(page -> page
.items().stream()
.sorted(Comparator.comparing(ProductCatalog::price))
.forEach(item ->
logger.info(item.toString())))
.join(); // If needed, blocks the subscribe() method thread until it is finished processing.
// 7. Use a Consumer to work through each ProductCatalog item.
pagePublisher.items()
.subscribe(product -> logger.info(product.toString()))
.exceptionally(failure -> {
logger.error("ERROR - ", failure);
return null;
})
.join(); // If needed, blocks the subscribe() method thread until it is finished processing.
}
```
```
private static class ProductCatalogSubscriber implements Subscriber> {
private CountDownLatch latch = new CountDownLatch(1);
private Subscription subscription;
private List itemsFromAllPages = new ArrayList<>();
@Override
public void onSubscribe(Subscription sub) {
subscription = sub;
subscription.request(1L);
try {
latch.await(); // Called by main thread blocking it until latch is released.
} catch (InterruptedException e) {
throw new RuntimeException(e);
}
}
@Override
public void onNext(Page productCatalogPage) {
// 8. Collect all the ProductCatalog instances in the page, then ask the publisher for one more page.
itemsFromAllPages.addAll(productCatalogPage.items());
subscription.request(1L);
}
@Override
public void onError(Throwable throwable) {
}
@Override
public void onComplete() {
latch.countDown(); // Call by subscription thread; latch releases.
}
List getSubscribedItems() {
return this.itemsFromAllPages;
}
}
```
下列程式碼片段範例使用在註解行 6 `Consumer`之後接受 的 `PagePublisher.subscribe`方法版本。Java lambda 參數會使用頁面，進一步處理每個項目。在此範例中，會處理每個頁面，然後對每個頁面上的項目進行排序和記錄。
```
// 6. Use a Consumer to work through each page.
pagePublisher.subscribe(page -> page
.items().stream()
.sorted(Comparator.comparing(ProductCatalog::price))
.forEach(item ->
logger.info(item.toString())))
.join(); // If needed, blocks the subscribe() method thread until it is finished processing.
```
的 `items`方法會`PagePublisher`取消包裝模型執行個體，讓您的程式碼可以直接處理項目。此方法會顯示在下列程式碼片段中。
```
// 7. Use a Consumer to work through each ProductCatalog item.
pagePublisher.items()
.subscribe(product -> logger.info(product.toString()))
.exceptionally(failure -> {
logger.error("ERROR - ", failure);
return null;
})
.join(); // If needed, blocks the subscribe() method thread until it is finished processing.
```
## 查詢資料表
您可以使用 DynamoDB 增強型用戶端來查詢資料表，並擷取符合特定條件的多個項目。[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html#query(software.amazon.awssdk.enhanced.dynamodb.model.QueryEnhancedRequest)](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/DynamoDbTable.html#query(software.amazon.awssdk.enhanced.dynamodb.model.QueryEnhancedRequest)) 方法會根據主索引鍵值，使用資料類別上定義的 `@DynamoDbPartitionKey`和選用`@DynamoDbSortKey`註釋來尋找項目。
`query()` 方法需要分割區索引鍵值，並選擇性地接受排序索引鍵條件，以進一步精簡結果。如同 `scan` API，查詢會`PageIterable`針對同步呼叫傳回 ，`PagePublisher`針對非同步呼叫傳回 。
### `Query` 方法範例
以下`query()`的方法程式碼範例使用 `MovieActor`類別。資料類別會定義複合主索引鍵，該索引鍵由 **`movie`** 屬性做為分割區索引鍵，而**`actor`**屬性做為排序索引鍵。
#### `MovieActor` 類別
```
package org.example.tests.model;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbAttribute;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbBean;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbPartitionKey;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondaryPartitionKey;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSecondarySortKey;
import software.amazon.awssdk.enhanced.dynamodb.mapper.annotations.DynamoDbSortKey;
import java.util.Objects;
@DynamoDbBean
public class MovieActor implements Comparable {
private String movieName;
private String actorName;
private String actingAward;
private Integer actingYear;
private String actingSchoolName;
@DynamoDbPartitionKey
@DynamoDbAttribute("movie")
public String getMovieName() {
return movieName;
}
public void setMovieName(String movieName) {
this.movieName = movieName;
}
@DynamoDbSortKey
@DynamoDbAttribute("actor")
public String getActorName() {
return actorName;
}
public void setActorName(String actorName) {
this.actorName = actorName;
}
@DynamoDbSecondaryPartitionKey(indexNames = "acting_award_year")
@DynamoDbAttribute("actingaward")
public String getActingAward() {
return actingAward;
}
public void setActingAward(String actingAward) {
this.actingAward = actingAward;
}
@DynamoDbSecondarySortKey(indexNames = {"acting_award_year", "movie_year"})
@DynamoDbAttribute("actingyear")
public Integer getActingYear() {
return actingYear;
}
public void setActingYear(Integer actingYear) {
this.actingYear = actingYear;
}
@DynamoDbAttribute("actingschoolname")
public String getActingSchoolName() {
return actingSchoolName;
}
public void setActingSchoolName(String actingSchoolName) {
this.actingSchoolName = actingSchoolName;
}
@Override
public String toString() {
final StringBuffer sb = new StringBuffer("MovieActor{");
sb.append("movieName='").append(movieName).append('\'');
sb.append(", actorName='").append(actorName).append('\'');
sb.append(", actingAward='").append(actingAward).append('\'');
sb.append(", actingYear=").append(actingYear);
sb.append(", actingSchoolName='").append(actingSchoolName).append('\'');
sb.append('}');
return sb.toString();
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
MovieActor that = (MovieActor) o;
return Objects.equals(movieName, that.movieName) && Objects.equals(actorName, that.actorName) && Objects.equals(actingAward, that.actingAward) && Objects.equals(actingYear, that.actingYear) && Objects.equals(actingSchoolName, that.actingSchoolName);
}
@Override
public int hashCode() {
return Objects.hash(movieName, actorName, actingAward, actingYear, actingSchoolName);
}
@Override
public int compareTo(MovieActor o) {
if (this.movieName.compareTo(o.movieName) != 0){
return this.movieName.compareTo(o.movieName);
} else {
return this.actorName.compareTo(o.actorName);
}
}
}
```
針對下列項目查詢之後的程式碼範例。
#### `MovieActor` 資料表中的項目
```
MovieActor{movieName='movie01', actorName='actor0', actingAward='actingaward0', actingYear=2001, actingSchoolName='null'}
MovieActor{movieName='movie01', actorName='actor1', actingAward='actingaward1', actingYear=2001, actingSchoolName='actingschool1'}
MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2', actingYear=2001, actingSchoolName='actingschool2'}
MovieActor{movieName='movie01', actorName='actor3', actingAward='actingaward3', actingYear=2001, actingSchoolName='null'}
MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4', actingYear=2001, actingSchoolName='actingschool4'}
MovieActor{movieName='movie02', actorName='actor0', actingAward='actingaward0', actingYear=2002, actingSchoolName='null'}
MovieActor{movieName='movie02', actorName='actor1', actingAward='actingaward1', actingYear=2002, actingSchoolName='actingschool1'}
MovieActor{movieName='movie02', actorName='actor2', actingAward='actingaward2', actingYear=2002, actingSchoolName='actingschool2'}
MovieActor{movieName='movie02', actorName='actor3', actingAward='actingaward3', actingYear=2002, actingSchoolName='null'}
MovieActor{movieName='movie02', actorName='actor4', actingAward='actingaward4', actingYear=2002, actingSchoolName='actingschool4'}
MovieActor{movieName='movie03', actorName='actor0', actingAward='actingaward0', actingYear=2003, actingSchoolName='null'}
MovieActor{movieName='movie03', actorName='actor1', actingAward='actingaward1', actingYear=2003, actingSchoolName='actingschool1'}
MovieActor{movieName='movie03', actorName='actor2', actingAward='actingaward2', actingYear=2003, actingSchoolName='actingschool2'}
MovieActor{movieName='movie03', actorName='actor3', actingAward='actingaward3', actingYear=2003, actingSchoolName='null'}
MovieActor{movieName='movie03', actorName='actor4', actingAward='actingaward4', actingYear=2003, actingSchoolName='actingschool4'}
```
下列程式碼定義兩個`QueryConditional`執行個體： `keyEqual`（在註解行 1 之後） 和 `sortGreaterThanOrEqualTo`（在註解行 1a 之後）。
#### 依分割區索引鍵查詢項目
`keyEqual` 執行個體會比對分割區索引鍵值為 的項目**`movie01`**。
此範例也會在註解行 2 之後定義篩選條件表達式，以篩選掉任何沒有 **`actingschoolname`**值的項目。
`QueryEnhancedRequest` 結合了查詢的索引鍵條件和篩選條件表達式。
```
public static void query(DynamoDbTable movieActorTable) {
// 1. Define a QueryConditional instance to return items matching a partition value.
QueryConditional keyEqual = QueryConditional.keyEqualTo(b -> b.partitionValue("movie01"));
// 1a. Define a QueryConditional that adds a sort key criteria to the partition value criteria.
QueryConditional sortGreaterThanOrEqualTo = QueryConditional.sortGreaterThanOrEqualTo(b -> b.partitionValue("movie01").sortValue("actor2"));
// 2. Define a filter expression that filters out items whose attribute value is null.
final Expression filterOutNoActingschoolname = Expression.builder().expression("attribute_exists(actingschoolname)").build();
// 3. Build the query request.
QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()
.queryConditional(keyEqual)
.filterExpression(filterOutNoActingschoolname)
.build();
// 4. Perform the query using the "keyEqual" conditional and filter expression.
PageIterable pagedResults = movieActorTable.query(tableQuery);
logger.info("page count: {}", pagedResults.stream().count()); // Log number of pages.
pagedResults.items().stream()
.sorted()
.forEach(
item -> logger.info(item.toString()) // Log the sorted list of items.
);
```
**Example – 使用`keyEqual`查詢條件式輸出**
以下是執行 方法的輸出。輸出會顯示`movieName`值為 **movie01** 的項目，且不會顯示`actingSchoolName`等於 的項目**`null`**。
```
2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:46 - page count: 1
2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:51 - MovieActor{movieName='movie01', actorName='actor1', actingAward='actingaward1', actingYear=2001, actingSchoolName='actingschool1'}
2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:51 - MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2', actingYear=2001, actingSchoolName='actingschool2'}
2023-03-05 13:11:05 [main] INFO org.example.tests.QueryDemo:51 - MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4', actingYear=2001, actingSchoolName='actingschool4'}
```
#### 依分割區索引鍵和排序索引鍵查詢項目
透過為大於或等於 **actor2** 的值新增排序索引鍵條件， 會`sortGreaterThanOrEqualTo``QueryConditional`精簡分割區索引鍵比對 (**movie01**)。
開頭為 [`QueryConditional`的方法](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryConditional.html)`sort`需要分割區索引鍵值才能比對，並根據排序索引鍵值進行比較，進一步精簡查詢。在方法名稱`Sort`中， 並不表示結果會排序，但排序索引鍵值將用於比較。
在下列程式碼片段中，我們會變更先前在註解行 3 之後顯示的查詢請求。此程式碼片段會將「keyEqual」查詢條件取代為註解行 1a 之後定義的「sortGreaterThanOrEqualTo」查詢條件。下列程式碼也會移除篩選條件表達式。
```
QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()
.queryConditional(sortGreaterThanOrEqualTo).build();
```
**Example – 使用`sortGreaterThanOrEqualTo`查詢條件式輸出**
下列輸出會顯示查詢的結果。查詢會傳回`movieName`值等於 **movie01** 的項目，且只有`actorName`值大於或等於 **actor2** 的項目。由於我們移除篩選條件，查詢會傳回屬性沒有值的項目`actingSchoolName`。
```
2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:46 - page count: 1
2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:51 - MovieActor{movieName='movie01', actorName='actor2', actingAward='actingaward2', actingYear=2001, actingSchoolName='actingschool2'}
2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:51 - MovieActor{movieName='movie01', actorName='actor3', actingAward='actingaward3', actingYear=2001, actingSchoolName='null'}
2023-03-05 13:15:00 [main] INFO org.example.tests.QueryDemo:51 - MovieActor{movieName='movie01', actorName='actor4', actingAward='actingaward4', actingYear=2001, actingSchoolName='actingschool4'}
```