# Adicionar condições prévias às operações do S3 com solicitações condicionais É possível usar solicitações condicionais para adicionar condições prévias às operações do S3. Para usar solicitações condicionais, é necessário adicionar outro cabeçalho à operação de API do Amazon S3. Esse cabeçalho especifica uma condição que, se não for atendida, provocará uma falha na operação do S3. As leituras condicionais comportam solicitações `GET`, `HEAD` e `COPY`. É possível adicionar condições prévias para exibir ou copiar um objeto com base na tag de entidade (ETag) ou na data da última modificação. Isso pode limitar uma operação do S3 a objetos atualizados desde uma data especificada. Também é possível limitar uma operação do S3 a uma ETag específica. Isso pode garantir que você exiba ou copie somente uma versão específica do objeto. Para obter mais informações sobre metadados de objeto, consulte [Trabalhar com metadados de objeto](UsingMetadata.md). As gravações condicionais podem garantir que não exista nenhum objeto com o mesmo nome de chave no bucket durante as operações `PUT`. Isso evita a substituição de objetos existentes por nomes de chave idênticos. Da mesma forma, você pode usar gravações condicionais para verificar se a ETag de um objeto está inalterada antes de atualizar o objeto. Isso evita substituições não intencionais em um objeto sem conhecer o estado do conteúdo dele. É possível usar gravações condicionais para solicitações [https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html), [CompleteMultipartUpload](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CompleteMultipartUpload.html) ou [CopyObject](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html). Para obter mais informações sobre nomes de chave, consulte [Nomear objetos do Amazon S3](object-keys.md). As exclusões condicionais avaliam se o objeto existe ou não foi alterado antes de excluí-lo. É possível realizar exclusões condicionais usando as APIs `DeleteObject` ou `DeleteObjects` em buckets de diretório e de uso geral. Para ter mais informações sobre exclusões condicionais, consulte [Como executar exclusões condicionais](conditional-deletes.md). Não há custo adicional para leituras, gravações ou exclusões condicionais. Você só paga as taxas existentes para as solicitações aplicáveis, inclusive para solicitações malsucedidas. Para obter informações sobre os recursos e a definição de preço do Amazon S3, consulte a [definição de preço do Amazon S3](https://aws.amazon.com/s3/pricing). **Topics** + [Como recuperar ou copiar objetos com base em metadados com leituras condicionais](conditional-reads.md) + [Como evitar substituições de objeto com gravações condicionais](conditional-writes.md) + [Como executar exclusões condicionais](conditional-deletes.md) # Como recuperar ou copiar objetos com base em metadados com leituras condicionais Com as leituras condicionais, é possível adicionar um cabeçalho extra à solicitação de leitura para adicionar condições prévias à operação do S3. Se essas condições prévias não forem atendidas, a solicitação de leitura falhará. É possível usar leituras condicionais em solicitações `GET`, `HEAD` ou `COPY` para exibir apenas um objeto com base nos metadados. Ao fazer upload de um objeto, o Amazon S3 cria metadados controlados pelo sistema que só podem ser modificados pelo S3. Tags de entidade (ETags) e Last-Modified são exemplos de metadados controlados pelo sistema. ETag de um objeto é uma string que representa uma versão específica de um objeto. A data Last-Modified corresponde a metadados que representam a data de criação de um objeto ou a data da última modificação, a mais recente entre as duas. Com leituras condicionais, é possível exibir um objeto com base na ETag ou na data da última modificação do objeto. É possível especificar um valor de ETag com sua solicitação e exibir o objeto somente se o valor da ETag coincidir. Isso pode garantir que você exiba ou copie apenas uma versão específica de um objeto. É possível especificar um valor de Last-Modified com sua solicitação de leitura e exibir um objeto somente se ele tiver sido modificado desde a data fornecida. ## APIs compatíveis As seguintes APIs do S3 são compatíveis com o uso de leituras condicionais: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) É possível usar os cabeçalhos a seguir para exibir um objeto dependente da tag da entidade (ETag) ou da data da última modificação. Para ter mais informações sobre metadados de objetos, como ETags e Last-Modified, consulte [Metadados do objeto definidos pelo sistema](UsingMetadata.md#SysMetadata). **[https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html)** + `If-Match`: exibirá o objeto somente se a ETag corresponder à fornecida. + `If-Modified-Since`: exibirá o objeto somente se ele tiver sido modificado desde o horário especificado. + `If-None-Match`: exibirá o objeto somente se a ETag não corresponder à fornecida. + `If-Unmodified-Since`: exibirá o objeto somente se ele não tiver sido modificado desde o horário especificado. Para ter mais informações sobre esses cabeçalhos, erros exibidos e a ordem em que o S3 processa vários cabeçalhos condicionais em uma única solicitação, consulte [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetObject.html) na “Referência de API do Amazon Simple Storage Service”. **[https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html)** + `If-Match`: exibirá o objeto somente se a ETag corresponder à fornecida. + `If-Modified-Since`: exibirá o objeto somente se ele tiver sido modificado desde o horário especificado. + `If-None-Match`: exibirá o objeto somente se a ETag não corresponder à fornecida. + `If-Unmodified-Since`: exibirá o objeto somente se ele não tiver sido modificado desde o horário especificado. Para ter mais informações sobre esses cabeçalhos, erros exibidos e a ordem em que o S3 processa vários cabeçalhos condicionais em uma única solicitação, consulte [https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html) na “Referência de API do Amazon Simple Storage Service”. **[https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html)** + `x-amz-copy-source-if-match`: copiará o objeto de origem somente se a ETag corresponder à fornecida. + `x-amz-copy-source-if-modified-since`: copiará o objeto de origem somente se ele tiver sido modificado desde o horário especificado. + `x-amz-copy-source-if-none-match`: copiará o objeto de origem somente se a ETag não corresponder à fornecida. + `x-amz-copy-source-if-unmodified-since`: copiará o objeto de origem somente se ele não tiver sido modificado desde o horário especificado. + `If-Match`: copia o objeto somente se a ETag corresponder à fornecida. `If-Match` exige o valor da ETag como uma string. + `If-None-Match`: copia o objeto somente se a ETag não corresponder à fornecida. `If-None-Match` exige o caractere “\$1” (asterisco). Para ter mais informações sobre esses cabeçalhos, erros exibidos e a ordem em que o S3 processa vários cabeçalhos condicionais em uma única solicitação, consulte [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CopyObject.html) na “Referência de API do Amazon Simple Storage Service”. # 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/*" } ] } ``` ------ # Como executar exclusões condicionais É possível usar as exclusões condicionais para avaliar se o objeto existe ou não foi alterado antes de excluí-lo. Você pode realizar exclusões condicionais usando as operações de API `DeleteObject` ou `DeleteObjects` em buckets de diretório e de uso geral do S3. Para começar, ao fazer uma solicitação de exclusão condicional, você pode usar o cabeçalho `HTTP If-Match` com o valor da pré-condição `*` para verificar se o objeto existe ou o cabeçalho `If-Match` com a `ETag` fornecida para verificar se o objeto foi modificado. É possível aplicar exclusões condicionais em nível de bucket de uso geral usando as políticas de bucket do S3 ou do Identity and Access Management (IAM). Para obter mais informações, consulte [Impor exclusões condicionais em buckets do Amazon S3](conditional-delete-enforce.md). **nota** As avaliações de exclusão condicional só se aplicam à versão atual do objeto. **Topics** + [Como verificar se o objeto foi modificado antes de excluí-lo](#conditional-deletes-etags) + [Como verificar se o objeto existe antes de excluí-lo](#conditional-delete) + [Impor exclusões condicionais em buckets do Amazon S3](conditional-delete-enforce.md) ## Como verificar se o objeto foi modificado antes de excluí-lo Com as exclusões condicionais, você pode proteger sua aplicação contra exclusões acidentais de objetos. Você pode usar o cabeçalho `HTTP If-Match` com o valor `ETag` para verificar se um objeto foi modificado. Se o valor `ETag` de um objeto em um bucket do S3 não corresponder à `ETag` que você fornece durante a operação de exclusão, a operação falhará. Para excluir condicionalmente vários objetos usando a operação `DeleteObjects`, você deve fornecer o valor `ETag` no elemento `ETag` do objeto no corpo da solicitação XML. Para obter mais informações, consulte [Usar Content-MD5 e a ETag para verificar objetos carregados](checking-object-integrity-upload.md#checking-object-integrity-etag-and-md5). **nota** Para realizar exclusões condicionais com o cabeçalho `If-Match` com o valor `ETag`, você deve ter as permissões `s3:DeleteObject` e `s3:GetObject`. O cabeçalho `If-Match` com o valor `ETag` é avaliado em relação aos objetos existentes em um bucket. Se já houver um objeto com o mesmo nome de chave e a `ETag` correspondente, as solicitações `DeleteObject` terão êxito e exibirão a resposta `204 No content`. Se não houver correspondência com a `ETag`, a operação de gravação falhará, exibindo a resposta `412 Precondition Failed`. Para excluir condicionalmente vários objetos usando a operação `DeleteObjects`, você pode fornecer o valor `ETag` no elemento `ETag` do objeto no corpo da solicitação XML. Se a solicitação tiver êxito, a operação `DeleteObjects` responderá com um `200 OK` e fornecerá o status de cada objeto no corpo da resposta. Se a pré-condição for satisfeita, a resposta desse objeto será capturada no elemento `` do corpo da resposta. Se a pré-condição não for satisfeita, a resposta desse objeto será capturada no elemento `` do corpo da resposta. Também é possível receber uma resposta de erro `409 Conflict` no caso de solicitações simultâneas se uma solicitação `DELETE` ou `PUT` de um objeto tiver êxito antes que uma operação de gravação condicional nesse objeto seja concluída. 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ê pode usar o cabeçalho `If-Match` com o valor `ETag` para as seguintes APIs: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) ### Como usar o AWS CLI O exemplo de comando `delete-object` a seguir tenta realizar uma exclusão condicional com o valor de ETag `6805f2cfc46c0f04559748bb039d69al` fornecido. ``` aws s3api delete-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --if-match "6805f2cfc46c0f04559748bb039d69al" ``` Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-object.html) na *Referência de comandos da AWS CLI*. O exemplo de comando `delete-objects` a seguir tenta realizar uma exclusão condicional com o valor de ETag `6805f2cfc46c0f04559748bb039d69al` fornecido. ``` aws s3api delete-objects --bucket amzn-s3-demo-bucket --delete '{"Objects":[{"Key":"my_images.tar.bz2", "ETag": "6805f2cfc46c0f04559748bb039d69al"}]}' ``` Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-objects.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-objects.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 verificar se o objeto existe antes de excluí-lo Você pode usar o cabeçalho `If-Match` com o valor `*` para verificar se o objeto existe antes de tentar excluí-lo. O valor `*` significa que a operação só deve continuar se o objeto existir, independentemente de ter sido modificado ou não. Os marcadores de exclusão são objetos especiais em buckets de uso geral versionados do S3 que indicam que um objeto foi excluído. Eles são espaços reservados que fazem o objeto parecer excluído, preservando as versões anteriores. Portanto, quando você usar `If-Match:*` com uma API `DeleteObject`, a operação só terá êxito com um `204 No Content` se o objeto existir. Quando a versão mais recente do objeto é um marcador de exclusão, o objeto não existe e a API `DeleteObject` falha, exibindo a resposta `412 Precondition Failed`. Para obter mais informações sobre marcadores de exclusão, consulte [Trabalhar com marcadores de exclusão](DeleteMarker.md). Para excluir condicionalmente vários objetos usando a operação `DeleteObjects`, você pode fornecer `*` no elemento `ETag` do objeto no corpo da solicitação XML. Se a pré-condição for satisfeita, a operação `DeleteObjects` responderá com um `200 OK` e fornecerá o status de cada objeto no corpo da resposta. Se a pré-condição for satisfeita, a resposta desse objeto será capturada no elemento `` do corpo da resposta. Se a pré-condição não for satisfeita, a resposta desse objeto será capturada no elemento `` do corpo da resposta. Se o objeto não existir ao avaliar qualquer uma das pré-condições, o S3 rejeitará a solicitação e exibirá a resposta de erro `Not Found`. **nota** Para realizar exclusões condicionais com `If-Match:*`, você deve ter permissões `s3:DeleteObject`. Você pode usar o cabeçalho `If-Match` com o valor `*` para as seguintes APIs: + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObject.html) + [https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html) ### Como usar o AWS CLI O exemplo de comando `delete-object` a seguir tenta executar uma exclusão condicional de um objeto com um nome de chave `my_images.tar.bz2` que tem o valor `*`, que representa qualquer ETag. ``` aws s3api delete-object --bucket amzn-s3-demo-bucket --key dir-1/my_images.tar.bz2 --if-match "*" ``` Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-object.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-object.html) na *Referência de comandos da AWS CLI*. O exemplo de comando `delete-objects` a seguir tenta executar uma exclusão condicional de um objeto com um nome de chave `my_images.tar.bz2` que tem o valor `*`, que representa qualquer ETag. ``` aws s3api delete-objects --bucket amzn-s3-demo-bucket --delete '{"Objects":[{"Key":"my_images.tar.bz2", "ETag": "*"}]}' ``` Para ter mais informações, consulte [https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-objects.html](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/s3api/delete-objects.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*. # Impor exclusões condicionais em buckets do Amazon S3 Ao usar políticas de bucket do Amazon S3, você pode impor o cabeçalho `If-Match` com exclusões condicionais para objetos em buckets de uso geral. Se o cabeçalho `If-Match` não existir, a solicitação será negada com um `403 Access Denied`. Uma política de bucket é baseada em recursos que você pode usar para conceder permissões de acesso ao bucket 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). 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-Match`. **Topics** + [Exemplo 1: permitir somente exclusões condicionais que usam o cabeçalho `If-Match` com o valor `ETag`](#conditional-writes-enforce-ex1) + [Exemplo 2: permitir somente exclusões condicionais que usam o cabeçalho `If-Match` com o valor `*`](#conditional-deletes-enforce-ex2) ## Exemplo 1: permitir somente exclusões condicionais que usam o cabeçalho `If-Match` com o valor `ETag` Você pode usar essa política de bucket para permitir somente exclusões condicionais que usam solicitações `DeleteObject` e `DeleteObjects` que incluem o cabeçalho `If-Match` com o valor `ETag`. Nesse caso, todas as exclusões não condicionais seriam negadas e as exclusões condicionais seriam aceitas. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowConditionalDeletes", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/Alice" }, "Action": "s3:DeleteObject", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Condition": { "Null": { "s3:if-match": "false" } } }, { "Sid": "AllowGetObjectBecauseConditionalDeleteIfMatchETag", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/Alice" }, "Action": "s3:GetObject", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*" } ] } ``` ## Exemplo 2: permitir somente exclusões condicionais que usam o cabeçalho `If-Match` com o valor `*` Você pode usar essa política de bucket para permitir somente exclusões condicionais que usam solicitações `DeleteObject` e `DeleteObjects` que incluem o cabeçalho `If-Match` com o valor `*`. Nesse caso, todas as exclusões não condicionais seriam negadas e as exclusões condicionais seriam aceitas. ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "AllowConditionalDeletes", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:user/Alice" }, "Action": "s3:DeleteObject", "Resource": "arn:aws:s3:::amzn-s3-demo-bucket/*", "Condition": { "Null": { "s3:if-match": "false" } } } ] } ```