Expected (舊版)

注意

我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱在 DynamoDB 中使用表達式。如需取代此參數之新參數的特定資訊，請參閱 ConditionExpression代替使用。。

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

如果在 Expected 映射中指定一個以上元素，所有條件必須根據預設評估為 true。換句話說，使用AND運算符組合條件。(您可以改用 ConditionalOperator 參數將條件以 OR 連在一起。若要如此，則至少其中一個條件必須評估為 true，而不是全部都必須評估為 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 的資料類型為 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清CONTAINS單支援 _：評估 "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代替使用-示例

假設您想只在某一條件為 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"}
    }'