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

# 使用表達式和條件
<a name="ddb-en-client-expressions"></a>

DynamoDB 增強型用戶端 API 中的表達式是 [DynamoDB 表達式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.html)的 Java 表示法。

DynamoDB 增強型用戶端 API 使用三種類型的表達式：

[運算式](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/Expression.html)  
當您定義條件和篩選條件時，會使用 `Expression`類別。

[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryConditional.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryConditional.html)  
這種類型的表達式代表查詢操作的關鍵[條件](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.KeyConditionExpressions)。

[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/update/UpdateExpression.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/update/UpdateExpression.html)  
此類別可協助您撰寫 DynamoDB [更新表達式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)，且目前在更新項目時用於延伸架構。

## 表達式剖析
<a name="ddb-en-client-expressions-compoonents"></a>

表達式由下列項目組成：
+ 字串表達式 （必要）。字串包含 DynamoDB 邏輯表達式，其中包含屬性名稱和屬性值的預留位置名稱。
+ 表達式值的映射 （通常為必要）。
+ 表達式名稱的映射 （選用）。

使用建置器產生`Expression`採用下列一般形式的物件。

```
Expression expression = Expression.builder()
                            .expression({{<String>}})
                            .expressionNames({{<Map>}})
                            .expressionValues({{<Map>}})
                           .build()
```

`Expression`通常需要表達式值的映射。映射提供字串表達式中預留位置的值。映射金鑰包含前面加上冒號 (`:`) 的預留位置名稱，而映射值是 [AttributeValue](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/dynamodb/model/AttributeValue.html) 的執行個體。[AttributeValues](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/internal/AttributeValues.html) 類別具有從常值產生`AttributeValue`執行個體的便利方法。或者，您可以使用 `AttributeValue.Builder`來產生`AttributeValue`執行個體。

下列程式碼片段顯示註解行 2 之後有兩個項目的映射。傳遞至 `expression()`方法的字串，顯示於註解行 1 之後，包含 DynamoDB 在執行操作之前解析的預留位置。此程式碼片段不包含表達式名稱的映射，因為*價格*是允許的屬性名稱。

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

如果 DynamoDB 資料表中的屬性名稱是保留字、以數字開頭或包含空格，則 需要表達式名稱的映射`Expression`。

例如，如果屬性名稱`1price`不是`price`在先前的程式碼範例中，則需要修改範例，如下列範例所示。

```
        ScanEnhancedRequest request = ScanEnhancedRequest.builder()
                .filterExpression(Expression.builder()
                        .expression("#price >= :min_value AND #price <= :max_value")
                        .expressionNames( Map.of("#price", "1price") )
                        .expressionValues(
                                Map.of(":min_value", numberValue(8.00),
                                        ":max_value", numberValue(400_000.00)))
                        .build())
                .build();
```

表達式名稱的預留位置以井號 () 開頭`#`。表達式名稱映射的項目會使用預留位置做為索引鍵，並使用屬性名稱做為值。映射會使用 `expressionNames()`方法新增至表達式建置器。DynamoDB 會在執行操作之前解析屬性名稱。

如果在字串表達式中使用函數，則不需要表達式值。表達式函數的範例為 `attribute_exists({{<attribute_name>}})`。

下列範例會建置`Expression`使用 [DynamoDB 函數](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.OperatorsAndFunctions.html#Expressions.OperatorsAndFunctions.Functions)的 。此範例中的表達式字串不使用任何預留位置。此表達式可用於 `putItem`操作，以檢查資料庫中是否存在屬性`movie`值等於資料物件`movie`屬性的項目。

```
Expression exp = Expression.builder().expression("attribute_not_exists (movie)").build();
```

DynamoDB 開發人員指南包含與 DynamoDB 搭配使用的[低階表達式](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.html)的完整資訊。

## 條件表達式和條件式
<a name="ddb-en-client-expressions-cond"></a>

當您使用 `putItem()`、 `updateItem()`和 `deleteItem()`方法，以及使用交易和批次操作時，您可以使用 `[Expression](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/Expression.html)` 物件來指定 DynamoDB 必須滿足的條件，才能繼續操作。這些表達式會命名為條件表達式。如需範例，請參閱本指南中所示[交易範例](ddb-en-client-use-multiop-trans.md#ddb-en-client-use-multiop-trans-writeitems-opcondition)的 `addDeleteItem()`方法 （註解行 1 之後） 中使用的條件表達式。

當您使用 `query()` 方法時，條件會以 表示[https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryConditional.html](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/model/QueryConditional.html)。`QueryConditional` 類別有數種靜態便利方法，可協助您撰寫判斷要從 DynamoDB 讀取哪些項目的條件。

如需 的範例`QueryConditionals`，請參閱本指南 [`Query` 方法範例](ddb-en-client-use-multirecord.md#ddb-en-client-use-multirecord-query-example)一節的第一個程式碼範例。

## 篩選條件表達式
<a name="ddb-en-client-expressions-filter"></a>

篩選條件表達式用於掃描和查詢操作，以篩選傳回的項目。

從資料庫讀取所有資料後，就會套用篩選條件表達式，因此讀取成本與沒有篩選條件相同。*Amazon DynamoDB 開發人員指南*提供有關使用篩選條件表達式進行[查詢](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Query.html#Query.FilterExpression)和[掃描](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Scan.html#Scan.FilterExpression)操作的詳細資訊。

下列範例顯示新增至掃描請求的篩選條件表達式。條件會將傳回的項目限制為價格介於 8.00 到 80.00 之間的項目。

```
        Map<String, AttributeValue> 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();
```

## 更新表達式
<a name="ddb-en-client-expressions-update"></a>

DynamoDB 增強型用戶端的 `updateItem()` 方法提供標準方法來更新 DynamoDB 中的項目。不過，當您需要更多功能時，[UpdateExpressions](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/update/UpdateExpression.html) 會提供 DynamoDB [更新表達式語法的安全類型表示法。](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)例如，您可以使用 `UpdateExpressions` 來增加值，而無需先從 DynamoDB 讀取項目，或將個別成員新增至清單。更新表達式目前可在 `updateItem()`方法的自訂擴充功能中使用。

如需使用更新表達式的範例，請參閱本指南中的[自訂延伸模組範例](ddb-en-client-extensions-custom.md)。

如需更新表達式的詳細資訊，請參閱《[Amazon DynamoDB 開發人員指南](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.UpdateExpressions.html)》。