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

# Expected (舊版)
<a name="LegacyConditionalParameters.Expected"></a>

**注意**  
我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。如需取代此參數之新參數的特定資訊，請參閱 [改用 *ConditionExpression*。](#Expected.instead)。

舊版條件式參數 `Expected` 是 `UpdateItem` 操作的條件式區塊。`Expected` 是屬性/條件對的映射。映射的每個元素都包含一個屬性名稱、一個比較運算子，以及一或多個數值。DynamoDB 會使用比較運算子來比較屬性與您提供的數值。對於每個 `Expected` 元素，評估結果皆為 true 或 false。

如果在 `Expected` 映射中指定一個以上元素，所有條件必須根據預設評估為 true。換句話說，條件是使用 `AND` 運算子的組合。(您可以改用 `ConditionalOperator` 參數將條件以 OR 連在一起。若要如此，則至少其中一個條件必須評估為 true，而不是全部都必須評估為 true。)

如果 `Expected` 映射評估為 true，則條件式操作會成功，反之則會失敗。

 `Expected` 包含下列各項：
+  `AttributeValueList`：針對所提供的屬性進行評估的一或多個數值。清單中值的數目依使用的 `ComparisonOperator` 而定。

  Number 類型的數值比較為數字。

  大於、等於或小於的 String 數值比較是根據 UTF-8 二進位編碼的 Unicode。例如，`a` 大於 `A`，`a` 大於 `B`。

  針對 Binary 類型，每當 DynamoDB 比較二進位值時，都會將二進位資料的每個位元組視為不帶正負號。
+  `ComparisonOperator`：用於評估 `AttributeValueList` 中屬性的比較程式。執行比較時，DynamoDB 會使用高度一致性讀取。

  可以使用下列比較運算子：

   `EQ | NE | LE | LT | GE | GT | NOT_NULL | NULL | CONTAINS | NOT_CONTAINS | BEGINS_WITH | IN | BETWEEN` 

  以下是每個比較運算子的描述。
  +  `EQ`：等於。所有資料類型都支援 `EQ`，包括清單和映射。

     `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。
  +  `NE`：不等於。所有資料類型都支援 `NE`，包括清單和映射。

     `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 與所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不等於 `{"NS":["6", "2", "1"]}`。
  +  `LE`：小於或等於。

     `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。
  +  `LT`：小於。

     `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue`。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。
  +  `GE`：大於或等於。

     `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。
  +  `GT`：大於。

     `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不等於 `{"N":"6"}`。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。
  +  `NOT_NULL`：屬性存在。所有資料類型都支援 `NOT_NULL`，包括清單和映射。
**注意**  
此運算子會測試屬性是否存在，而不是其資料類型。如果屬性 `a` 的資料類型為 Null，並且是以 `NOT_NULL` 評估，則結果為布林值 `true`。此結果是因為屬性 `a` 存在；其資料類型與 `NOT_NULL` 比較運算子無關。
  +  `NULL`：屬性不存在。所有資料類型都支援 `NULL`，包括清單和映射。
**注意**  
此運算子會測試屬性是否不存在，而不是其資料類型。如果屬性 `a` 的資料類型為 Null，並且是以 `NULL` 評估，則結果為布林值 `false`。這是因為屬性 `a` 存在；其資料類型與 `NULL` 比較運算子無關。
  +  `CONTAINS`：檢查子序列，或是集合中的數值。

     `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果比較的目標屬性是 String 類型，則運算子會檢查相符子字串。如果比較的目標屬性是 Binary 類型，則運算子會尋找與輸入相符的目標子序列。比較的目標屬性為集合 (`SS`、`NS` 或 `BS`) 時，如果找到與該集合任一成員完全相符的項目，則運算子評估為 true。

    清單支援 CONTAINS：當評估 `a CONTAINS b` 時，`a` 可以是清單，但 `b` 不可以是集合、映射或清單。
  +  `NOT_CONTAINS`：檢查子序列是否不存在，或者集合中的數值是否不存在。

     `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合類型) 的一個 `AttributeValue` 元素。如果比較的目標屬性是 String，則運算子會檢查相符子字串是否不存在。如果比較的目標屬性是 Binary，則運算子會檢查與輸入相符的目標子序列是否不存在。比較的目標屬性為集合 (`SS`、`NS` 或 `BS`) 時，如果 `does not` 找到與該集合任一成員完全相符的項目，則運算子評估為 true。

    清單支援 NOT\$1CONTAINS：當評估 `a NOT CONTAINS b` 時，`a` 可以是清單，但 `b` 不可以是集合、映射或清單。
  +  `BEGINS_WITH`：檢查字首。

     `AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合類型) 的一個 `AttributeValue`。比較的目標屬性必須是 String 或 Binary 類型 (非 Number 或集合類型)。
  +  `IN`：檢查兩個集合內相符的元素。

     `AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合類型) 的一或多個 `AttributeValue` 元素。這些屬性會與項目的現有集合類型屬性進行比較。如果輸入集合的任何元素存在於項目屬性中，則表達式評估為 true。
  +  `BETWEEN`：大於或等於第一個數值，並且小於或等於第二個數值。

     `AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合類型) 的兩個 `AttributeValue` 元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的 `AttributeValue` 元素所屬類型與請求中提供的類型不同，則數值不相符。例如，`{"S":"6"}` 不與 `{"N":"6"}` 比較。另外，`{"N":"6"}` 不與 `{"NS":["6", "2", "1"]}` 比較。

下列參數可用來取代 `AttributeValueList` 和 `ComparisonOperator`：
+  `Value`：DynamoDB 用來與屬性進行比較的數值。
+  `Exists`：此為布林值，可讓 DynamoDB 在嘗試條件式操作之前評估數值：
  + 如果 `Exists` 為 `true`，則 DynamoDB 會查看該屬性值是否已存在於資料表中。如果找到該數值，則條件評估為 true，否則條件評估為 false。
  + 如果 `Exists` 為 `false`，則 DynamoDB 會假設屬性值 `not` 存在於資料表中。如果該數值實際上不存在，則假設有效，條件會評估為 true。如果找到該值，則即使假設該值不存在，條件仍會評估為 false。

  請注意，`Exists` 預設值為 `true`。

`Value` 和 `Exists` 參數與 `AttributeValueList` 和 `ComparisonOperator` 不相容。請注意，如果同時使用此兩組參數，DynamoDB 會傳回 `ValidationException` 例外狀況。

**注意**  
此參數不支援 List 或 Map 類型的屬性。

## 改用 *ConditionExpression* - 範例
<a name="Expected.instead"></a>

假設您想只在某一條件為 true 的情況下修改 *Music* 資料表中的一個項目。您可以搭配 `Expected` 參數使用 `UpdateItem`請求，如本 AWS CLI 範例所示：

```
aws dynamodb update-item \
    --table-name Music \
    --key '{
        "Artist": {"S":"No One You Know"},
        "SongTitle": {"S":"Call Me Today"} 
    }' \
    --attribute-updates '{
        "Price": {
            "Action": "PUT", 
            "Value": {"N":"1.98"}
        }
    }' \
    --expected '{
        "Price": {
            "ComparisonOperator": "LE", 
            "AttributeValueList": [ {"N":"2.00"} ]
        }
    }'
```

您可以改用 `ConditionExpression`。

```
aws dynamodb update-item \
    --table-name Music \
    --key '{
        "Artist": {"S":"No One You Know"},
        "SongTitle": {"S":"Call Me Today"} 
    }' \
    --update-expression 'SET Price = :p1' \
    --condition-expression 'Price <= :p2' \
    --expression-attribute-values '{
        ":p1": {"N":"1.98"},
        ":p2": {"N":"2.00"}
    }'
```