# Como evitar substituições de objeto com gravações condicionais
Ao usar as gravações condicionais, é possível adicionar outro cabeçalho às solicitações `WRITE` a fim de especificar condições prévias para a operação do Amazon S3. Para gravar objetos condicionalmente, adicione o cabeçalho HTTP `If-None-Match` ou `If-Match`.
O cabeçalho `If-None-Match` evita a substituição de dados existentes, validando que não há um objeto com o mesmo nome de chave já existente no bucket.
Como alternativa, você pode adicionar o cabeçalho `If-Match` para verificar a tag de entidade (ETag) de um objeto antes de gravá-lo. Com esse cabeçalho, o Amazon S3 compara o valor da ETag fornecido com o valor da ETag do objeto no S3. Se esses valores de ETag não forem correspondentes, a operação vai falhar.
Os proprietários de buckets podem usar políticas de bucket para impor gravações condicionais para objetos carregados. Para obter mais informações, consulte [Impor gravações condicionais em buckets do Amazon S3](conditional-writes-enforce.md).
**nota**
Para usar gravações condicionais, é necessário usar o AWS Signature Version 4 para assinar a solicitação.
**Topics**
+ [Como evitar substituições de objeto com base em nomes de chave](#conditional-write-key-names)
+ [Como evitar substituições se o objeto tiver sido alterado](#conditional-write-etags)
+ [Comportamento de uma gravação condicional](#conditional-error-response)
+ [Cenários de gravação condicional](#conditional-write-scenarios)
+ [Impor gravações condicionais em buckets do Amazon S3](conditional-writes-enforce.md)
## Como evitar substituições de objeto com base em nomes de chave
É possível usar o cabeçalho condicional HTTP `If-None-Match` para verificar se um objeto já existe no bucket especificado com base no nome da chave antes de criá-lo ou copiá-lo para o bucket de destino.
As gravações condicionais com o cabeçalho HTTP `If-None-Match` verificam a existência de um objeto durante a operação `WRITE`. Se um nome de chave idêntico for encontrado no bucket, a operação falhará. Sem o cabeçalho HTTP `If-None-Match`, se você fizer upload ou copiar um objeto com um nome de chave idêntico em um bucket sem versão ou com versionamento suspenso, o objeto será substituído. Para ter mais informações sobre como usar nomes de chave, consulte [Nomear objetos do Amazon S3](object-keys.md).
**nota**
O cabeçalho HTTP `If-None-Match` se aplica somente à versão atual de um objeto em um bucket de versão.
Para realizar gravações condicionais com o cabeçalho HTTP `If-None-Match`, é necessário ter a permissão `s3:PutObject`. Isso possibilita que o chamador confira a presença de objetos no bucket. O cabeçalho `If-None-Match` espera o valor \$1 (asterisco).
É possível usar o cabeçalho `If-None-Match` com as seguintes APIs:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)
### Put condicional usando a AWS CLI
O exemplo de comando `put-object` a seguir tenta realizar uma gravação condicional para um objeto com o nome de chave `dir-1/my_images.tar.bz2`.
```
aws s3api put-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --body my_images.tar.bz2 --if-none-match "*"
```
Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html) na *Referência de comandos da AWS CLI*.
Para obter informações sobre o AWS CLI, consulte [O que é AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) no *Guia do usuário do AWS Command Line Interface*.
### Copy condicional usando a AWS CLI
O exemplo de comando `copy-object` a seguir tenta copiar um objeto para um bucket de destino com uma gravação condicional para um objeto com o nome de chave `dir-1/my_images.tar.bz2`.
```
aws s3api copy-object --copy-source amzn-s3-demo-bucket/key --key dir-1/my_images.tar.bz2 --bucket amzn-s3-demo-bucket2 --if-none-match "*"
```
Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/copy-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/copy-object.html) na *Referência de comandos da AWS CLI*.
Para obter informações sobre o AWS CLI, consulte [O que é AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) no *Guia do usuário do AWS Command Line Interface*.
### Multipart upload condicional de várias partes usando a AWS CLI
O exemplo de comando `complete-multipart-upload` a seguir tenta realizar um multipart upload condicional com uma gravação condicional para um objeto com o nome de chave `dir-1/my_images.tar.bz2`. Neste exemplo, o prefixo file://é usado para carregar a estrutura JSON de um arquivo na pasta local chamada `mpustruct`, que lista todas as partes que foram carregadas para esse multipart upload específico.
```
aws s3api complete-multipart-upload --multipart-upload file://mpustruct --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --upload-id upload-id --if-none-match "*"
```
Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/complete-multipart-upload.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/complete-multipart-upload.html) na *Referência de comandos da AWS CLI*.
Para obter informações sobre o AWS CLI, consulte [O que é AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) no *Guia do usuário do AWS Command Line Interface*.
## Como evitar substituições se o objeto tiver sido alterado
A ETag de um objeto é uma string exclusiva do objeto, que reflete uma alteração no conteúdo do objeto. Você pode usar o cabeçalho `If-Match` para comparar o valor da ETag de um objeto em um bucket do Amazon S3 com aquele que você fornece durante a operação `WRITE`. Se esses valores de ETag não forem correspondentes, a operação vai falhar. Para ter mais informações sobre as ETags, consulte [Usar Content-MD5 e a ETag para verificar objetos carregados](checking-object-integrity-upload.md#checking-object-integrity-etag-and-md5).
Para realizar gravações condicionais com o cabeçalho HTTP `If-Match`, é necessário ter as permissões `s3:PutObject` e `s3:GetObject`. Isso possibilita que o chamador verifique a ETag e o estado dos objetos no bucket. O cabeçalho `If-Match` espera o valor da ETag como uma string.
É possível usar o cabeçalho `If-Match` com as seguintes APIs:
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html)
+ [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)
### Put condicional usando a AWS CLI
O exemplo de comando `put-object` a seguir tenta realizar uma gravação condicional com o valor de ETag fornecido `6805f2cfc46c0f04559748bb039d69ae`.
```
aws s3api put-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --body my_images.tar.bz2 --if-match "6805f2cfc46c0f04559748bb039d69ae"
```
Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/put-object.html) na *Referência de comandos da AWS CLI*.
Para obter informações sobre o AWS CLI, consulte [O que é AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) no *Guia do usuário do AWS Command Line Interface*.
### Copy condicional usando a AWS CLI
O exemplo de comando `copy-object` a seguir tenta realizar uma gravação condicional com o valor de ETag fornecido `6805f2cfc46c0f04559748bb039d69ae`.
```
aws s3api copy-object --copy-source amzn-s3-demo-bucket/key --key dir-1/my_images.tar.bz2 --bucket amzn-s3-demo-bucket2 --if-match "6805f2cfc46c0f04559748bb039d69ae"
```
Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/copy-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/copy-object.html) na *Referência de comandos da AWS CLI*.
Para obter informações sobre o AWS CLI, consulte [O que é AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) no *Guia do usuário do AWS Command Line Interface*.
### Multipart upload condicional de várias partes usando a AWS CLI
O exemplo de comando `complete-multipart-upload` a seguir tenta realizar um multipart upload com uma gravação condicional usando o valor de ETag `6805f2cfc46c0f04559748bb039d69ae` fornecido. Neste exemplo, o prefixo file://é usado para carregar a estrutura JSON de um arquivo na pasta local chamada `mpustruct`, que lista todas as partes que foram carregadas para esse multipart upload específico.
```
aws s3api complete-multipart-upload --multipart-upload file://mpustruct --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --upload-id upload-id --if-match "6805f2cfc46c0f04559748bb039d69ae"
```
Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/complete-multipart-upload.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/complete-multipart-upload.html) na *Referência de comandos da AWS CLI*.
Para obter informações sobre o AWS CLI, consulte [O que é AWS Command Line Interface?](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html) no *Guia do usuário do AWS Command Line Interface*.
## Comportamento de uma gravação condicional
**Gravações ou cópias condicionais com o cabeçalho `If-None-Match`**
As gravações condicionais com o cabeçalho `If-None-Match` são avaliadas em relação aos objetos existentes em um bucket. Se não houver nenhum objeto existente com o mesmo nome de chave no bucket, a operação de gravação será bem-sucedida, resultando em uma resposta `200 OK`. Se houver um objeto existente, a operação de gravação falhará, resultando em uma resposta `412 Precondition Failed`.
Para buckets com o versionamento habilitado, se não houver nenhuma versão atual do objeto com o mesmo nome, ou se a versão atual do objeto for um marcador de exclusão, a operação de gravação será bem-sucedida. Caso contrário, isso resultará em uma resposta `412 Precondition Failed`, que indica uma falha na operação de gravação.
Se ocorrerem várias gravações ou cópias condicionais para o mesmo nome de objeto, a primeira operação de gravação que for concluída terá êxito. O Amazon S3 rejeitará as gravações subsequentes com uma resposta `412 Precondition Failed`.
Também é possível receber uma resposta `409 Conflict` no caso de solicitações simultâneas se uma solicitação de exclusão de um objeto for bem-sucedida antes que uma operação de gravação condicional nesse objeto seja concluída. Ao usar gravações condicionais com `PutObject`, os uploads podem ser repetidos após o recebimento de um erro `409 Conflict`. Ao usar `CompleteMultipartUpload`, o upload fracionado deve ser reinicializado com `CreateMultipartUpload` para que o objeto seja carregado novamente após o recebimento de um erro `409 Conflict`.
**Gravações ou cópias condicionais com cabeçalho `If-Match`**
O cabeçalho `If-Match` é avaliado em relação aos objetos existentes em um bucket. Se já houver um objeto com o mesmo nome de chave e uma ETag correspondente, a operação de gravação será bem-sucedida, resultando em uma resposta `200 OK`. Se a ETag não corresponder, a operação de gravação falhará com uma resposta `412 Precondition Failed`.
Você também pode receber uma resposta `409 Conflict` no caso de solicitações simultâneas.
Você receberá uma resposta `404 Not Found` se uma solicitação simultânea de exclusão de um objeto for bem-sucedida antes que uma operação de gravação condicional nesse objeto seja concluída, já que a chave do objeto não existe mais. Você deve fazer upload do objeto novamente ao receber uma `404 Not Found` resposta.
Se não houver uma versão atual do objeto com o mesmo nome ou se a versão atual do objeto for um marcador de exclusão, a operação falhará com um erro `404 Not Found`.
## Cenários de gravação condicional
Considere os casos a seguir, em que dois clientes estão executando operações no mesmo bucket.
**Gravações condicionais durante uploads fracionados**
As gravações condicionais não levam em conta nenhuma solicitação de carregamento fracionado em andamento, pois nesse caso os objetos ainda não foram totalmente gravados. Considere o exemplo a seguir, em que o Cliente 1 está fazendo upload de um objeto usando o carregamento fracionado. Durante o carregamento fracionado, o Cliente 2 consegue gravar com êxito o mesmo objeto com a operação de gravação condicional. Posteriormente, quando o Cliente 1 tenta concluir o upload fracionado usando uma gravação condicional, o upload falha.
**nota**
Esse cenário resultará em uma resposta `412 Precondition Failed` para os cabeçalhos `If-None-Match` e `If-Match`.
![\[Um exemplo de dois clientes que gravam itens com o mesmo nome de chave. Um com UploadPart para carregamento fracionado (MPU) e outro com PutObject e uma gravação condicional. A operação CompleteMultipartUpload, que se inicia depois, falha.\]](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/userguide/images/conwrite_put_mpu.png)
**Exclusões simultâneas durante uploads fracionados**
Se uma solicitação de exclusão for bem-sucedida antes que uma solicitação de gravação condicional possa ser concluída, o Amazon S3 exibirá uma resposta `409 Conflict` ou `404 Not Found` para a operação de gravação. Isso ocorre porque a solicitação de exclusão iniciada anteriormente tem precedência sobre a operação de gravação condicional. Nesses casos, é necessário iniciar um novo carregamento fracionado.
**nota**
Esse cenário resultará em uma resposta `409 Conflict` para um cabeçalho `If-None-Match` e em uma resposta `404 Not Found` para um cabeçalho `If-Match`.
![\[Um exemplo de dois clientes, um usando carregamento fracionado e outro enviando uma solicitação de exclusão após o início do MPU. A solicitação de exclusão termina antes do início da gravação condicional.\]](http://docs.aws.amazon.com/pt_br/AmazonS3/latest/userguide/images/conwrite_delete_mpu.png)
**nota**
Para minimizar os custos de armazenamento, recomendamos que você configure uma regra de ciclo de vida para excluir uploads incompletos de várias partes após um determinado número de dias usando a ação `AbortIncompleteMultipartUpload`. Para obter mais informações sobre como criar uma regra de ciclo de vida para excluir uploads incompletos de várias partes, consulte [Configurando uma política de ciclo de vida de bucket para anular multipart uploads incompletos](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mpu-abort-incomplete-mpu-lifecycle-config.html).
# Impor gravações condicionais em buckets do Amazon S3
Ao usar as políticas de bucket do Amazon S3, você pode impor gravações condicionais para uploads de objetos em buckets de uso geral.
Uma política de bucket é uma política baseada em recursos que você pode usar para conceder permissões de acesso ao bucket do Amazon S3 e aos objetos contidos nele. Só o proprietário do bucket pode associar uma política a um bucket. Para obter mais informações sobre políticas de bucket, consulte [Políticas de bucket para o Amazon S3](bucket-policies.md).
Você pode usar as chaves de condição `s3:if-match` ou `s3:if-none-match` como elemento `Condition` opcional ou o bloco `Condition` para especificar quando uma política está em vigor. Para uploads fracionados, você deve especificar a chave de condição `s3:ObjectCreationOperation` para isentar as operações `CreateMultipartUpload`, `UploadPart` e `UploadPartCopy`, pois essas APIs não aceitam cabeçalhos condicionais. Para ter mais informações sobre como usar condições em políticas de bucket, consulte [Exemplos de políticas de bucket usando chaves de condição](amazon-s3-policy-keys.md).
**nota**
Se você usar uma política de bucket para impor gravações condicionais, não poderá realizar operações de cópia no bucket ou no prefixo especificado na política de bucket. As solicitações `CopyObject` sem um cabeçalho HTTP `If-None-Match` ou `If-Match` falham com um erro `403 Access Denied`. As solicitações `CopyObject` feitas com esses cabeçalhos HTTP falham com uma resposta `501 Not Implemented`.
Os exemplos a seguir mostram como usar condições em uma política de bucket para forçar os clientes a usar o cabeçalho HTTP `If-None-Match` ou `If-Match`.
**Topics**
+ [Exemplo 1: permitir somente uploads de objetos usando solicitações `PutObject` e `CompleteMultipartUpload` que incluam o cabeçalho `if-none-match`](#conditional-writes-enforce-ex1)
+ [Exemplo 2: permitir somente uploads de objetos usando solicitações `PutObject` e `CompleteMultipartUpload` que incluam o cabeçalho `if-match`](#conditional-writes-enforce-ex2)
+ [Exemplo 3: permitir somente solicitações de upload de objetos que incluam o cabeçalho `if-none-match` ou `if-match`](#conditional-writes-enforce-ex3)
## Exemplo 1: permitir somente uploads de objetos usando solicitações `PutObject` e `CompleteMultipartUpload` que incluam o cabeçalho `if-none-match`
Essa política permite que a conta 111122223333, usuária Alice, grave no bucket *amzn-s3-demo-bucket1* se a solicitação incluir o cabeçalho `if-none-match`, garantindo que a chave de objeto ainda não exista no bucket. Todas as solicitações `PutObject` e `CompleteMultipartUpload` ao bucket especificado devem incluir o cabeçalho `if-none-match` para serem bem-sucedidas. Usando esse cabeçalho, os clientes só poderão gravar nesse bucket se a chave de objeto não existir no bucket.
**nota**
Essa política também define a chave de condição `s3:ObjectCreationOperation` que permite uploads fracionados usando as APIs `CreateMultipartUpload`, `UploadPart` e `UploadPartCopy`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "AllowConditionalPut",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
"Condition": {
"Null": {
"s3:if-none-match": "false"
}
}
},
{
"Sid": "AllowConditionalPutwithMPUs",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
"Condition": {
"Bool": {
"s3:ObjectCreationOperation": "false"
}
}
}
]
}
```
------
## Exemplo 2: permitir somente uploads de objetos usando solicitações `PutObject` e `CompleteMultipartUpload` que incluam o cabeçalho `if-match`
Essa política permite que a conta 111122223333, usuário Alice, grave em *amzn-s3-demo-bucket1* somente se a solicitação incluir o cabeçalho `if-match`. Esse cabeçalho compara o valor da ETag de um objeto no S3 com o valor fornecido durante a operação `WRITE`. Se esses valores de ETag não forem correspondentes, a operação vai falhar. Todas as solicitações `PutObject` e `CompleteMultipartUpload` ao bucket especificado devem incluir o cabeçalho `if-match` para serem bem-sucedidas.
**nota**
Essa política também define a chave de condição `s3:ObjectCreationOperation` que permite uploads fracionados usando as APIs `CreateMultipartUpload`, `UploadPart` e `UploadPartCopy`.
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowPutObject",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
},
{
"Sid": "BlockNonConditionalObjectCreation",
"Effect": "Deny",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
"Condition": {
"Null": {
"s3:if-match": "true"
},
"Bool": {
"s3:ObjectCreationOperation": "true"
}
}
},
{
"Sid": "AllowGetObjectBecauseConditionalPutIfMatchETag",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*"
}
]
}
```
## Exemplo 3: permitir somente solicitações de upload de objetos que incluam o cabeçalho `if-none-match` ou `if-match`
Essa política permite que a conta 111122223333, usuário Alice, grave em *amzn-s3-demo-bucket1* se as solicitações incluírem o cabeçalho `if-none-match` ou `if-match`. Isso permite que Alice faça upload de um objeto se o nome de chave não existir no bucket. Se o nome de chave existir, Alice poderá sobrescrever o objeto se a ETag do objeto corresponder à ETag fornecida na solicitação `PUT`.
**nota**
Essa política também define a chave de condição `s3:ObjectCreationOperation` que permite uploads fracionados usando as APIs `CreateMultipartUpload`, `UploadPart` e `UploadPartCopy`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": " AllowConditionalPutifAbsent",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
"Condition": {
"Null": {
"s3:if-none-match": "false"
}
}
},
{
"Sid": "AllowConditionalPutIfMatchEtag",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
"Condition": {
"Null": {
"s3:if-match": "false"
}
}
},
{
"Sid": "AllowConditionalObjectCreation",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*",
"Condition": {
"Bool": {
"s3:ObjectCreationOperation": "false"
}
}
},
{
"Sid": " AllowGetObjectBecauseConditionalPutIfMatchETag",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/Alice"
},
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::amzn-s3-demo-bucket1/*"
}
]
}
```
------