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.

nota

Para usar gravações condicionais, é necessário fazer as solicitações por HTTPS (TLS) ou usar o AWS Signature Version 4 para assinar a solicitação.

Tópicos

• Como evitar substituições de objeto com base em nomes de chave

• Como evitar substituições se o objeto tiver sido alterado

• Comportamento de uma gravação condicional

• Cenários de gravação condicional

• Impor gravações condicionais em buckets do Amazon S3

Como evitar substituições de objeto com base em nomes de chave

Você pode 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. Ao fazer upload de um objeto no Amazon S3, especifique o nome da chave: um identificador exclusivo de um objeto em um bucket, com diferenciação entre maiúsculas e minúsculas. Sem o cabeçalho HTTP If-None-Match, se você fizer upload de um objeto com um nome de chave idêntico em um bucket sem versionamento ou com versionamento suspenso, o objeto será substituído. Em um bucket com versionamento, o objeto cujo upload foi feito mais recentemente se torna a versão atual do objeto. 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á. Para ter mais informações sobre como usar nomes de chave, consulte Nomear objetos do Amazon S3.

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:

• PutObject

• CompleteMultipartUpload

Como usar o AWS CLI

O exemplo de comando put-object a seguir tenta realizar uma gravação condicional para um objeto com o nome da 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 obter mais informações, consulte put-object na Referência de comandos da AWS CLI.

Para obter informações sobre o AWS CLI, consulte O que é AWS Command Line Interface? 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.

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:

• PutObject

• CompleteMultipartUpload

Como usar o 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 obter mais informações, consulte put-object na Referência de comandos da AWS CLI.

Para obter informações sobre o AWS CLI, consulte O que é AWS Command Line Interface? no Guia do usuário do AWS Command Line Interface.

Comportamento de uma gravação condicional

Gravações condicionais com 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 condicionais para o mesmo nome de objeto, a primeira operação de gravação que for concluída será bem-sucedida. 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 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 um 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.

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.

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.