Referências, retenção e exclusão de versões

Cada referência retida guarda o arquivo e sua versão: a origem de um registro, o modelo XLSX de um formato e o arquivo gerado por uma exportação. record_read e record_history retornam sourceFileId com sourceVersion; format_get retorna templateVersion. Leia a origem com file_read({fileId: sourceFileId, version: sourceVersion}). Os recibos de exportação continuam apontando para a versão que aquela exportação gerou. Essa referência protege a versão contra retenção e exclusão individual, mas permite apagar o arquivo de saída inteiro pela lixeira e purge; depois disso, repetir a exportação com o mesmo requestId falha com not_found. Arquivos de origem e modelos continuam protegidos contra exclusão inteira enquanto forem referenciados.

Por padrão, a empresa guarda todas as versões. Um proprietário ou administrador pode mudar versionRetention com organization_update: {keep: "all"}, {keepLast: N} para guardar as últimas N versões existentes, ou {keepDays: N} para guardar as criadas nos últimos N dias. N precisa ser um inteiro positivo. principal_get retorna a política em organization.versionRetention. A manutenção aplica a política a cada cinco minutos e sempre preserva a versão atual e todas as versões presas a referências retidas.

purge({fileId, version, confirm: true}) exclui uma versão de um arquivo ativo. Exige o criador do arquivo, um proprietário ou um administrador, além de permissão de escrita. Uma versão presa a uma referência ou a única versão do arquivo falha com conflict. Ao excluir a versão atual, a última versão anterior ainda existente passa a ser a atual, com seu conteúdo e índices. O conteúdo só é removido do armazenamento quando nenhuma versão o usa.

Os números de versão nunca são reutilizados. A retenção, a exclusão de uma versão e o cancelamento de uma exportação podem deixar lacunas no histórico; file_history lista as versões que continuam existindo. Para escrever, use sempre a versão atual como baseVersion, sem calcular o número da próxima versão.