Importante
Esta seção refere-se à versão de API 2011-12-05, que está obsoleta e não deve ser usada para novos aplicativos.
Para obter a documentação da API de baixo nível atual, consulte a Referência da API do Amazon DynamoDB.
Descrição
Edita os atributos de um item existente. Você pode executar uma atualização condicional (insira um novo par de nome-valor de atributo se ele não existir, ou substitua um par de nome-valor existente se ele tiver determinados valores de atributos esperados).
nota
Não é possível atualizar os atributos da chave primária usando UpdateItem. Em vez disso, exclua o item e use PutItem para criar um novo item com novos atributos.
A operação UpdateItem inclui um parâmetro Action
que define como executar a atualização. Você pode inserir, excluir ou adicionar valores de atributo.
Os valores de atributo não podem ser nulos; os atributos do tipo string e binário devem ter tamanhos maiores que zero; e os atributos do tipo conjunto não devem estar vazios. As solicitações com valores vazios serão rejeitadas com ValidationException
.
Se um item existente tiver a chave primária especificada:
PUT: adiciona o atributo especificado. Se o atributo existir, ele será substituído pelo novo valor.
DELETE: se nenhum valor for especificado, o atributo e seu valor serão removidos. Se um conjunto de valores for especificado, os valores no conjunto especificado serão removidos do conjunto antigo. Portanto, se o valor do atributo incluir [a, b, c] e a ação de exclusão incluir [a, c], o valor do atributo final será [b]. O tipo de valor especificado deve corresponder ao tipo de valor existente. Não é válido especificar um conjunto vazio.
ADD: use a ação de adicionar apenas para números ou se o atributo de destino for um conjunto (incluindo conjuntos de strings). ADD não funcionará se o atributo de destino for um único valor de string ou um valor binário escalar. O valor especificado é adicionado a um valor numérico (aumentando ou diminuindo o valor numérico existente) ou adicionado como um valor extra em um conjunto de strings. Se um conjunto de valores for especificado, os valores serão adicionados ao conjunto existente. Por exemplo, se o conjunto original for [1,2] e o valor fornecido for [3], após a operação de adição, o conjunto será [1,2,3] e não [4,5]. Ocorrerá um erro se uma ação Adicionar for especificada para um atributo de conjunto e o tipo de atributo especificado não corresponder ao tipo de conjunto existente.
Se você usar ADD para um atributo que não existe, o atributo e seus valores serão adicionados ao item.
Se nenhum item corresponder à chave primária especificada:
PUT: cria um novo item com a chave primária especificada. Em seguida, adiciona o atributo especificado.
DELETE - Nada acontece.
ADD: cria um item com a chave primária e o número fornecidos (ou conjunto de números) para o valor de atributo. Não é válido para um tipo string ou binário.
nota
Se você usar ADD
para aumentar ou reduzir um valor de número de um item que não existe antes da atualização, o DynamoDB usará 0
como o valor inicial. Além disso, se você atualizar um item usando ADD
para aumentar ou diminuir um valor de número de um atributo que não existe antes da atualização (mas o item existe), o DynamoDB usará 0
como o valor inicial. Por exemplo, você usa ADD
para adicionar +3
a um atributo que não existia antes da atualização. O DynamoDB usa 0
para o valor inicial, e o valor após a atualização é 3
.
Para obter mais informações sobre o uso dessa operação, consulte Trabalhar com itens e atributos no DynamoDB.
Solicitações
Sintaxe
// This header is abbreviated. // For a sample of a complete header, see API de baixo nível do DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.UpdateItem content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Key": {"HashKeyElement":{"S":"AttributeValue1"}, "RangeKeyElement":{"N":"AttributeValue2"}}, "AttributeUpdates":{"AttributeName3":{"Value":{"S":"AttributeValue3_New"},"Action":"PUT"}}, "Expected":{"AttributeName3":{"Value":{"S":"AttributeValue3_Current"}}}, "ReturnValues":"ReturnValuesConstant" }
Nome | Descrição | Obrigatório |
---|---|---|
TableName
|
O nome da tabela que contém o item a ser atualizado. Tipo: sequência |
Sim |
Key
|
A chave primária que define o item. Para obter mais informações sobre chaves primárias, consulte Chave primária. Tipo: mapa de |
Sim |
AttributeUpdates |
Mapa de nome de atributo para o novo valor e ação para a atualização. Os nomes de atributo especificam os atributos a serem modificados, e não podem conter quaisquer atributos da chave primária. Tipo: mapa de nome de atributo, valor e uma ação para a atualização do atributo. |
|
AttributeUpdates :Action |
Especifica como executar a atualização. Valores possíveis: Tipo: sequência Padrão: |
Não |
Expected
|
Designa um atributo para uma atualização condicional. O parâmetro Tipo: mapa de nomes de atributo. |
Não |
Expected:AttributeName
|
O nome do atributo da operação put condicional. Tipo: sequência |
Não |
Expected:AttributeName: ExpectedAttributeValue |
Use esse parâmetro para especificar se o valor já existe ou não para o par de nome-valor do atributo. A notação JSON seguinte atualiza o item, se o atributo "Cor" ainda não existir para esse item:
A notação JSON seguinte verifica se o atributo com o nome "Cor" tem um valor existente "Amarelo" antes de atualizar o item:
Por padrão, se você usar o parâmetro
notaSe você especificar |
Não |
ReturnValues
|
Use esse parâmetro se você quiser obter os pares de nome-valor de atributo antes que eles sejam atualizados com a solicitação Tipo: sequência |
Não |
Respostas
Sintaxe
A sintaxe a seguir presume que a solicitação especificou um parâmetro ReturnValues
de ALL_OLD
; caso contrário, a resposta terá apenas o elemento ConsumedCapacityUnits
.
HTTP/1.1 200
x-amzn-RequestId: 8966d095-71e9-11e0-a498-71d736f27375
content-type: application/x-amz-json-1.0
content-length: 140
{"Attributes":{
"AttributeName1":{"S":"AttributeValue1"},
"AttributeName2":{"S":"AttributeValue2"},
"AttributeName3":{"S":"AttributeValue3"},
"AttributeName5":{"B":"dmFsdWU="}
},
"ConsumedCapacityUnits":1
}
Nome | Descrição |
---|---|
Attributes
|
Um mapa de pares de nome-valor de atributo, mas somente se o parâmetro Tipo: mapa de pares de nome-valor de atributo. |
ConsumedCapacityUnits |
O número de unidades de capacidade de gravação consumidas pela operação. Esse valor mostra o número utilizado no throughput provisionado. Para ter mais informações, consulte Modo de capacidade provisionada do DynamoDB. Tipo: número |
Erros especiais
Erro | Descrição |
---|---|
ConditionalCheckFailedException
|
Falha na verificação condicional. Atributo ("+ name +"), o valor é ("+ value +") mas o esperado era ("+ expValue +") |
ResourceNotFoundExceptions
|
O item especificado ou o atributo não foi encontrado. |
Exemplos
Para obter exemplos sobre o uso do AWS SDK, consulte Trabalhar com itens e atributos no DynamoDB.
Exemplo de solicitação
// This header is abbreviated. For a sample of a complete header, see API de baixo nível do DynamoDB. POST / HTTP/1.1 x-amz-target: DynamoDB_20111205.UpdateItem content-type: application/x-amz-json-1.0 {"TableName":"comp5", "Key": {"HashKeyElement":{"S":"Julie"},"RangeKeyElement":{"N":"1307654350"}}, "AttributeUpdates": {"status":{"Value":{"S":"online"}, "Action":"PUT"}}, "Expected":{"status":{"Value":{"S":"offline"}}}, "ReturnValues":"ALL_NEW" }
Exemplo de resposta
HTTP/1.1 200 OK
x-amzn-RequestId: 5IMHO7F01Q9P7Q6QMKMMI3R3QRVV4KQNSO5AEMVJF66Q9ASUAAJG
content-type: application/x-amz-json-1.0
content-length: 121
Date: Fri, 26 Aug 2011 21:05:00 GMT
{"Attributes":
{"friends":{"SS":["Lynda, Aaron"]},
"status":{"S":"online"},
"time":{"N":"1307654350"},
"user":{"S":"Julie"}},
"ConsumedCapacityUnits":1
}