Gerenciar versões históricas de arquivos - PDS - Drive and Photo Service: Central de Documentação do Alibaba Cloud

Conceitos principais

Em um espaço pessoal ou drive corporativo, arquivos e pastas seguem uma estrutura de árvore.

Pastas não possuem versões. Todo arquivo tem pelo menos uma versão.
Criar um novo arquivo ou editar um existente gera uma nova versão.
Um arquivo recém-criado possui apenas uma versão.
Editar ou sobrescrever um arquivo existente cria uma nova versão.
Sem o recurso de multiversão ativo, o sistema mantém apenas a versão mais recente do arquivo.
Com a multiversão ativada, criar uma nova versão converte a atual em histórica. As regras configuradas definem o total de versões históricas retidas.
Versões históricas consomem espaço de armazenamento no drive.

Recursos

O backup multiversão salva todas as versões dos seus arquivos. Restaure qualquer arquivo para um estado anterior caso seja sobrescrito ou modificado acidentalmente.
Editar ou substituir um arquivo cria uma versão histórica. Liste, visualize, restaure, exclua e descreva essas versões.
Configure um período de retenção de 1 a 999 dias ou mantenha as versões indefinidamente. Mescla automática de versões criadas em um período específico reduz a proliferação de versões.
Defina o número máximo de versões retidas entre 1 e 999. Marque até 50 versões para retenção permanente e proteja-as contra exclusão por limites de tempo ou quantidade.

Pré-requisitos

Domínio do PDS Developer Edition criado.
Apenas superadministradores ou administradores de drive podem ativar este recurso.
BasicUI ativado.

Ativar versões históricas

Faça login no BasicUI e acesse o admin console.
No painel de navegação à esquerda, escolha Enterprise Settings > File Settings.
Ative a chave Historical Version.

Configuração de versão histórica

À direita de Historical Version, clique em Edit para modificar a configuração.

Parâmetro	Descrição
Merge file historical versions	Ativado por padrão. Vários salvamentos em um período de 10 minutos (edição online, sincronização de arquivos) são mesclados em uma única versão histórica. Se desativado, cada salvamento cria uma nova versão histórica.
Version count limit	Especifique um número inteiro de 1 a 999 como limite máximo de versões históricas. O sistema exclui automaticamente versões históricas que excedem esse limite, exceto as marcadas para retenção permanente. Ajuda a controlar custos de armazenamento ao limitar a quantidade de versões retidas.
Retention period	Defina um número inteiro de 1 a 999 para o período de retenção em dias. O sistema exclui automaticamente versões históricas que ultrapassam o período de retenção, exceto as com retenção permanente. Permite controlar custos de armazenamento ao limitar o tempo de retenção das versões.

Fluxo e exemplos de chamadas de API

Gerar uma nova versão

Ao fazer upload de um arquivo pela primeira vez, ele possui apenas uma versão. Sobrescrever o arquivo gera uma nova versão.

Para sobrescrever um arquivo, chame a operação CreateFile com file_id definido como o ID do arquivo de destino. O restante do processo de upload segue o fluxo descrito em Upload a file.

Listar versões históricas

Chame a operação ListRevision para obter uma lista paginada das versões de um arquivo. As versões retornam em ordem cronológica inversa.

Exemplo de solicitação:

{
	"drive_id":"testDriveId",
	"file_id": "testFileId"
}

Exemplo de resposta:

{
	"items": [{
		"domain_id": "testDomainId",
		"drive_id": "testDriveId",
		"file_id": "testFileId",
		"revision_id": "testRevisionId",
		"revision_name": "history_version.xlsx",
		"file_extension": "xlsx",
		"size": 8493,
		"revision_version": 2,
		"keep_forever": false,
		"revision_description": "",
		"revision_create_reason": "overwrite",
		"content_hash_name": "sha1",
		"content_hash": "xxxxxx",
		"crc64_hash": "xxxxxx",
		"created_at": "2022-09-05T04:00:09.017Z",
		"updated_at": "2022-09-05T04:00:09.017Z",
		"creator_type": "User",
		"creator_id": "testCreatorId",
		"is_latest_version": true
	}],
	"next_marker": ""
}

Descrição dos campos:

drive_id: ID do espaço pessoal ou drive corporativo.
file_id: ID do arquivo. Não pode ser ID de pasta.
next_marker: Token de paginação. Passe este valor como parâmetro marker na próxima solicitação. Valor vazio indica a última página.
revision_version: Número da versão. Um número menor indica uma versão mais antiga.
revision_create_reason: Motivo da criação da versão. Valores válidos:
- "" (string vazia): Arquivo criado.
- "overwrite": Arquivo sobrescrito.
- "restore_rev": Versão histórica restaurada.
is_latest_version: Indica se esta é a versão mais recente do arquivo.
revision_name: Nome da versão. A versão mais recente compartilha o nome do arquivo. O nome de uma versão histórica é fixo após a criação.

Obter detalhes da versão

Use a operação GetRevision para obter detalhes de uma única versão. Diferentemente da resposta de ListRevision, a resposta de GetRevision inclui uma URL de download.

Exemplo de solicitação:

{
	"drive_id":"testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId"
}

Exemplo de resposta:

{
	"domain_id": "testDomainId",
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"revision_name": "history_version.xlsx",
	"file_extension": "xlsx",
	"size": 8493,
	"revision_version": 2,
	"keep_forever": false,
	"revision_description": "",
	"revision_create_reason": "overwrite",
	"content_hash_name": "sha1",
	"content_hash": "xxxxxx",
	"crc64_hash": "xxxxxx",
	"created_at": "2022-09-05T04:00:09.017Z",
	"updated_at": "2022-09-05T04:00:09.017Z",
	"creator_type": "User",
	"creator_id": "testCreatorId",
	"is_latest_version": true,
	"download_url": "testDownloadUrl"
}

Atualizar propriedades da versão

Chame a operação UpdateRevision para atualizar as propriedades de uma versão.

Marcar uma versão para retenção permanente

Importante

Marque até 50 versões para retenção permanente. Versões assim marcadas não são excluídas mesmo que excedam os limites de período de retenção ou quantidade.
Para excluir uma versão com retenção permanente, chame a operação DeleteRevision.
Excluir permanentemente um arquivo também remove todas as suas versões, inclusive as com retenção permanente.

Exemplo de solicitação:

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"keep_forever": true
}

Cancelar retenção permanente

Exemplo de solicitação:

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"keep_forever": false
}

Definir descrição da versão

Exemplo de solicitação:

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId",
	"revision_description": "this is a revision"
}

Restaurar uma versão histórica

Importante

Esta operação não restaura a versão mais recente de um arquivo.
Restaurar uma versão histórica cria uma nova versão baseada nela. A versão histórica original permanece inalterada. O usuário que executa a restauração torna-se o criador da nova versão. Para liberar espaço de armazenamento, chame a operação DeleteRevision.

Chame a operação RestoreRevision para restaurar uma versão histórica e torná-la a versão mais recente do arquivo.

Exemplo de solicitação:

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId"
}

Excluir uma versão histórica

Importante

Esta operação não exclui a versão mais recente de um arquivo.

Use a operação DeleteRevision para excluir uma versão histórica e liberar o espaço de armazenamento ocupado.

Exemplo de solicitação:

{
	"drive_id": "testDriveId",
	"file_id": "testFileId",
	"revision_id": "testRevisionId"
}

Perguntas frequentes

Mesclar versões históricas de arquivos

Quando ativado, vários salvamentos em uma janela de 10 minutos são mesclados, mantendo apenas o último como versão histórica. A janela de 10 minutos usa intervalos fixos, como 10:00-10:10 e 10:10-10:20.
Com este recurso desativado, cada salvamento (automático ou manual) gera uma nova versão histórica.

Retenção da primeira versão

Não. A primeira versão, gerada na criação do arquivo, está sujeita ao período de retenção configurado e aos limites de contagem de versões.
Quando a primeira versão de um arquivo se torna histórica, ela será excluída se exceder o período de retenção.
Se o total de versões exceder o limite configurado, o sistema exclui primeiro as versões mais antigas, o que pode incluir a primeira versão. Para manter uma versão específica, marque-a para retenção permanente pela interface ou chamando a operação UpdateRevision.
O mecanismo de limpeza de versões não exclui a versão mais recente de um arquivo.

Desativar versões históricas

Não é possível desativar este recurso após a ativação. Para obter efeito semelhante, defina o número máximo de versões históricas como 1.