UpdateItem

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.

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"
}

Name (Nome)	Descrição	Obrigatório
TableName	O nome da tabela que contém o item a ser atualizado. Tipo: string	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 HashKeyElement para seu valor e RangeKeyElement para seu valor.	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: PUT (padrão) ADD ou DELETE. As semânticas são explicadas na descrição de UpdateItem. Tipo: string Padrão: PUT	Não
Expected	Designa um atributo para uma atualização condicional. O parâmetro Expected permite que você forneça o nome do atributo, e se o DynamoDB deve ou não verificar se o valor de atributo já existe; ou se o valor de atributo existe e tem um valor específico antes de alterá-lo. Tipo: mapa de nomes de atributo.	Não
Expected:AttributeName	O nome do atributo da operação put condicional. Tipo: string	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: "Expected" : {"Color":{"Exists":false}} A notação JSON seguinte verifica se o atributo com o nome "Cor" tem um valor existente "Amarelo" antes de atualizar o item: "Expected" : {"Color":{"Exists":true},{"Value":{"S":"Yellow"}}} Por padrão, se você usar o parâmetro Expected e fornecer um Value, o DynamoDB presumirá que o atributo existe e tem um valor atual a ser substituído. Portanto, você não precisa especificar {"Exists":true}, pois ele está implícito. Você pode reduzir a solicitação para: "Expected" : {"Color":{"Value":{"S":"Yellow"}}} nota Se você especificar {"Exists":true} sem um valor de atributo para verificar, o DynamoDB retornará um erro.	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 UpdateItem. Possíveis valores de parâmetro são NONE (padrão) ou ALL_OLD, UPDATED_OLD, ALL_NEW ou UPDATED_NEW. Se ALL_OLD for especificado, e UpdateItem sobrescreveu um par de nome-valor de atributo, o conteúdo do item antigo é retornado. Se esse parâmetro não for fornecido ou for NONE, nada será retornado. Se ALL_NEW for especificado, todos os atributos da nova versão do item serão retornados. Se UPDATED_NEW for especificado, somente as novas versões dos atributos atualizados serão retornadas. Tipo: string	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
}

Name (Nome)	Descrição
Attributes	Um mapa de pares de nome-valor de atributo, mas somente se o parâmetro ReturnValues for especificado como algo diferente de NONE na solicitação. 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 obter mais informações, consulte Gerenciar configurações em tabelas com 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.

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
}

Ações relacionadas

• PutItem

• DeleteItem