本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用舊式參數撰寫條件 **注意** 我們建議您盡可能使用新的表達式參數，而不要使用舊版參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。 下節說明如何撰寫搭配舊式參數 (例如 `Expected`、`QueryFilter`、`ScanFilter`) 使用的條件。 **注意** 新的應用程式應改用表達式參數。如需詳細資訊，請參閱[在 DynamoDB 中使用表達式](Expressions.md)。 ## 簡單條件 使用屬性值，您可以撰寫條件來與資料表屬性進行比較。條件一律評估為 true 或 false，並且包含下列各項： + `ComparisonOperator`：大於、小於、等於等。 + `AttributeValueList` (選用)：要比較的屬性值。依使用中的 `ComparisonOperator` 而定，`AttributeValueList` 可能包含一兩個或更多數值，或者根本不存在。 下列各節說明各種比較運算子，並附有這些運算子在條件中的用法範例。 ### 不具屬性值的比較運算子 + `NOT_NULL`：如果屬性存在，則本項為 true。 + `NULL`：如果屬性不存在，則本項為 true。 使用這些運算子來檢查屬性存在與否。因為並無可比較的數值，所以不要指定 `AttributeValueList`。 **範例** 如果 *Dimensions* 屬性存在，則下列表達式評估為 true。 ``` ... "Dimensions": { ComparisonOperator: "NOT_NULL" } ... ``` ### 具有一個屬性值的比較運算子 + `EQ`：如果某屬性等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。例如，字串 `"3"` 不等於數字 `3`。此外，數字 `3` 不等於數字集合 `[3, 2, 1]`。 + `NE`：如果某屬性不等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number、Binary、String Set、Number Set 或 Binary Set 類型的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `LE`：如果某屬性小於或等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的 `AttributeValue` 所屬類型與請求中指定的類型不同，則數值不相符。 + `LT`：如果某屬性小於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `GE`：如果某屬性大於或等於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `GT`：如果某屬性大於某數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 + `CONTAINS`：如果某數值在集合內，或者某數值包含另一個數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果比較的目標屬性是 String，則運算子會檢查相符子字串。如果比較的目標屬性是 Binary，則運算子會尋找與輸入相符的目標子序列。比較的目標屬性為集合時，如果找到與該集合任一成員完全相符的項目，則運算子評估為 true。 + `NOT_CONTAINS`：如果某數值*不在*集合內，或者某數值不包含另一個數值，則本項為 true。 `AttributeValueList` 僅可包含 String、Number 或 Binary 類型 (非集合) 的一個數值。如果比較的目標屬性是 String，則運算子會檢查相符子字串是否不存在。如果比較的目標屬性是 Binary，則運算子會檢查與輸入相符的目標子序列是否不存在。比較的目標屬性為集合時，如果*未*找到與該集合任一成員完全相符的項目，則運算子評估為 true。 + `BEGINS_WITH`：如果屬性前幾個字元與提供的數值相符，則本項為 true。請勿使用此運算子來比較數字。 `AttributeValueList` 僅可包含 String 或 Binary 類型 (非 Number 或集合) 的一個數值。比較的目標屬性必須是 String 或 Binary (非 Number 或集合)。 使用這些運算子來比較屬性與數值。您必須指定包含單一數值的 `AttributeValueList`。大多數的運算子要求此數值必須為一個純量，不過 `EQ` 和 `NE` 運算子也支援集合。 **範例** 下列各表達式會評估為 true： + 產品價格大於 100。 ``` ... "Price": { ComparisonOperator: "GT", AttributeValueList: [ {"N":"100"} ] } ... ``` + 產品類別以 Bo 開頭。 ``` ... "ProductCategory": { ComparisonOperator: "BEGINS_WITH", AttributeValueList: [ {"S":"Bo"} ] } ... ``` + 產品有紅色、綠色或黑色款式： ``` ... "Color": { ComparisonOperator: "EQ", AttributeValueList: [ [ {"S":"Black"}, {"S":"Red"}, {"S":"Green"} ] ] } ... ``` **注意** 比較集合資料類型時，元素的順序無關緊要。無論在請求中指定何順序，DynamoDB 只會傳回具有相同一組數值的項目。 ### 具有兩個屬性值的比較運算子 + `BETWEEN`：如果某數值介於下限和上限之間 (含端點在內)，則本項為 true。 `AttributeValueList` 必須包含 String、Number 或 Binary 類型 (非集合) 的兩個元素。如果目標數值大於或等於第一個元素，並且小於或等於第二個元素，則目標屬性相符。如果項目內含的數值所屬類型與請求中指定的類型不同，則數值不相符。 使用此運算子判定屬性值是否在某範圍內。`AttributeValueList` 必須包含同為 String、Number 或 Binary 類型的兩個純量元素。 **範例** 如果產品價格介於 100 和 200 之間，則下列表達式評估為 true。 ``` ... "Price": { ComparisonOperator: "BETWEEN", AttributeValueList: [ {"N":"100"}, {"N":"200"} ] } ... ``` ### 具有 *N* 屬性值的比較運算子 + `IN`：如果某數值等於列舉清單中任何數值，則本項為 true。清單中僅支援純量值，不支援集合。目標屬性必須為相同的類型和確切數值才相符。 `AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合) 的一或多個元素。這些屬性會與項目的現有非集合類型屬性進行比較。如果輸入集合的*任何*元素存在於項目屬性中，則表達式評估為 true。 `AttributeValueList` 可以包含 String、Number 或 Binary 類型 (非集合) 的一或多個數值。比較的目標屬性必須為相同的類型和確切數值才相符。String 一律不與 String 集合相符。 使用此運算子判定提供的數值是否在列舉清單內。您可以在 `AttributeValueList` 中指定任意數量的純量值，但所有純量值必須屬於同一資料類型。 **範例** 如果 *Id* 的數值為 201、203 或 205，則下列表達式評估為 true。 ``` ... "Id": { ComparisonOperator: "IN", AttributeValueList: [ {"N":"201"}, {"N":"203"}, {"N":"205"} ] } ... ``` ## 使用多個條件 DynamoDB 可讓您將多個條件結合成複雜的表達式。您可以提供至少兩個表達式來執行此操作，另可選用 [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md)。 根據預設，指定一個以上條件時，*所有*條件必須評估為 true，以便整個表達式評估為 true。換言之，會執行隱含的 *AND* 操作。 **範例** 如果產品為一本至少有 600 頁的書，則下列表達式評估為 true。這兩個條件皆須評估為 true，因為兩者隱含地以 *AND* 連在一起。 ``` ... "ProductCategory": { ComparisonOperator: "EQ", AttributeValueList: [ {"S":"Book"} ] }, "PageCount": { ComparisonOperator: "GE", AttributeValueList: [ {"N":600"} ] } ... ``` 可以使用 [ConditionalOperator (舊版)](LegacyConditionalParameters.ConditionalOperator.md) 來清楚表示會執行一個 *AND* 操作。下列範例與前一範例的表現方式相同。 ``` ... "ConditionalOperator" : "AND", "ProductCategory": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"N":"Book"} ] }, "PageCount": { "ComparisonOperator": "GE", "AttributeValueList": [ {"N":600"} ] } ... ``` 您也可以將 `ConditionalOperator` 設定為 *OR*，這表示其中*至少一個*條件必須評估為 true。 **範例** 如果產品為一台登山單車、屬於特定品牌，或者其價格大於 100，則下列表達式評估為 true。 ``` ... ConditionalOperator : "OR", "BicycleType": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S":"Mountain" ] }, "Brand": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"S":"Brand-Company A" ] }, "Price": { "ComparisonOperator": "GT", "AttributeValueList": [ {"N":"100"} ] } ... ``` **注意** 在複雜的表達式中，會按第一到最後一個條件的順序依序處理條件。 無法在單一表達式中同時使用 AND 和 OR。 ## 其他條件式運算子 在舊版 DynamoDB 當中，`Expected` 參數在條件式寫入方面有不同的表現方式。`Expected` 映射中的每個項目顯示 DynamoDB 要檢查的屬性名稱，並具有下列資訊： + `Value`：要與屬性比較的值。 + `Exists`：判定在嘗試操作之前是否已有此數值。 DynamoDB 持續支援 `Value` 和 `Exists` 選項；不過，這些選項僅能測試相等條件，或者是否存在某屬性。建議您改用 `ComparisonOperator` 和 `AttributeValueList`，因為這些選項可讓您建構更廣泛的條件。 **Example** `DeleteItem` 可以查看書籍是否已絕版，並且只在此條件為 true 時才刪除書籍。以下為使用舊式條件的 AWS CLI 範例： ``` aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{ "Id": {"N":"600"} }' \ --expected '{ "InPublication": { "Exists": true, "Value": {"BOOL":false} } }' ``` 以下範例顯示相同項目，但不使用舊式條件： ``` aws dynamodb delete-item \ --table-name ProductCatalog \ --key '{ "Id": {"N":"600"} }' \ --expected '{ "InPublication": { "ComparisonOperator": "EQ", "AttributeValueList": [ {"BOOL":false} ] } }' ``` **Example** `PutItem` 操作可防止覆寫已有相同主索引鍵屬性的現有項目。以下為使用舊式條件的範例： ``` aws dynamodb put-item \ --table-name ProductCatalog \ --item '{ "Id": {"N":"500"}, "Title": {"S":"Book 500 Title"} }' \ --expected '{ "Id": { "Exists": false } }' ``` 以下範例顯示相同項目，但不使用舊式條件： ``` aws dynamodb put-item \ --table-name ProductCatalog \ --item '{ "Id": {"N":"500"}, "Title": {"S":"Book 500 Title"} }' \ --expected '{ "Id": { "ComparisonOperator": "NULL" } }' ``` **注意** 針對 `Expected` 映射中的條件，請勿搭配 `ComparisonOperator` 和 `AttributeValueList` 使用舊式的 `Value` 和 `Exists` 選項。若採取此法，條件式寫入將會失敗。