# 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，而不是所有条件都必须。）

如果 `Expected` 映射的计算结果为 true，则操作成功；否则操作失败。

 `Expected` 包含以下内容：
+  `AttributeValueList` - 对提供的属性计算的一个或多个值。列表中的值取决于使用的 `ComparisonOperator`。

  对于 Number 类型，值比较为数字。

  大于、等于或小于的字符串值比较基于 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`”的数据类型为空，并且使用 `NOT_NULL` 计算，则结果是一个布尔值 `true`。这是因为属性“`a`”存在；其数据类型与 `NOT_NULL` 比较运算符无关。
  +  `NULL`：属性不存在。`NULL` 支持所有数据类型，包括列表和映射。
**注意**  
此运算符测试属性不存在，而不是其数据类型。如果属性 "`a`" 的数据类型为空，并且使用 `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` 必须包含两个相同类型的 `AttributeValue` 元素，可以是 String、Number 或 Binary（不是集合类型）。如果目标值大于等于第一个元素，小于等于第二个元素，则目标属性匹配。如果项目包含的 `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* 表的项目。可以使用 `UpdateItem` 请求和 `Expected` 参数，如这个 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"}
    }'
```