SharePoint Online 고성능 백업 및 검증 스크립트

Microsoft Graph API와 PoshRSJob 모듈을 활용하여 SharePoint Online 문서 라이브러리를 빠르고 안전하게 로컬로 백업하고, 백업된 데이터의 무결성을 검증하는 PowerShell 스크립트.

---

✨ 주요 기능

• 🚀 고성능 병렬 다운로드: PoshRSJob 모듈을 사용해 다수의 파일을 동시에 다운로드, 백업 속도 극대화
• 🔄 지능형 재시도: 실패 파일만 자동 재시도 → 전체 스캔 없이 빠른 복구
• 🛡️ API 사용량 제한 대응: 429 Too Many Requests 오류 시 Retry-After 헤더 기반 대기 및 재시도
• 📊 실시간 모니터링: 진행률, 다운로드 속도, 경과 시간 표시
• 🔍 백업 무결성 검증: 로컬 백업과 원본 SharePoint를 비교해 누락/손상 여부 확인
• 📂 파일/폴더명 정제: 한글, 공백, 특수문자 포함된 이름 안전 변환
• 📑 종합 보고서: 용량 분석 포함 결과 로그 생성

---

📋 필수 요구사항

1. PowerShell 7.2 이상
2. PowerShell 모듈
   • Microsoft.Graph
   • PoshRSJob
3. Microsoft Graph 권한: Sites.Read.All

---

🛠️ 설치 및 초기 설정

1. PowerShell 7 설치

공식 PowerShell GitHub 릴리스 페이지에서 최신 버전 설치.

2. 필수 모듈 설치

Install-Module Microsoft.Graph -Scope CurrentUser -Force
Install-Module PoshRSJob -Scope CurrentUser -Force

🔹 PoshRSJob 모듈 설명

ForEach-Object -Parallel 대비 안정적인 병렬 작업 관리와 상태 추적을 지원하는 고성능 병렬 처리 모듈. 대규모 파일 다운로드에서 권장되는 사실상 표준.

🔹 PoshRSJob 수동 설치

네트워크/캐시 문제로 Install-Module이 실패할 경우:

1. 캐시 삭제 후 재시도:

   Remove-Item -Path "$env:LOCALAPPDATA\NuGet\Cache\*" -Recurse -Force -ErrorAction SilentlyContinue
   

2. PowerShell Gallery에서 .nupkg 다운로드

3. 파일 속성 → 차단 해제(Unblock) 체크

4. 확장자 .zip으로 변경 후 압축 해제

5. 모듈 경로(($env:PSModulePath -split ';')[0])에 PoshRSJob 폴더 생성 후 복사

   • 예: C:\Users\<User>\Documents\PowerShell\Modules\PoshRSJob\

6. 설치 확인:

   Get-Module -ListAvailable PoshRSJob
   

3. Microsoft Graph 최초 연결

Connect-MgGraph -Scopes "Sites.Read.All"

---

🚀 사용법

1. 백업 스크립트

.\Backup-SPO-PoshRSJob.ps1 -SiteUrl "https://tenant.sharepoint.com/sites/SiteName"

• ThrottleLimit으로 병렬 다운로드 개수 조정 (기본값 3, 권장 1~3)
• 실패 시 _failed_files.json 기반 자동 이어받기 지원

2. 검증 스크립트

.\Verify-SPO-Backup.ps1 -SiteUrl "https://tenant.sharepoint.com/sites/SiteName" -BackupPath "D:\Backups\SharePoint"

---

📊 보고서 예시

==================================================
 SharePoint 백업 결과 보고서 (PoshRSJob)
==================================================
 > 백업 일시   : 2025-08-20 13:31:22
 > 대상 사이트 : https://oneunivrs.sharepoint.com/sites/Anvil
 > 저장 위치   : F:\action_anvil
--------------------------------------------------
 [ 사이트 저장소 현황 ]
   - 전체 할당량 (Quota)      : 100.00 GB
   - 실제 총 사용량            : 101.01 GB
   - 현재 파일 총 용량          : 98.53 GB
   - 기타 용량 (버전 기록 등)     : 2.48 GB
--------------------------------------------------
 [ 백업된 파일 정보 ]
   - 스캔된 총 폴더 수 : 264 개
   - 스캔된 총 파일 수 : 2612 개
--------------------------------------------------
 [ 백업 작업 결과 ]
   - ✅ 성공           : 2612 개
   - ⏩ 건너뜀         : 0 개
   - ❌ 실패           : 0 개
   - ⏱️ 총 소요 시간   : 00:47:51
   - ↓ 실제 평균 속도 : 34.30 MB/s
==================================================

---

💡 문제 해결 및 고급 주제 (Troubleshooting & Advanced Topics)

1. API 사용량 제한 (429 오류)

• 문제: 대용량 다운로드 시 Too Many Requests 발생

• 해결:

  • Retry-After 헤더 기반 대기 후 재시도
  • 점진적 대기 (5초, 10초, 15초...) 적용

• 팁: -ThrottleLimit 값은 1~2 권장

2. 왜 PoshRSJob 인가?

• ForEach-Object -Parallel은 공유 변수 전달 시 오류 발생
• PoshRSJob은 Job 기반 격리 실행, 상태 추적과 안정성 우수

3. 파일 이름 문제

• Windows 불가 문자를 _로 치환 (예: : → _)
• 모든 파일 작업에 -LiteralPath 적용

4. 대용량(>2GB) 처리

• PowerShell 기본 Int32 한계로 오류 발생
• 모든 파일 크기 계산을 [long] 타입으로 변환해 테라바이트 단위 지원

---