Controle de versões de objetos

Acessar os exemplos

O Cloud Storage oferece o recurso de controle de versões de objetos para recuperar objetos que são excluídos ou substituídos. Nesta página, você verá esse recurso e as opções disponíveis.

Ative o controle de versões de objetos para evitar que os dados do Cloud Storage sejam substituídos ou excluídos acidentalmente. Isso aumenta os custos de armazenamento, que podem ser parcialmente reduzidos configurando o gerenciamento do ciclo de vida de objetos para excluir versões mais antigas.

Introdução

Ative o controle de versões de objetos para um bucket. Uma vez ativado,

  • o Cloud Storage cria uma versão não atual de um objeto toda vez que a versão ativa é substituída ou excluída, contanto que você não especifique o número de geração da versão ativa.

    • As versões não atuais mantêm o nome do objeto, mas são identificadas exclusivamente pelo número de geração.

    • Esse tipo de versão só aparece em solicitações que chamam explicitamente as versões de objetos a serem incluídas.

  • Exclua permanentemente as versões de objetos incluindo o número de geração na solicitação de exclusão ou usando o gerenciamento do ciclo de vida de objetos.

  • As versões não atuais de objetos existem independentemente de qualquer versão ativa.

O controle de versões de um bucket pode ser ativado ou desativado a qualquer momento. Se o controle de versões for desativado, as versões de objetos atuais não serão alteradas e o bucket não acumulará mais versões de objetos não atuais.

Detalhes do controle de versões de objetos

O Cloud Storage usa duas propriedades que, juntas, identificam a versão de um objeto. Uma propriedade identifica a versão dos dados do objeto e a outra identifica a versão dos metadados. Essas propriedades estão sempre presentes em todas as versões de objetos, mesmo que o controle de versões de objetos não esteja ativado. Essas propriedades podem ser usadas como pré-condições para atualizações condicionais para impor a ordem das atualizações.

O Cloud Storage marca todos os objetos usando as seguintes propriedades:

Propriedade Descrição
generation Identifica a geração de conteúdo (dados) e atualiza quando o conteúdo de um objeto é substituído. Não há relação entre os números de geração de objetos não relacionados, mesmo que os objetos estejam no mesmo bucket.
metageneration Identifica a geração de metadados e aumenta sempre que os metadados de uma determinada geração de conteúdo são atualizados. metageneration é redefinido para 1 para cada novo generation de um objeto. A propriedade metageneration não tem significado sem a propriedade generation e só pode ser usada com ela. Em outras palavras, não faz sentido comparar gerações de metadados de duas versões que tenham gerações de dados diferentes.

O controle de versões de objetos não pode ser ativado em um bucket que tenha política de retenção.

Metadados de objeto não atual

As versões não atuais de objetos têm seus próprios metadados, que podem ser diferentes dos metadados da versão ativa. Ainda mais importante, uma versão não atual mantém as próprias ACLs e não tem necessariamente as mesmas permissões que a versão ativa.

Cada versão, ativa ou não atual, tem um conjunto de metadados. Somente o último número de metageração se refere aos metadados. Números de metageração mais antigos não podem ser usados para acessar metadados que foram alterados desde então.

É possível atualizar metadados para uma versão não atual de um objeto especificando a generation na solicitação. Para garantir uma semântica segura de leitura-modificação-gravação, é possível usar uma condição prévia de correspondência de metageração. Essa condição prévia faz com que a atualização falhe se os metadados que você está tentando atualizar foram alterados entre a hora em que você leu os metadados e a hora em que enviou a atualização.

Exemplo de controle de versões de objetos

Neste exemplo, você verá o que acontece com o arquivo cat.jpg em um bucket com controle de versões de objetos ativado conforme o arquivo é substituído, atualizado e excluído.

Upload de uma nova imagem

Ao fazer o uploadcat.jpg para o Cloud Storage pela primeira vez, ele recebe um número de generation e um número de metageneration. Neste exemplo, o número de geração é 1360887697105000. Como o objeto é novo, o número metageneration é 1.

cat.jpg recebe números generation e metageneration, mesmo que o controle de versões de objetos não esteja ativado. É possível visualizar esses números usando o comando stat na gsutil. Para ver instruções, consulte como visualizar metadados de objetos.

Ativação do controle de versões de objetos

Nesse momento, você decide ativar o controle de versões de objetos para o bucket. Isso não afeta os números generation ou metageneration de cat.jpg.

Mudança dos metadados da imagem

Para atualizar os metadados para cat.jpg adicione metadados personalizados : color:black. A atualização de metadados faz com que o valor metageneration de cat.jpg aumente, neste caso, de 1 a 2. No entanto, o objeto permanece inalterado, de modo que o Cloud Storage continua armazenando apenas uma versão de cat.jpg, e a versão continua a ter um número generation de 1360887697105000.

Upload de uma nova versão da imagem

Faça o upload de uma nova versão de cat.jpg para seu bucket do Cloud Storage. Ao fazer isso, o controle de versões de objetos move o objeto cat.jpg atual para um estado não atual. A versão não atual mantém a mesma classe de armazenamento e os mesmos metadados que tinha antes. Ela aparece apenas se você executar uma listagem com versão: ela não aparece nos comandos normais de listagem. A versão não atual agora é referenciada como: cat.jpg#1360887697105000.

Enquanto isso, a versão da imagem cat.jpg que acabou de ser enviada se torna a versão ativa do objeto. Esse nova imagem cat.jpg recebe seu próprio número de generation, que neste exemplo é 1360887759327000. Ela também recebe seus próprios metadados e um metagenerationnúmero de 1, o que significa que ele não contém os metadados color:black, a não ser que você especifique. Quando você for acessar ou modificar a imagem cat.jpg,, é esta versão que será usada. Outra opção é consultar essa versão da cat.jpg usando o númerogeneration. Por exemplo, quando usar a ferramenta gsutil, você se referirá a ela como cat.jpg#1360887759327000.

Exclusão da versão ativa da imagem

Agora, é possível excluir cat.jpg. Quando fizer isso, a versão que teve o número de geração 1360887759327000 se tornará não atual. Agora, o bucket contém duas versões não atuais de cat.jpg e nenhuma versão ativa. Ainda é possível consultar qualquer versão não atual usando o número de generation. No entanto, se tentar acessar cat.jpg sem um número de generation, ocorrerá uma falha.

Da mesma forma, uma listagem normal de objetos do bucket não mostrará cat.jpg como um dos objetos no bucket. Para mais informações sobre a listagem de versões não atuais de objetos, consulte esta página.

Desativação do controle de versões de objetos

Desative o controle de versões de objetos. Isso impede que os objetos se tornem não atuais. As versões não atuais de objetos permanecem no Cloud Storage. Mesmo que o controle de versões de objetos esteja desativado, cat.jpg#1360887697105000 e cat.jpg#1360887759327000 permanecem armazenadas no bucket até que sejam excluídas manualmente ou usando o Gerenciamento do ciclo de vida de objetos.

Restauração de uma das versões não atuais

Mesmo com o controle de versões de objetos desativado, é possível restaurar uma das versões não atuais fazendo uma cópia dela. Para isso, basta nomear a cópia como cat.jpg. Depois disso, seu bucket terá três versões da cat.jpg: as duas versões não atuais e a versão ativa que foi feita com base em uma cópia.

Referência de controle de versões de objetos

Esta tabela de referência mostra o que acontece quando você realiza determinadas ações com o controle de versões de objetos.

Status do controle de versões de objetos Ação Resultado
Desativada
Substitua dog.png por uma nova versão. A nova versão substitui a versão ativa e recebe um número da nova geração. A versão ativa antiga é excluída permanentemente.
Copiar uma versão não circulante de dog.png sobre a versão ao vivo.1 Uma cópia da versão não atual substitui a versão ativa e recebe um novo número de geração. A versão ativa antiga é excluída permanentemente.
Excluir dog.png. dog.png é excluído permanentemente.
Exclua uma versão não atual de dog.png especificando o número de geração.1 A versão não atual é excluída permanentemente.
Ativada
Substitua dog.png por uma nova versão. A nova versão substitui a versão ativa e recebe um número da nova geração. A versão ativa antiga se torna uma versão não atual e mantém o mesmo número de geração.
Copie uma versão não atual de dog.png sobre a versão ativa. Uma cópia da versão não atual substitui a versão ativa e recebe um novo número de geração. A versão ativa antiga se torna uma versão não atual e mantém o mesmo número de geração.
Exclua a versão ativa de dog.png sem especificar o número de geração. A versão ativa se torna uma versão não atual e mantém o mesmo número de geração.
Exclua a versão ativa de dog.png especificando o número de geração. A versão ativa será excluída permanentemente.
Exclua uma versão não atual de dog.png especificando o número de geração. A versão não atual é excluída permanentemente.

1 Uma versão não atual pode existir se o controle de versões de objetos tiver sido ativado anteriormente.

Dicas

Nesta seção, discutimos dicas para ajudar a trabalhar com o controle de versões de objetos com mais eficiência.

Use a gsutil

  • A ferramenta gsutil tem suporte abrangente para trabalhar com objetos com versão, o que facilita muitas tarefas que envolvem o controle de versões de objetos. Por exemplo, é possível trabalhar com versões não atuais de objetos acrescentando # e o número de generation ao nome do objeto. Para mais informações sobre como usar a gsutil com o controle de versões de objetos, consulte Controle de versões de objetos e controle de simultaneidade.

Evite ETags

  • Em vez de ETags, pense em usar os números de generation e metageneration para realizar atualizações condicionais. Juntos, os números de generation e metageneration rastreiam todas as atualizações de objetos, incluindo alterações de metadados. Esse método é mais seguro que o uso de ETags.

Entenda o comportamento de restauração de arquivos

  • É possível copiar uma versão de objeto não atual para a versão atual ativa. Para ver um guia passo a passo de como copiar versões não atuais de objetos, consulte esta página.

    Quando isso é feito com o controle de versões de objetos ativado, se já houver uma versão ativa do objeto no bucket, o Cloud Storage a substituirá e criará uma nova versão não atual do objeto substituído. Nesse caso, o bucket conterá o objeto substituído (agora não atual) e duas cópias do objeto que anteriormente era não atual (uma cópia ativa e uma cópia não atual), todos com custos de armazenamento. Para evitar cobranças desnecessárias, exclua a versão não atual usada para fazer a cópia ativa atualizada.

Use pré-condições de correspondência de geração quando for alterar versões ativas de objetos

  • Quando você usa números de geração, a solicitação funciona se houver um objeto com esse nome e número de geração, independentemente de estar ativo ou não atual. Se não houver nenhum objeto assim, o Cloud Storage retornará 404 Not Found.

  • Quando você usa pré-condições de correspondência de geração, a solicitação funciona somente se a versão ativa do objeto solicitado tiver o número de geração especificado. Se não houver nenhum objeto assim ou se for não atual, o Cloud Storage retornará 412 Precondition Failed.

  • Evite usar uma pré-condição de correspondência de geração com um número de geração no nome do objeto. Se você usar os dois e os números corresponderem, o uso da pré-condição será redundante. Se os números não corresponderem, a solicitação sempre falhará.

  • Se você fizer várias solicitações simultâneas de mutação com uma pré-condição de correspondência de geração, a consistência forte do Cloud Storage permitirá que apenas uma dessas solicitações funcione. Esse recurso é útil caso seus objetos sejam atualizados com base em várias fontes e você precise garantir que os usuários não substituam os objetos acidentalmente.

  • Se você definir uma pré-condição de correspondência de geração como 0 ao fazer o upload de um objeto, o Cloud Storage executará a solicitação especificada somente se não houver uma versão ativa do objeto. Por exemplo, se você executar uma solicitação PUT com a API XML para criar um novo objeto com o cabeçalho x-goog-if-generation-match:0, a solicitação será bem-sucedida se o objeto não existir ou se houver apenas versões não atuais do objeto. Se houver uma versão ativa do objeto, o Cloud Storage cancelará a atualização com um código de status de 412 Precondition Failed.