Como Recuperar um Arquivo da Lixeira da Nuvem via PowerShell

Quando você exclui um arquivo de uma pasta sincronizada na nuvem, como OneDrive ou SharePoint, o arquivo vai para a lixeira da nuvem em vez de ser removido permanentemente. A forma padrão de restaurá-lo é pela interface web, mas esse processo se torna lento e sujeito a erros quando você precisa recuperar muitos arquivos ou automatizar a tarefa. O PowerShell fornece um método direto e scriptável para recuperar arquivos da lixeira da nuvem sem abrir um navegador. Este artigo explica como usar o SharePoint Online Management Shell e o cmdlet Restore-PnPRecycleBinItem para recuperar um arquivo da lixeira da nuvem.

Entendendo a Lixeira da Nuvem e as Opções de Recuperação com PowerShell

A lixeira da nuvem no Microsoft 365 consiste em dois estágios. A lixeira de primeiro estágio retém itens excluídos por 93 dias para a maioria dos usuários. Quando um usuário exclui um item da lixeira de primeiro estágio, ou quando o período de retenção expira, o item vai para a lixeira de segundo estágio, também chamada de lixeira da coleção de sites. A lixeira de segundo estágio retém itens por mais 93 dias, dando aos administradores um total de 186 dias para recuperar um arquivo excluído.

A interface web da lixeira funciona bem para recuperar um ou dois arquivos. No entanto, quando você precisa recuperar dezenas de arquivos, restaurar arquivos com base em um intervalo de datas específico ou scriptar o processo de recuperação para vários sites, o PowerShell se torna a ferramenta prática. O SharePoint Online Management Shell, construído sobre o módulo PnP PowerShell, expõe a lixeira como uma coleção de objetos que você pode consultar, filtrar e restaurar programaticamente.

Antes de começar, verifique se você tem o módulo PnP PowerShell instalado. Você precisa da função de Administrador do SharePoint ou, no mínimo, de permissões de proprietário no site onde o arquivo foi excluído. Os comandos neste artigo funcionam tanto para bibliotecas de documentos do SharePoint Online quanto para sites do OneDrive for Business.

Passos para Recuperar um Arquivo da Lixeira da Nuvem Usando PowerShell

Siga estes passos para conectar ao seu site, localizar o arquivo excluído na lixeira e restaurá-lo para sua localização original.

1. Instale o módulo PnP PowerShell
   Abra o Windows PowerShell como administrador. Execute Install-Module PnP.PowerShell -Scope CurrentUser. Se você já tiver o módulo instalado, execute Update-Module PnP.PowerShell para garantir a versão mais recente. Pressione Y para confirmar a instalação quando solicitado.
2. Conecte-se ao seu site do SharePoint ou OneDrive
   Execute Connect-PnPOnline -Url "https://sualocatario.sharepoint.com/sites/seunome" -Interactive. Substitua a URL pela URL da sua coleção de sites. Para OneDrive, use o formato https://sualocatario-my.sharepoint.com/personal/usuario_dominio_com. Uma caixa de diálogo de login será aberta. Insira suas credenciais do Microsoft 365 e conclua quaisquer prompts de autenticação multifator.
3. Liste todos os itens na lixeira de primeiro estágio
   Execute Get-PnPRecycleBinItem | Select-Object Id, Title, DirName, DeletedDate. Este comando retorna todos os itens na lixeira de primeiro estágio. A saída mostra o ID exclusivo, nome do arquivo, caminho da pasta original e carimbo de data/hora da exclusão para cada item. Anote o Id do arquivo que você deseja recuperar.
4. Filtre a lista da lixeira para encontrar o arquivo desejado
   Execute Get-PnPRecycleBinItem | Where-Object {$_.Title -eq "Relatorio.xlsx"} | Select-Object Id, Title, DirName, DeletedDate. Substitua Relatorio.xlsx pelo nome real do seu arquivo. Se o nome do arquivo incluir espaços, coloque-o entre aspas. Este filtro retorna apenas itens que correspondem exatamente ao nome do arquivo. Para pesquisar por nome parcial, use -like "Relatorio" em vez de -eq.
5. Restaure o arquivo da lixeira
   Execute Get-PnPRecycleBinItem | Where-Object {$_.Title -eq "Relatorio.xlsx"} | Restore-PnPRecycleBinItem. Este comando canaliza o item da lixeira filtrado diretamente para o cmdlet de restauração. O arquivo retorna para sua pasta original. Você verá uma mensagem de confirmação no console mostrando o nome do arquivo restaurado.
6. Verifique se o arquivo foi restaurado
   Execute Get-PnPFile -Url "Documentos Compartilhados/Relatorio.xlsx". Substitua o caminho da URL pela localização original da pasta do seu arquivo. Se o arquivo existir, o comando retornará suas propriedades. Você também pode abrir o site em um navegador e navegar até a pasta original para confirmar que o arquivo está presente.

Se o arquivo não estiver na lixeira de primeiro estágio, ele pode estar na lixeira de segundo estágio. Execute Get-PnPRecycleBinItem -SecondStage para listar itens na lixeira de segundo estágio. Use os mesmos comandos de filtro e restauração com o parâmetro -SecondStage.

Problemas Comuns ao Recuperar Arquivos da Lixeira da Nuvem via PowerShell

“Acesso Negado” ao Executar Get-PnPRecycleBinItem

Este erro ocorre quando sua conta não tem permissões suficientes no site. Você precisa, no mínimo, da função de Proprietário na coleção de sites ou da função de Administrador do SharePoint no nível do locatário. Entre em contato com o administrador do locatário para solicitar as permissões necessárias. Após a concessão das permissões, execute Disconnect-PnPOnline e reconecte usando Connect-PnPOnline com a mesma URL.

“O termo ‘Restore-PnPRecycleBinItem’ não é reconhecido”

Este erro significa que o módulo PnP PowerShell não está carregado ou está desatualizado. Execute Import-Module PnP.PowerShell -Force para carregar o módulo. Se o erro persistir, execute Get-Module -ListAvailable PnP.PowerShell para verificar se o módulo está instalado. Se não estiver listado, instale-o usando o comando do Passo 1 acima.

Arquivo Restaurado no Local Errado ou Não Restaurado

Este problema acontece quando a lixeira contém vários itens com o mesmo nome de arquivo em pastas diferentes. O filtro Where-Object deve incluir tanto o nome do arquivo quanto o caminho da pasta original. Use $_.Title -eq "Relatorio.xlsx" -and $_.DirName -eq "Documentos Compartilhados/Financeiro" para direcionar o item correto. Se o comando de restauração for executado sem erro, mas o arquivo não aparecer, verifique a lixeira de segundo estágio. O arquivo pode ter sido excluído da lixeira de primeiro estágio e movido para a lixeira de segundo estágio.

A Sessão do PowerShell Expira Durante a Restauração

Operações de restauração longas podem expirar se a conexão ficar ociosa. Use o parâmetro -KeepConnection ao chamar Restore-PnPRecycleBinItem. Este parâmetro mantém a sessão ativa até que a restauração seja concluída. Alternativamente, restaure itens em lotes menores filtrando por data em vez de restaurar todos os itens de uma vez.

Recuperação via PowerShell vs Interface Web

Item	Método PowerShell	Método Interface Web
Tempo de configuração	Requer instalação do módulo e autenticação	Nenhuma configuração necessária
Recuperação em lote	Suporta filtragem e restauração de vários arquivos em um único comando	Seleção manual de cada arquivo
Filtragem por data	Use Where-Object {$_.DeletedDate -gt "2025-01-01"}	Nenhum filtro de data disponível
Recuperação de segundo estágio	Use o parâmetro -SecondStage	Navegue até a lixeira da coleção de sites
Suporte a automação	Scriptável com tarefas agendadas ou Azure Automation	Não automatizável
Requisito de permissão	Proprietário do site ou Administrador do SharePoint	Proprietário do site ou membro com permissões de exclusão

O método PowerShell economiza tempo considerável quando você precisa recuperar arquivos de vários sites ou restaurar itens com base em critérios complexos, como data de exclusão e caminho da pasta original. A interface web continua mais rápida para recuperações de arquivo único quando você já tem o site aberto no navegador.

Agora você pode recuperar arquivos da lixeira da nuvem usando comandos PowerShell em vez de navegar pela interface web. Comece instalando o módulo PnP PowerShell e conectando-se ao seu site com Connect-PnPOnline. Para tarefas recorrentes de recuperação, salve os comandos de filtro e restauração em um arquivo .ps1 e execute-o conforme necessário. Uma dica avançada é combinar Get-PnPRecycleBinItem com um filtro de intervalo de datas para restaurar automaticamente todos os arquivos excluídos nas últimas 24 horas, o que é útil para reverter exclusões em massa acidentais.