Arquivos

Envie, organize e recupere arquivos da organização.

Os arquivos pertencem à organização e permanecem nela quando seus membros mudam. Peça ao agente para enviar documentos e planilhas e organizar o acesso em pastas.

Cota de armazenamento

O espaço da organização está em Ativação e limites. Os dados processados para consulta de planilhas têm uma cota separada.

• limitBytes: capacidade de armazenamento da organização.
• usedBytes: arquivos ativos e na lixeira. Os bytes são liberados após a exclusão definitiva.
• reservedBytes: espaço reservado por uploads em andamento.
• Espaço disponível: limitBytes - usedBytes - reservedBytes.

Mover um arquivo para a lixeira mantém seus bytes contabilizados. Restaurá-lo durante o prazo de recuperação não consome espaço adicional.

Envio pelo agente

O agente envia cada arquivo por MCP neste fluxo:

1. Reserve o envio com upload_begin. Informe requestId, name, mediaType e size, além do destino quando necessário. O servidor confere a cota, reserva o tamanho declarado e devolve o envio e transfer: um link de uso único (url), o cabeçalho Upload-Token e command, um curl pronto.
2. Envie o arquivo. O agente roda transfer.command no terminal, com FILE trocado pelo caminho local. O PUT leva só o Upload-Token, nunca o token da conexão. A resposta é o envio concluído (kind: "completed"); o id do arquivo é file.id. O servidor confere o tamanho, ativa o arquivo e converte o espaço reservado em usado. Repetir o PUT depois de concluído devolve o mesmo arquivo.
3. Acima de 64 MiB, envie em partes. Mande cada parte de 8 MiB (8.388.608 bytes) com PUT {url}?part=N, N de 1 em diante; a última parte leva o restante. O envio termina quando a última parte chega.

O link vale por uma hora (até transfer.expiresAt) e age como a conexão que o criou: se ela for revogada ou a pessoa sair da organização, o link para de funcionar. Chamar upload_begin de novo com o mesmo requestId devolve um link novo para o mesmo envio. São permitidas até 10.000 partes: no máximo 83.886.080.000 bytes por arquivo (78,125 GiB), dentro do espaço disponível da organização.

No Codex, o curl precisa de rede; veja Conectar Codex.

Use o mesmo requestId (até 200 caracteres) ao repetir uma tentativa. Outro nome, destino ou tamanho com a mesma chave falha com conflict; em file_write e sheet_write, outros bytes também entram nessa verificação. upload_cancel cancela um envio inacabado e libera a reserva. Uploads abandonados expiram e são limpos automaticamente.

Cada ferramenta lista seus parâmetros completos no schema de entrada; veja MCP.

Lixeira e recuperação

trash move um arquivo ativo para a lixeira por 30 dias. Ele sai da listagem padrão e aparece em list com state: "trash".

restore recupera o arquivo antes de recover_until. Pelo MCP, exige files:write e acesso de escrita ao item. Após o prazo, a restauração fica indisponível e a limpeza automática exclui os dados.

Nenhum agente apaga um item na hora: qualquer membro com acesso de escrita move para a lixeira e restaura, e a Siglata apaga o item 30 dias depois, liberando os bytes após a remoção dos dados armazenados. activity_list registra quem moveu o item, por qual agente e quando, e também o apagamento.

Renomear e baixar

rename altera o nome sem copiar o conteúdo ou consumir mais espaço.

file_read devolve o conteúdo na resposta até 128 KiB e dois caminhos de download:

• link: endereço do Console para uma pessoa autenticada abrir no navegador.
• transfer: um link de uso único para o próprio agente salvar o arquivo, com o cabeçalho Download-Token e command, um curl pronto que grava o arquivo com o nome dele na pasta de trabalho. O link vale por 10 minutos e serve um único download.

O download age como a conexão que chamou file_read: antes de enviar os bytes, ele confere a conexão, o vínculo com a organização e o acesso ao arquivo, e fica registrado na Atividade.

Pastas e Controle de Acesso

Arquivos podem residir em pastas aninhadas, e cada arquivo e pasta carrega um atributo visibility:

• org (padrão): Os membros podem acessá-lo, respeitando as restrições das pastas e os escopos OAuth. A escrita no espaço da empresa também exige as permissões descritas lá.
• restricted: Somente o criador do objeto, membros owner/admin da organização e membros com concessão explícita, direta ou por uma equipe da qual fazem parte, podem acessar o objeto.

Uma pasta restrita restringe toda a sua subárvore: para ler ou gravar um objeto, o chamador precisa satisfazer cada pasta restrita na cadeia de ancestrais. Uma concessão em uma pasta se estende aos seus descendentes irrestritos, enquanto um objeto restrito dentro de uma pasta compartilhada ainda exige sua própria concessão.

• Operações negadas falham com o código de erro forbidden; objetos restritos que um membro não pode ler também são omitidos dos resultados de list.
• grant_set é limitado ao criador do objeto e a administradores da organização; define o nível de um beneficiário, e level: null o revoga. As operações de compartilhamento existem só para organizações Empresas.
• Uma concessão vai para um membro (granteeType: "user") ou para uma equipe (granteeType: "team") da organização; qualquer outro id falha com invalid_input. A concessão de uma equipe vale para quem é membro dela a cada requisição: quem sai da equipe perde o acesso na requisição seguinte. Com uma concessão direta e outra por equipe, vale o nível mais alto.
• set_visibility, como grant_set, é limitado ao criador do objeto e a administradores da organização; uma concessão de escrita não basta. Não altera concessões existentes.
• move e upload_begin em uma pasta requerem acesso de escrita à pasta de destino.
• Mover uma pasta para a lixeira não move seu conteúdo; quando uma pasta na lixeira ultrapassa o prazo de recuperação, ela é excluída e seus filhos voltam para a raiz da organização.