# PutItem **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](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/).** ## Descrição Cria um novo item ou substitui um item antigo por um novo (incluindo todos os atributos). Se algum item existe em uma tabela específica com a mesma chave primária, o novo item substitui completamente o item já existente. Você pode executar uma operação Put condicional (inserir um novo item, caso não exista um com a chave primária) ou substituir um item existente se ele tiver determinados 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`. **nota** Para garantir que um novo item não substitua um item existente, use uma operação put condicional com `Exists` definido como `false` para o atributo de chave primária, ou atributos. Para obter mais informações sobre o uso de `PutItem`, consulte [Trabalhar com itens e atributos no DynamoDB](WorkingWithItems.md). ## 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.PutItem content-type: application/x-amz-json-1.0 {"TableName":"Table1", "Item":{ "AttributeName1":{"S":"AttributeValue1"}, "AttributeName2":{"N":"AttributeValue2"}, "AttributeName5":{"B":"dmFsdWU="} }, "Expected":{"AttributeName3":{"Value": {"S":"AttributeValue"}, "Exists":Boolean}}, "ReturnValues":"ReturnValuesConstant"} ``` **** | Nome | Descrição | Obrigatório | | --- | --- | --- | | TableName | O nome da tabela que conterá o item. Tipo: string | Sim | | Item | Um mapa dos atributos do item, e deve incluir os valores de chave primária que definem o item. Outros pares de nome-valor de atributo podem ser fornecidos para o item. Para obter mais informações sobre chaves primárias, consulte [Chave primária](HowItWorks.CoreComponents.md#HowItWorks.CoreComponents.PrimaryKey).Tipo: mapa de nomes de atributo para valores de atributo. | Sim | | Expected | Designa um atributo para uma operação Put 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 um nome de atributo para um valor de atributo, e se ele existe. | 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 substitui o item, se o atributo "Cor" ainda não existir para esse item:
"Expected" :
	{"Color":{"Exists":false}}
A notação JSON a seguir verifica se o atributo com o nome "Cor" tem um valor existente "Amarelo" antes de substituir 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"}}}
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 `PutItem`. Os possíveis valores de parâmetro são `NONE` (padrão) ou `ALL_OLD`. Se `ALL_OLD` for especificado, e `PutItem` 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.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: 85 {"Attributes": {"AttributeName3":{"S":"AttributeValue3"}, "AttributeName2":{"SS":"AttributeValue2"}, "AttributeName1":{"SS":"AttributeValue1"}, }, "ConsumedCapacityUnits":1 } ``` **** | Nome | Descrição | | --- | --- | | Attributes | Os valores de atributo antes da operação Put, mas somente se o parâmetro `ReturnValues` for especificado `ALL_OLD` 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 ter mais informações, consulte [Modo de capacidade provisionada do DynamoDB](provisioned-capacity-mode.md). Tipo: número | ## Erros especiais **** | Erro | Descrição | | --- | --- | | ConditionalCheckFailedException | Falha na verificação condicional. Um valor de atributo esperado não foi encontrado. | | ResourceNotFoundException | 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](WorkingWithItems.md). ### 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.PutItem content-type: application/x-amz-json-1.0 {"TableName":"comp5", "Item": {"time":{"N":"300"}, "feeling":{"S":"not surprised"}, "user":{"S":"Riley"} }, "Expected": {"feeling":{"Value":{"S":"surprised"},"Exists":true}} "ReturnValues":"ALL_OLD" } ``` ### Exemplo de resposta ``` HTTP/1.1 200 x-amzn-RequestId: 8952fa74-71e9-11e0-a498-71d736f27375 content-type: application/x-amz-json-1.0 content-length: 84 {"Attributes": {"feeling":{"S":"surprised"}, "time":{"N":"300"}, "user":{"S":"Riley"}}, "ConsumedCapacityUnits":1 } ``` ## Ações relacionadas + [UpdateItem](API_UpdateItem_v20111205.md) + [DeleteItem](API_DeleteItem_v20111205.md) + [GetItem](API_GetItem_v20111205.md) + [BatchGetItem](API_BatchGetItem_v20111205.md)