本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# DynamoDB 條件表達式 CLI 範例
以下是使用條件表達式的一些 AWS Command Line Interface (AWS CLI) 範例。這些範例是以 [在 DynamoDB 中使用表達式時參考項目屬性](Expressions.Attributes.md) 中引進的 `ProductCatalog` 資料表為基礎。此資料表的分割區索引鍵是 `Id`；沒有排序索引鍵。以下 `PutItem` 操作會建立將在範例中參考的範例 `ProductCatalog` 項目。
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json
```
`--item` 的引數會存放在 `item.json` 檔案中。(為求簡化，只會使用一些項目屬性)。
```
{
"Id": {"N": "456" },
"ProductCategory": {"S": "Sporting Goods" },
"Price": {"N": "650" }
}
```
**Topics**
+ [條件式放置](#Expressions.ConditionExpressions.PreventingOverwrites)
+ [條件式刪除](#Expressions.ConditionExpressions.AdvancedComparisons)
+ [條件式更新](#Expressions.ConditionExpressions.SimpleComparisons)
+ [條件式表達式範例](#Expressions.ConditionExpressions.ConditionalExamples)
## 條件式放置
`PutItem` 操作將會覆寫具有相同主索引鍵 (如有) 的項目。若您想要避免這種情況，請使用條件表達式。只有在相關項目還沒有相同的主索引鍵時，才會允許繼續寫入。
下列範例會在嘗試寫入操作之前，使用 `attribute_not_exists()` 檢查資料表中是否存在主索引鍵。
**注意**
如果您的主索引鍵同時包含分割區索引鍵 (pk) 和排序索引鍵 (sk)，則在嘗試寫入操作之前，參數會檢查 `attribute_not_exists(pk)` AND `attribute_not_exists(sk)` 作為完整陳述式評估為 true 或 false。
```
aws dynamodb put-item \
--table-name ProductCatalog \
--item file://item.json \
--condition-expression "attribute_not_exists(Id)"
```
如果條件表達式評估為 false，則 DynamoDB 會傳回以下錯誤訊息：The conditional request failed (條件式請求失敗)。
**注意**
如需 `attribute_not_exists` 和其他函數的詳細資訊，請參閱 [DynamoDB 中的條件表達式、篩選條件表達式、運算子和函數。](Expressions.OperatorsAndFunctions.md)。
## 條件式刪除
若要執行條件式刪除，您可以搭配使用 `DeleteItem` 操作與條件表達式。條件表達式必須評估為 true，操作才會成功；否則，操作會失敗。
考慮以上定義的項目。
假設您想要刪除項目，但只限在下列條件下：
+ `ProductCategory` 是 "Sporting Goods" 或 "Gardening Supplies"。
+ `Price` 介於 500 與 600 之間。
以下範例會嘗試刪除項目。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id":{"N":"456"}}' \
--condition-expression "(ProductCategory IN (:cat1, :cat2)) and (Price between :lo and :hi)" \
--expression-attribute-values file://values.json
```
`--expression-attribute-values` 的引數會存放在 `values.json` 檔案中。
```
{
":cat1": {"S": "Sporting Goods"},
":cat2": {"S": "Gardening Supplies"},
":lo": {"N": "500"},
":hi": {"N": "600"}
}
```
**注意**
在條件表達式中，`:` (冒號字元) 表示*表達式屬性值* (即實際值的預留位置)。如需詳細資訊，請參閱 [在 DynamoDB 中使用表達式屬性值](Expressions.ExpressionAttributeValues.md)。
如需 `IN`、`AND` 和其他關鍵字的詳細資訊，請參閱 [DynamoDB 中的條件表達式、篩選條件表達式、運算子和函數。](Expressions.OperatorsAndFunctions.md)。
在此範例中，`ProductCategory` 比較會評估為 true，但 `Price` 比較會評估為 false。這會導致條件表達式評估為 false，使 `DeleteItem` 操作失敗。
## 條件式更新
若要執行條件式更新，您可以搭配使用 `UpdateItem` 操作與條件表達式。條件表達式必須評估為 true，操作才會成功；否則，操作會失敗。
**注意**
`UpdateItem` 也支援*更新表達式*；其中，您可以指定想要對項目進行的修改。如需詳細資訊，請參閱[在 DynamoDB 中使用更新表達式](Expressions.UpdateExpressions.md)。
假設您已開始使用以上定義的項目。
以下範例會執行 `UpdateItem` 操作。其試圖將產品的 `Price` 減少 75，但如果目前的 `Price` 小於或等於 500，條件表達式會阻止更新。
```
aws dynamodb update-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--update-expression "SET Price = Price - :discount" \
--condition-expression "Price > :limit" \
--expression-attribute-values file://values.json
```
`--expression-attribute-values` 的引數會存放在 `values.json` 檔案中。
```
{
":discount": { "N": "75"},
":limit": {"N": "500"}
}
```
如果起始 `Price` 是 650，則 `UpdateItem` 操作會將 `Price` 減少為 575。如果您再次執行 `UpdateItem` 操作，則 `Price` 會減少為 500。如果您執行它第三次，則條件表達式會評估為 false，而更新會失敗。
**注意**
在條件表達式中，`:` (冒號字元) 表示*表達式屬性值* (即實際值的預留位置)。如需詳細資訊，請參閱 [在 DynamoDB 中使用表達式屬性值](Expressions.ExpressionAttributeValues.md)。
如需 "*>*" 和其他運算子的詳細資訊，請參閱 [DynamoDB 中的條件表達式、篩選條件表達式、運算子和函數。](Expressions.OperatorsAndFunctions.md)。
## 條件式表達式範例
如需下列範例中所用函數的詳細資訊，請參閱 [DynamoDB 中的條件表達式、篩選條件表達式、運算子和函數。](Expressions.OperatorsAndFunctions.md)。若要進一步了解如何指定表達式中的不同屬性類型，請參閱 [在 DynamoDB 中使用表達式時參考項目屬性](Expressions.Attributes.md)。
### 檢查項目中的屬性
您可以檢查任何屬性是否存在。如果條件表達式評估為 true，則操作會成功；否則，操作會失敗。
只有在產品沒有 `Price` 屬性時，以下範例才會使用 `attribute_not_exists` 來刪除產品。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_not_exists(Price)"
```
DynamoDB 也提供 `attribute_exists` 函數。只有在產品收到不佳的檢閱時，以下範例才會刪除產品。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_exists(ProductReviews.OneStar)"
```
### 檢查屬性類型
您可以使用 `attribute_type` 函數，以檢查屬性值的資料類型。如果條件表達式評估為 true，則操作會成功；否則，操作會失敗。
下列範例只有在具有字串集合類型的 `Color` 屬性的情況下，才會使用 `attribute_type` 刪除產品。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "attribute_type(Color, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
`--expression-attribute-values` 的引數會存放在 expression-attribute-values.json 檔案中。
```
{
":v_sub":{"S":"SS"}
}
```
### 檢查字串起始值
您可以使用 `begins_with` 函數，來檢查字串屬性值是否以特定子字串做為開頭。如果條件表達式評估為 true，則操作會成功；否則，操作會失敗。
只有在 `begins_with` 映射的 `FrontView` 元素以特定值作為開頭時，下列範例才會使用 `Pictures` 刪除產品。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "begins_with(Pictures.FrontView, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
`--expression-attribute-values` 的引數會存放在 expression-attribute-values.json 檔案中。
```
{
":v_sub":{"S":"http://"}
}
```
### 檢查集合中的元素
您可以使用 `contains` 函數，檢查集合中的元素或尋找字串內的子字串。如果條件表達式評估為 true，則操作會成功；否則，操作會失敗。
只有在 `Color` 字串集合具有含特定值的元素時，下列範例才會使用 `contains` 刪除產品。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "contains(Color, :v_sub)" \
--expression-attribute-values file://expression-attribute-values.json
```
`--expression-attribute-values` 的引數會存放在 expression-attribute-values.json 檔案中。
```
{
":v_sub":{"S":"Red"}
}
```
### 檢查屬性值的大小
您可以使用 `size` 函數，來檢查屬性值的大小。如果條件表達式評估為 true，則操作會成功；否則，操作會失敗。
只有在 `VideoClip` 二進制屬性大於 `64000` 位元組時，下列範例才會使用 `size` 刪除產品。
```
aws dynamodb delete-item \
--table-name ProductCatalog \
--key '{"Id": {"N": "456"}}' \
--condition-expression "size(VideoClip) > :v_sub" \
--expression-attribute-values file://expression-attribute-values.json
```
`--expression-attribute-values` 的引數會存放在 expression-attribute-values.json 檔案中。
```
{
":v_sub":{"N":"64000"}
}
```