Cómo recuperar un archivo de la papelera de reciclaje en la nube mediante powershell

Cuando elimina un archivo de una carpeta en la nube sincronizada, como OneDrive o SharePoint, el archivo se mueve a la papelera de reciclaje en la nube en lugar de eliminarse permanentemente. La forma estándar de restaurarlo es a través de la interfaz web, pero ese proceso se vuelve lento y propenso a errores cuando necesita recuperar muchos archivos o automatizar la tarea. PowerShell proporciona un método directo y programable para recuperar archivos de la papelera de reciclaje en la nube sin abrir un navegador. Este artículo explica cómo usar SharePoint Online Management Shell y el cmdlet Restore-PnPRecycleBinItem para recuperar un archivo de la papelera de reciclaje en la nube.

Descripción de la papelera de reciclaje en la nube y las opciones de recuperación con PowerShell

La papelera de reciclaje en la nube de Microsoft 365 consta de dos etapas. La papelera de reciclaje de primera etapa conserva los elementos eliminados durante 93 días para la mayoría de los usuarios. Cuando un usuario elimina un elemento de la papelera de reciclaje de primera etapa, o cuando expira el período de retención, el elemento se mueve a la papelera de reciclaje de segunda etapa, también llamada papelera de reciclaje de la colección de sitios. La papelera de reciclaje de segunda etapa conserva los elementos durante 93 días adicionales, lo que brinda a los administradores un total de 186 días para recuperar un archivo eliminado.

La interfaz web de la papelera de reciclaje funciona bien para recuperar uno o dos archivos. Sin embargo, cuando necesita recuperar docenas de archivos, restaurar archivos según un rango de fechas específico o programar el proceso de recuperación para varios sitios, PowerShell se convierte en la herramienta práctica. SharePoint Online Management Shell, basado en el módulo PnP PowerShell, expone la papelera de reciclaje como una colección de objetos que puede consultar, filtrar y restaurar mediante programación.

Antes de comenzar, verifique que tiene instalado el módulo PnP PowerShell. Necesita el rol de Administrador de SharePoint o al menos permisos de propietario a nivel de sitio en el sitio donde se eliminó el archivo. Los comandos de este artículo funcionan tanto para bibliotecas de documentos de SharePoint Online como para sitios de OneDrive para la Empresa.

Pasos para recuperar un archivo de la papelera de reciclaje en la nube con PowerShell

Siga estos pasos para conectarse a su sitio, localizar el archivo eliminado en la papelera de reciclaje y restaurarlo a su ubicación original.

1. Instale el módulo PnP PowerShell
   Abra Windows PowerShell como administrador. Ejecute Install-Module PnP.PowerShell -Scope CurrentUser. Si ya tiene el módulo instalado, ejecute Update-Module PnP.PowerShell para asegurarse de tener la versión más reciente. Presione Y para confirmar la instalación cuando se le solicite.
2. Conéctese a su sitio de SharePoint o OneDrive
   Ejecute Connect-PnPOnline -Url "https://yourtenant.sharepoint.com/sites/yoursite" -Interactive. Reemplace la URL con la URL de su colección de sitios. Para OneDrive, use el formato https://yourtenant-my.sharepoint.com/personal/user_domain_com. Se abre un cuadro de diálogo de inicio de sesión. Ingrese sus credenciales de Microsoft 365 y complete cualquier solicitud de autenticación multifactor.
3. Enumere todos los elementos de la papelera de reciclaje de primera etapa
   Ejecute Get-PnPRecycleBinItem | Select-Object Id, Title, DirName, DeletedDate. Este comando devuelve todos los elementos de la papelera de reciclaje de primera etapa. La salida muestra el ID único, el nombre del archivo, la ruta de la carpeta original y la marca de tiempo de eliminación de cada elemento. Anote el Id del archivo que desea recuperar.
4. Filtre la lista de la papelera de reciclaje para encontrar su archivo de destino
   Ejecute Get-PnPRecycleBinItem | Where-Object {$_.Title -eq "Report.xlsx"} | Select-Object Id, Title, DirName, DeletedDate. Reemplace Report.xlsx con el nombre real de su archivo. Si el nombre del archivo incluye espacios, enciérrelo entre comillas. Este filtro devuelve solo los elementos que coinciden con el nombre exacto del archivo. Para buscar por nombre parcial, use -like "Report" en lugar de -eq.
5. Restaure el archivo desde la papelera de reciclaje
   Ejecute Get-PnPRecycleBinItem | Where-Object {$_.Title -eq "Report.xlsx"} | Restore-PnPRecycleBinItem. Este comando canaliza el elemento filtrado de la papelera de reciclaje directamente al cmdlet de restauración. El archivo vuelve a su ubicación de carpeta original. Verá un mensaje de confirmación en la consola que muestra el nombre del archivo restaurado.
6. Verifique que el archivo se haya restaurado
   Ejecute Get-PnPFile -Url "Shared Documents/Report.xlsx". Reemplace la ruta de la URL con la ubicación de la carpeta original de su archivo. Si el archivo existe, el comando devuelve sus propiedades. También puede abrir el sitio en un navegador y navegar a la carpeta original para confirmar que el archivo está presente.

Si el archivo no está en la papelera de reciclaje de primera etapa, puede estar en la papelera de reciclaje de segunda etapa. Ejecute Get-PnPRecycleBinItem -SecondStage para enumerar los elementos de la papelera de reciclaje de segunda etapa. Use los mismos comandos de filtro y restauración con el parámetro -SecondStage.

Problemas comunes al recuperar archivos de la papelera de reciclaje en la nube mediante PowerShell

“Acceso denegado” al ejecutar Get-PnPRecycleBinItem

Este error ocurre cuando su cuenta no tiene permisos suficientes en el sitio. Necesita al menos el rol Propietario en la colección de sitios o el rol Administrador de SharePoint a nivel de inquilino. Comuníquese con el administrador de su inquilino para solicitar los permisos necesarios. Una vez otorgados los permisos, ejecute Disconnect-PnPOnline y luego vuelva a conectarse usando Connect-PnPOnline con la misma URL.

“No se reconoce el término ‘Restore-PnPRecycleBinItem'”

Este error significa que el módulo PnP PowerShell no está cargado o está desactualizado. Ejecute Import-Module PnP.PowerShell -Force para cargar el módulo. Si el error persiste, ejecute Get-Module -ListAvailable PnP.PowerShell para verificar si el módulo está instalado. Si no aparece en la lista, instálelo usando el comando del Paso 1 anterior.

Archivo restaurado en la ubicación incorrecta o no restaurado en absoluto

Este problema ocurre cuando la papelera de reciclaje contiene varios elementos con el mismo nombre de archivo en carpetas diferentes. El filtro Where-Object debe incluir tanto el nombre del archivo como la ruta de la carpeta original. Use $_.Title -eq "Report.xlsx" -and $_.DirName -eq "Shared Documents/Finance" para apuntar al elemento correcto. Si el comando de restauración se ejecuta sin errores pero el archivo no aparece, revise la papelera de reciclaje de segunda etapa. Es posible que el archivo se haya eliminado de la papelera de reciclaje de primera etapa y se haya movido a la papelera de segunda etapa.

La sesión de PowerShell agota el tiempo de espera durante la restauración

Las operaciones de restauración de larga duración pueden agotar el tiempo de espera si la conexión está inactiva. Use el parámetro -KeepConnection al llamar a Restore-PnPRecycleBinItem. Este parámetro mantiene la sesión activa hasta que finaliza la restauración. Como alternativa, restaure los elementos en lotes más pequeños filtrando por fecha en lugar de restaurar todos los elementos a la vez.

Recuperación de la papelera de reciclaje con PowerShell frente a la recuperación con la interfaz web

Navegue a la papelera de reciclaje de la colección de sitios

Elemento	Método de PowerShell	Método de la interfaz web
Tiempo de configuración	Requiere instalación del módulo y autenticación	No requiere configuración
Recuperación por lotes	Admite filtrar y restaurar varios archivos en un solo comando	Selección manual de cada archivo
Filtrado por fecha	Use Where-Object {$_.DeletedDate -gt "2025-01-01"}	No hay filtro de fecha disponible
Recuperación de segunda etapa	Use el parámetro -SecondStage
Compatibilidad con automatización	Se puede programar con tareas programadas o Azure Automation	No es automatizable
Requisito de permisos	Propietario del sitio o Administrador de SharePoint	Propietario o miembro del sitio con permisos de eliminación

El método de PowerShell ahorra mucho tiempo cuando necesita recuperar archivos de varios sitios o restaurar elementos según criterios complejos, como la fecha de eliminación y la ruta de la carpeta original. La interfaz web sigue siendo más rápida para recuperaciones de un solo archivo cuando ya tiene el sitio abierto en un navegador.

Ahora puede recuperar archivos de la papelera de reciclaje en la nube usando comandos de PowerShell en lugar de navegar por la interfaz web. Comience instalando el módulo PnP PowerShell y conectándose a su sitio con Connect-PnPOnline. Para tareas de recuperación recurrentes, guarde los comandos de filtro y restauración en un archivo de script .ps1 y ejecútelo cuando sea necesario. Un consejo avanzado es combinar Get-PnPRecycleBinItem con un filtro de rango de fechas para restaurar automáticamente todos los archivos eliminados en las últimas 24 horas, lo cual es útil para revertir eliminaciones masivas accidentales.