# 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 \* (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).