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

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

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

在 `UpdateItem` 操作中，舊版條件式參數 `AttributeUpdates` 包含要修改的屬性名稱、每個屬性上要執行的動作，以及每個屬性的新值。如果您要更新的屬性是資料表上任何索引的索引鍵屬性，則其類型必須符合資料表描述的 `AttributesDefinition` 中所定義的索引鍵類型。您可以使用 `UpdateItem` 來更新任何非索引鍵屬性。

屬性值不可為 Null。String 和 Binary 類型屬性的長度必須大於零。Set 類型屬性不能為空白。具有空白數值的請求會遭到拒絕，並出現 `ValidationException` 例外狀況。

每個 `AttributeUpdates` 元素包含要修改的屬性名稱，並具有下列資訊：
+  `Value`：此屬性的新值 (如適用)。
+  `Action`：用以指定如何執行更新的數值。此動作僅適用於資料類型為 Number 或 Set 的現有屬性。請勿對其他資料類型使用 `ADD`。

  如果在資料表中找到具有指定主索引鍵的項目，則下列各數值會執行以下動作：
  +  `PUT`：將指定屬性新增至項目。如果屬性已存在，則以新數值取代。
  +  `DELETE`：如果未指定 `DELETE` 的數值，則刪除屬性及其數值。指定數值的資料類型必須符合現有數值的資料類型。

    如果指定一組數值，則會從舊的集合中減去該等數值。例如，如果屬性值是集合 `[a,b,c]`，而且 `DELETE` 動作指定 `[a,c]`，則最後屬性值為 `[b]`。指定空集合是一項錯誤。
  +  `ADD`：如果屬性尚未存在，則將指定數值新增至項目。如果屬性已存在，則 `ADD` 的行為依屬性的資料類型而定：
    + 如果現有屬性是數字，而 `Value` 亦為數字，則 `Value` 會以數學方式新增至現有屬性。如果 `Value` 是負數，則會從現有屬性減去。
**注意**  
如果對更新前不存在的項目使用 `ADD` 增減數值，則 DynamoDB 會以 0 為初始數值。  
同樣地，如果對現有項目使用 `ADD` 增減更新前不存在的屬性值，則 DynamoDB 會以 `0` 為初始數值。例如，假設欲更新的項目不具有 *itemcount* 名稱的屬性，但您仍要將此屬性 `ADD` 數字 `3`。DynamoDB 會建立屬性 *itemcount*，將其初始數值設為 `0`，最後再加上 `3`。結果會得到數值為 `3` 的新 *itemcount* 屬性。
    + 如果現有的資料類型是集合，而 `Value` 亦為集合，則 `Value` 會附加至現有集合。例如，如果屬性值是集合 `[1,2]`，而且 `ADD` 動作指定 `[3]`，則最後屬性值為 `[1,2,3]`。如果已為集合屬性指定 `ADD` 動作，且指定的屬性類型與現有集合類型不符，則會發生錯誤。

      兩個集合必須具有相同的基本資料類型。例如，如果現有的資料類型是一組字串，`Value` 也必須是一組字串。

  如果未在資料表中找到具有指定索引鍵的項目，則下列各數值會執行以下動作：
  +  `PUT`：讓 DynamoDB 使用指定的主索引鍵建立新項目，然後新增屬性。
  +  `DELETE`：不進行任何動作，因為無法從不存在的項目中刪除屬性。成功完成操作，但 DynamoDB 不會建立新項目。
  +  `ADD`：讓 DynamoDB 使用為屬性值提供的主索引鍵和數字 (或一組數字) 建立項目。僅允許 Number 和 Number Set 資料類型。

如果提供屬於索引鍵一部分的任何屬性，則這些屬性的資料類型必須符合資料表屬性定義中結構描述的資料類型。

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

假設您想修改 *Music* 資料表中的一個項目。您可以搭配 `AttributeUpdates` 參數使用 `UpdateItem`請求，如本 AWS CLI 範例所示：

```
aws dynamodb update-item \
    --table-name Music \
    --key '{
        "SongTitle": {"S":"Call Me Today"}, 
        "Artist": {"S":"No One You Know"}
    }' \
    --attribute-updates '{
        "Genre": {
            "Action": "PUT", 
            "Value": {"S":"Rock"}
        }   
    }'
```

您可以改用 `UpdateExpression`。

```
aws dynamodb update-item \
    --table-name Music \
    --key '{
        "SongTitle": {"S":"Call Me Today"}, 
        "Artist": {"S":"No One You Know"}
    }' \
    --update-expression 'SET Genre = :g' \ 
    --expression-attribute-values '{
        ":g": {"S":"Rock"}
    }'
```