Como usar o controle de versão de objeto

Nesta página, você aprende a configurar o controle de versão de objeto com exemplos de utilização. Para uma descrição desse recurso, consulte Controle de versão de objeto.

Como configurar o controle de versão de objeto

Nas próximas seções, você verá como ativar e desativar o controle de versão de objeto com a ferramenta gsutil, a API JSON e a API XML. No momento, não é possível controlar o controle de versão de objeto com o Console do Google Cloud.

Como ativar o controle de versão de objeto

Observação: o controle de versão de objeto não pode ser ativado em um intervalo que atualmente tem uma política de retenção.

Para ativar o controle de versão de objeto em um intervalo:

gsutil

Use o comando gsutil versioning set on:

gsutil versioning set on gs://[BUCKET_NAME]

em que [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Crie um arquivo .json que contenha as seguintes informações:

   {
     "versioning": {
       "enabled": true
     }
   }

3. Use cURL para chamar a API JSON com uma solicitação de intervalo PATCH:

   curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=versioning"

   Em que:

   • [JSON_FILE_NAME] é o arquivo criado na Etapa 2.
   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Crie um arquivo .xml que contenha as seguintes informações:

   <VersioningConfiguration>
     <Status>Enabled</Status>
   </VersioningConfiguration>

3. Use cURL para chamar a API XML com uma solicitação de PUTIntervalo e parâmetro de string de consulta de versioning:

   curl -X PUT --data-binary @[XML_FILE_NAME].xml \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?versioning"

   Em que:

   • [XML_FILE_NAME] é o arquivo criado na Etapa 2.
   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

Quando o controle de versão de objeto está ativado, o Cloud Storage cria uma versão arquivada de um objeto sempre que a versão ativa do objeto for substituída ou excluída.

Como desativar o Controle de versão de objeto

Para desativar o Controle de versão de objeto em um intervalo:

gsutil

Use o comando gsutil versioning set off:

gsutil versioning set off gs://[BUCKET_NAME]

em que [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Crie um arquivo .json que contenha as seguintes informações:

   {
     "versioning": {
       "enabled": false
     }
   }

3. Use cURL para chamar a API JSON com uma solicitação de intervalo PATCH:

   curl -X PATCH --data-binary @[JSON_FILE_NAME].json \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Type: application/json" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=versioning"

   Em que:

   • [JSON_FILE_NAME] é o arquivo criado na Etapa 2.
   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Crie um arquivo .xml que contenha as seguintes informações:

   <VersioningConfiguration>
     <Status>Suspended</Status>
   </VersioningConfiguration>

3. Use cURL para chamar a API XML com uma solicitação de PUTIntervalo e parâmetro de string de consulta de versioning:

   curl -X PUT --data-binary @[XML_FILE_NAME].xml \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?versioning"

   Em que:

   • [XML_FILE_NAME] é o arquivo criado na Etapa 2.
   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

Como verificar se o controle de versão de objeto está ativado

Para verificar se o Controle de versão de objeto está ativado em um intervalo:

gsutil

Use o comando gsutil versioning get:

gsutil versioning get gs://[BUCKET_NAME]

em que [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

Se o controle de versão de objeto estiver ativado, a resposta será como esta:

gs://[BUCKET_NAME]: Enabled

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API JSON com uma solicitação de GET Intervalo:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]?fields=versioning"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API XML com uma solicitação de GETIntervalo e parâmetro de string de consulta de versioning:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?versioning"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

Como trabalhar com objetos com controle de versão

Nas próximas seções, você vai aprender a trabalhar com objetos com controle de versão. Para ver um exemplo detalhado de como trabalhar com o controle de versão de objetos, consulte Exemplo de controle de versão de objetos.

Como listar versões de objetos arquivados

Para listar versões ativas e arquivadas de um objeto e visualizar seus números de generation:

gsutil

Use o comando gsutil ls -a:

gsutil ls -a gs://[BUCKET_NAME]

em que [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

A resposta terá esta aparência:

gs://[BUCKET_NAME]/[OBJECT_NAME1]#[GENERATION_NUMBER1]
gs://[BUCKET_NAME]/[OBJECT_NAME1]#[GENERATION_NUMBER2]
gs://[BUCKET_NAME]/[OBJECT_NAME1]#[GENERATION_NUMBER3]
...

Observação: use a sinalização -l junto com a sinalização -a para receber os números de metageração na resposta. Use as sinalizações -L e -a para obter Archived Time para versões arquivadas de um objeto.

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API JSON com uma solicitação de LIST Objeto:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/o?versions=true"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

Versões arquivadas de objetos têm uma propriedade timeDeleted.

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API XML com uma solicitação de GETIntervalo e parâmetro de string de consulta de versions:

   curl -X GET \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]?versions"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso criado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo pertinente. Por exemplo, my-bucket.

Há algumas diferenças nos resultados da solicitação GET quando se usa o parâmetro da consulta versions e quando ele não é usado. Especificamente, o Cloud Storage retorna as seguintes informações quando um parâmetro de consulta versions é incluído na solicitação:

• Um elemento Version que contém informações sobre cada objeto.
• Um elemento DeletedTime que contém a hora em que o objeto foi arquivado (excluído ou substituído).
• Um elemento IsLatest que indica se o objeto específico é a versão mais recente
• Um elemento NextGenerationMarker será retornado se a listagem de objetos for uma listagem parcial. Isso ocorre quando você tem muitas versões de objeto em um intervalo. Use o valor desse elemento no parâmetro de consulta generationmarker das solicitações subsequentes para retomar a partir do último ponto. O parâmetro de consulta generationmarker é usado da mesma forma que o parâmetro de consulta marker para paginar uma listagem de um intervalo sem controle de versão.

Como acessar versões de objetos arquivados

Para usar a versão arquivada de um objeto ao realizar tarefas como fazer o download de um objeto, visualizar metadados ou atualizar metadados:

gsutil

1. Anexe o número de generation da versão arquivada ao nome do objeto:

   [OBJECT_NAME]#[GENERATION_NUMBER]

   Em que:

   • [OBJECT_NAME] é o nome da versão arquivada. Por exemplo, pets/dog.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada. Por exemplo, 1560468815691234.

2. Usando a string da etapa 1, continue como normalmente faria com a versão ativa do objeto.

APIs REST

API JSON

1. Anexe o número de generation da versão arquivada ao URI do objeto:

   https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?generation=[GENERATION_NUMBER]

   Em que:

   • [BUCKET_NAME] é o nome do intervalo que contém a versão arquivada. Por exemplo, my-bucket.
   • [OBJECT_NAME] é o nome da versão arquivada. Por exemplo, pets/dog.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada. Por exemplo, 1560468815691234.

2. Usando o URI da etapa 1, continue como normalmente faria com a versão ativa do objeto.

API XML

1. Anexe o número de generation da versão arquivada ao URI do objeto:

   https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]?generation=[GENERATION_NUMBER]

   Em que:

   • [BUCKET_NAME] é o nome do intervalo que contém a versão arquivada. Por exemplo, my-bucket.
   • [OBJECT_NAME] é o nome da versão arquivada. Por exemplo, pets/dog.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada. Por exemplo, 1560468815691234.

2. Usando o URI da etapa 1, continue como normalmente faria com a versão ativa do objeto.

Como copiar versões de objetos arquivados

Para copiar a versão arquivada de um objeto:

gsutil

Use o comando gsutil cp:

gsutil cp gs://[SOURCE_BUCKET_NAME]/[SOURCE_OBJECT_NAME]#[GENERATION_NUMBER] gs://[DESTINATION_BUCKET_NAME]/[DESTINATION_OBJECT_NAME]

Em que:

• [SOURCE_BUCKET_NAME] é o nome do intervalo que contém a versão arquivada que você quer copiar. Por exemplo, my-bucket.
• [SOURCE_OBJECT_NAME] é o nome da versão arquivada que você quer copiar. Por exemplo, pets/dog.png.
• [GENERATION_NUMBER] é o número de geração da versão arquivada que você quer copiar. Por exemplo, 1560468815691234.
• [DESTINATION_BUCKET_NAME] é o nome do intervalo onde você quer copiar a versão arquivada. Por exemplo, my-bucket.
• [DESTINATION_OBJECT_NAME] é o nome da cópia da versão arquivada. Por exemplo, pets/shiba.png.

Se bem-sucedida, a resposta será parecida com esta:

Operation completed over 1 objects/58.8 KiB.

Observação: alguns shells, como zsh quando a opção extendedglob está ativada, tratam o caractere hash, #, como um caractere especial. Se esse for o caso, você precisa colocar esse argumento entre aspas simples (ou aspas duplas no Windows).

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API JSON com uma solicitação de POST Objeto:

   curl -X POST \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "Content-Length: 0" \
     "https://storage.googleapis.com/upload/storage/v1/b/[SOURCE_BUCKET_NAME]/o/[SOURCE_OBJECT_NAME]/rewriteTo/b/[DESTINATION_BUCKET_NAME]/o/[NAME_OF_COPY]?sourceGeneration=[GENERATION_NUMBER]"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1.
   • [SOURCE_BUCKET_NAME] é o nome do intervalo que contém a versão arquivada que você quer copiar. Por exemplo, my-bucket.
   • [SOURCE_OBJECT_NAME] é o nome da versão arquivada que você quer copiar. Por exemplo, pets/dog.png.
   • [DESTINATION_BUCKET_NAME] é o nome do intervalo onde você quer copiar a versão arquivada. Por exemplo, my-bucket.
   • [NAME OF COPY] é o nome da cópia da versão arquivada. Por exemplo, pets/shiba.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada que você quer copiar. Por exemplo, 1560468815691234.

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API XML com uma solicitação PUT Objeto:

   curl -X PUT \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     -H "x-goog-copy-source: [SOURCE_BUCKET_NAME]/[SOURCE_OBJECT_NAME]" \
     -H "x-goog-copy-source-generation:[GENERATION_NUMBER]" \
     "https://storage.googleapis.com/[DESTINATION_BUCKET_NAME]/[NAME_OF_COPY]"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1.
   • [SOURCE_BUCKET_NAME] é o nome do intervalo que contém a versão arquivada que você quer copiar. Por exemplo, my-bucket.
   • [SOURCE_OBJECT_NAME] é o nome da versão arquivada que você quer copiar. Por exemplo, pets/dog.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada que você quer copiar. Por exemplo, 1560468815691234.
   • [DESTINATION_BUCKET_NAME] é o nome do intervalo onde você quer copiar a versão arquivada. Por exemplo, my-bucket.
   • [NAME OF COPY] é o nome da cópia da versão arquivada. Por exemplo, pets/shiba.png.

Como excluir versões de objetos arquivadas

Para excluir a versão arquivada de um objeto:

gsutil

Use o comando gsutil rm:

gsutil rm gs://[BUCKET_NAME]/[OBJECT_NAME]#[GENERATION_NUMBER]

Em que:

• [BUCKET_NAME] é o nome do intervalo que contém a versão arquivada que você quer excluir. Por exemplo, my-bucket.
• [OBJECT_NAME] é o nome da versão arquivada que você quer excluir. Por exemplo, pets/dog.png.
• [GENERATION_NUMBER] é o número de geração da versão arquivada que você quer excluir. Por exemplo, 1560468815691234.

Se bem-sucedida, a resposta será parecida com esta:

Operation completed over 1 objects.

Observação: remova todas as versões de um objeto, incluindo as ativas e arquivadas, usando a sinalização -a e omitindo o #[GENERATION_NUMBER].

APIs REST

API JSON

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API JSON com uma solicitação de DELETE Objeto:

   curl -X DELETE \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/storage/v1/b/[BUCKET_NAME]/o/[OBJECT_NAME]?generation=[GENERATION_NUMBER]"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo que contém a versão arquivada que você quer excluir. Por exemplo, my-bucket.
   • [OBJECT_NAME] é o nome da versão arquivada que você quer excluir. Por exemplo, pets/dog.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada que você quer excluir. Por exemplo, 1560468815691234.

API XML

1. Receba um token de acesso de autorização do OAuth 2.0 Playground. Configure o Playground para usar suas credenciais do OAuth.

2. Use cURL para chamar a API XML com uma solicitação DELETE Objeto:

   curl -X DELETE \
     -H "Authorization: Bearer [OAUTH2_TOKEN]" \
     "https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]?generation=[GENERATION_NUMBER]"

   Em que:

   • [OAUTH2_TOKEN] é o token de acesso gerado na Etapa 1.
   • [BUCKET_NAME] é o nome do intervalo que contém a versão arquivada que você quer excluir. Por exemplo, my-bucket.
   • [OBJECT_NAME] é o nome da versão arquivada que você quer excluir. Por exemplo, pets/dog.png.
   • [GENERATION_NUMBER] é o número de geração da versão arquivada que você quer excluir. Por exemplo, 1560468815691234.