Python으로 안전한 Google Drive–OneDrive 전송 구축하기

간단한 답변

관리형 마이그레이션의 경우 FileArk는 사용자의 컴퓨터를 데이터 전송 경로로 사용하지 않고 이 워크플로를 자동화합니다. 수 테라바이트 규모의 마이그레이션 작업으로 테스트되었으며, 성공으로 보고하기 전에 소스 데이터 수신, 제공업체의 업로드 수락, 대상 객체를 확인합니다. 파이프라인을 직접 운영해야 한다면 아래의 MIT 라이선스 Python 프로그램을 사용해 컴퓨터를 거쳐 보수적으로 복사할 수 있으며, 소스 파일은 삭제되지 않습니다.

코드를 선택하기 전에 운영 모델부터 선택하세요

파일 라이브러리 규모가 크거나, 연결을 무인으로 계속 실행해야 하거나, 노트북을 통해 데이터를 전송하고 싶지 않을 때는 클라우드 간 직접 마이그레이션 서비스가 실용적인 선택입니다. FileArk는 전송을 온라인에서 유지하고, 제공업체의 응답을 모니터링하며, 복구 가능한 오류를 재시도하고, 하나의 화면에서 진행 상황을 보여 줍니다. 검증 과정에서는 파일을 완료된 것으로 처리하기 전에 서로 독립적인 세 가지 검사를 수행합니다.

OAuth 애플리케이션, 스테이징 디스크, 로그 또는 대상 폴더 정책을 완전히 제어해야 할 때는 로컬 스크립트가 유용합니다. 대신 운영 책임이 따릅니다. 컴퓨터가 계속 온라인 상태여야 하고 네트워크 연결이 병목 지점이 되며, OAuth 자격 증명을 보호해야 하고, 활성 배치와 검증용 사본을 위한 임시 디스크 공간을 충분히 유지해야 합니다.

여기에 공개된 프로그램은 의도적으로 보수적으로 설계되었습니다. 한 개인 드라이브의 루트에서 새 대상 폴더로 복사합니다. 삭제 메서드를 제공하지 않고, 충돌 시 덮어쓰지 않으며, 검증 후 영구 체크포인트를 저장하고, 로컬 또는 대상의 용량이 설정한 예비 용량 아래로 떨어지면 중지합니다.

전송 파이프라인과 오류 처리 경계

1. 원본 트리 목록화

   원본 어댑터는 폴더를 재귀적으로 탐색하고 공급자의 페이지네이션을 따르며 ID, 경로, 유형, 보고된 크기를 기록하고, 지원되는 Google 네이티브 파일을 이식 가능한 내보내기 형식에 매핑합니다.

2. 대상 및 로컬 용량 사전 점검

   엔진은 대기 중인 바이트 수에 설정 가능한 예비 용량을 더한 값을 대상 할당량과 비교합니다. 또한 각 배치와 개별 다운로드를 시작하기 전에 스테이징 파일 시스템도 확인합니다.

3. 제한된 배치 스테이징

   파일은 총 바이트 수와 파일 수가 모두 제한된 배치 단위로 처리됩니다. 현재 배치만 로컬 디스크를 사용하므로 대규모 라이브러리를 처리할 때도 같은 크기의 드라이브가 필요하지 않습니다.

4. 해시 계산 및 업로드

   다운로드 후 스크립트는 로컬 SHA-256을 계산하고, 알려진 원본 크기가 있으면 이를 확인한 다음, 대상 폴더를 만들고 공급자와 호환되는 재개 가능 청크 방식으로 업로드합니다.

5. 검증 및 체크포인트 저장

   기본 모드에서는 대상에 새로 생성된 객체를 다시 다운로드하고 SHA-256을 비교합니다. 일치하는 파일만 JSON 체크포인트에 기록되고 로컬 스테이징에서 제거됩니다.

MIT 라이선스가 적용된 전체 Python 버전 다운로드

다운로드 파일은 읽기 쉬운 단일 Python 진입점으로 구성됩니다. 공급자 SDK는 실제 전송에만 가져오므로 종속 항목이나 자격 증명을 설치하기 전에도 데모 및 도움말 명령을 실행할 수 있습니다. 별도의 요구 사항 파일에는 지원되는 패키지의 최소 버전이 고정되어 있으며, 라이선스는 소스와 함께 제공됩니다.

사용하기 전에 코드를 검토하고, 작은 대상 폴더로 테스트하며, 중요한 데이터에는 기본값인 재다운로드 검증을 유지하세요. 어떤 범용 스크립트도 모든 공유 권한, 바로가기, 보존 레이블, 공유 드라이브 규칙 또는 테넌트 정책을 그대로 재현할 수는 없습니다.

클라우드 액세스를 허용하기 전에 안전 절차 확인하기

먼저 데모를 실행하세요. 데모는 네트워크를 호출하지 않으며 클라우드에 데이터를 쓰지 않습니다. 마지막 줄은 의도적으로 모호하지 않게 작성되었습니다. 삭제된 원본 파일은 0개입니다. 실제 엔진도 구조화된 로그를 통해 동일한 순서를 출력하며, 검증되지 않은 첫 번째 파일에서 0이 아닌 종료 코드로 끝납니다.

chmod +x fileark-cloud-transfer.py
python3 fileark-cloud-transfer.py --demo
python3 fileark-cloud-transfer.py --help

비밀 정보를 코드에 삽입하지 않고 OAuth 클라이언트 만들기

Google Drive의 경우 Google Cloud 프로젝트에서 데스크톱 OAuth 클라이언트를 만들고, Drive API를 사용 설정하고, 동의 화면을 구성한 다음 클라이언트 JSON을 다운로드하세요. --google-client-secret으로 해당 경로를 전달하거나 GOOGLE_OAUTH_CLIENT_SECRET_FILE을 설정하세요. 스크립트는 파일 목록 조회, 다운로드, 폴더 생성, 업로드 및 검증을 수행해야 하므로 Drive 액세스 권한을 요청합니다.

OneDrive의 경우 Microsoft Entra ID에 공용 클라이언트 애플리케이션을 등록하고, 디바이스 코드 흐름을 활성화한 다음, 위임된 Files.ReadWrite 권한을 추가하고 애플리케이션 클라이언트 ID를 전달하세요. 개인 및 조직 계정에는 common, 회사 계정에는 organizations를 선택하고, 정책에서 요구하는 경우 특정 테넌트 ID를 사용하세요.

중단된 마이그레이션을 새로 로그인하지 않고 재개할 수 있도록 토큰은 로컬 파일에 캐시됩니다. 클라이언트 JSON과 토큰 캐시는 비밀 정보로 취급하세요. 버전 관리에서 제외하고, 파일 시스템 권한을 제한하며, 지원 티켓에 절대 업로드하지 말고, 마이그레이션이 승인되면 삭제하세요.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-fileark-cloud-transfer.txt

Google Drive에서 OneDrive로 또는 반대 방향으로 실행하기

ID와 관련된 모든 값은 운영자가 직접 제공해야 합니다. 프로그램에는 클라이언트 ID, 비밀 값, 테넌트, 토큰, 원격 계정 또는 대상 자격 증명이 포함되어 있지 않습니다. 첫 번째 명령은 브라우저에서 Google에 로그인하고 디바이스 코드를 사용해 Microsoft에 로그인한 다음, 새 OneDrive 폴더로 파일을 복사합니다.

OneDrive에서 Google Drive로 전송하려면 원본과 대상을 반대로 지정하세요. 독립적인 마이그레이션마다 서로 다른 상태 파일과 대상 루트를 사용하세요. 체크포인트는 원본 공급자, 대상 공급자, 루트를 하나로 연결하며, 구성이 일치하지 않으면 재개를 거부합니다.

export MICROSOFT_CLIENT_ID="your-public-client-id"
python fileark-cloud-transfer.py \
  --source google \
  --destination onedrive \
  --google-client-secret ./client_secret.json \
  --microsoft-tenant common \
  --destination-root "FileArk Manual Transfer 2026-07-25" \
  --batch-gib 8 \
  --batch-files 200 \
  --local-reserve-gib 15 \
  --destination-reserve-gib 10 \
  --verification redownload

python fileark-cloud-transfer.py \
  --source onedrive \
  --destination google \
  --microsoft-client-id "$MICROSOFT_CLIENT_ID" \
  --google-client-secret ./client_secret.json \
  --destination-root "OneDrive archive 2026-07-25" \
  --state-file ./onedrive-to-google-state.json \
  --verification redownload

용량을 여러 번 확인하는 이유

전송 시간이 길어지면 한 번 수행한 사전 점검 정보가 오래되어 정확하지 않을 수 있습니다. 다른 사용자가 대상에 파일을 업로드하거나, 내보낸 Google 문서가 소스 메타데이터에 표시된 것보다 클 수 있으며, 관련 없는 애플리케이션이 로컬 디스크 공간을 사용할 수도 있습니다. 따라서 엔진은 시작 전에 대상의 전체 용량을 확인하고, 배치마다 대상 용량을 확인하며, 각 로컬 다운로드 후에 대상 용량을 다시 확인합니다. 또한 각 스테이징 또는 검증용 복사 전에 로컬 디스크 공간도 확인합니다.

예약 용량 값은 전송 크기의 추정치가 아니라 운영상 필요한 여유 공간입니다. 운영 체제 업데이트, 제공업체의 사용량 반영 지연, 동일한 클라우드 할당량을 사용하는 다른 사용자를 고려해 충분히 크게 설정하세요. 제공업체가 유한한 잔여 할당량을 공개하지 않으면 스크립트가 경고를 표시하고 제공업체의 제한 적용에 의존합니다. 이는 잔여 용량을 알고 수행하는 사전 점검보다 안전성이 낮으므로 적극적인 모니터링이 필요합니다.

def ensure_destination_capacity(quota, required, reserve):
    if quota.remaining is None:
        LOG.warning("Destination did not report a finite quota")
        return
    needed = required + reserve
    if quota.remaining < needed:
        raise RuntimeError(
            f"Destination is too small: {human_bytes(quota.remaining)} free, "
            f"{human_bytes(needed)} required including reserve."
        )

바이트와 파일 개수로 스테이징 사용량 제한하기

바이트 상한은 디스크 사용량을 제한하고, 파일 수 상한은 원본에 아주 작은 객체가 수십만 개 있을 때 발생하는 API 및 파일 시스템 오버헤드를 제한합니다. 배치 상한보다 큰 파일은 파일 하나로 구성된 배치로 허용되므로, 예비 공간은 가장 큰 개별 객체를 수용할 수 있도록 설정해야 합니다.

기본 청크 크기는 10 MiB입니다. 이는 Google Drive의 256 KiB 재개 가능 업로드 단위와 Microsoft Graph의 320 KiB 순차 프래그먼트 요구 사항의 공배수입니다. 명령줄 검증기는 인증 전에 호환되지 않는 청크 크기를 거부합니다.

def batches(files, max_bytes, max_files):
    batch, batch_size = [], 0
    for item in files:
        planned_size = max(item.size, 1)
        if batch and (
            len(batch) >= max_files
            or batch_size + planned_size > max_bytes
        ):
            yield batch
            batch, batch_size = [], 0
        batch.append(item)
        batch_size += planned_size
    if batch:
        yield batch

Google 네이티브 문서를 변환 방식으로 처리하기

Google Docs, Sheets, Slides, Drawings 및 Apps Script 프로젝트는 일반적으로 다운로드할 수 있는 바이트 스트림이 아닙니다. Google 어댑터는 각 파일을 DOCX, XLSX, PPTX, PNG, JSON으로 내보내고 이식 가능한 파일 확장자를 추가합니다. 폴더는 탐색하지만 파일이 들어 있지 않으면 빈 객체로 업로드하지 않습니다.

변환 과정에서 글꼴, 수식, 댓글, 포함된 객체, 페이지 레이아웃 및 공동작업 기록이 달라질 수 있습니다. Google 내보내기 엔드포인트에도 형식 및 크기 제한이 있습니다. 스크립트는 임의의 표현 형식을 만들어 내는 대신 지원되지 않는 네이티브 형식을 건너뛰고 경고를 표시합니다. 대표적인 변환 파일을 수동으로 검토하세요.

바로가기, 공유 드라이브, 나와 공유되었지만 내 드라이브에는 없는 파일, OneNote 패키지, 조직의 보존 메타데이터, 버전 기록, 공유 ACL은 이 버전의 지원 범위에 포함되지 않습니다. 이러한 한계로 인해 파일 복사를 완전한 테넌트 마이그레이션이라고 표현해서는 안 됩니다.

정확한 바이트 검증을 위해 대상 파일 전체를 재다운로드

제공업체에서 업로드 성공 응답을 받는 것은 필요하지만 그것만으로는 충분하지 않습니다. 업로드 후 스크립트는 먼저 대상 메타데이터의 크기와 스테이징된 파일의 크기를 비교합니다. 기본 재다운로드 모드에서는 대상 객체를 임시 인접 파일로 다운로드한 다음 SHA-256을 계산하고, 해당 다이제스트를 스테이징된 소스의 다이제스트와 비교합니다.

크기와 다이제스트가 모두 일치하는 경우에만 체크포인트 항목이 생성됩니다. 체크포인트에는 원본 ID, 원본에서 보고한 크기, 대상 ID, 대상 경로, 실제 바이트 수, 두 다이제스트 및 UTC 완료 시간이 기록됩니다. 체크포인트에 기록된 원본 경로가 나중에 다른 ID나 크기를 가리키면 스크립트는 변경된 데이터를 조용히 건너뛰지 않고 중지합니다.

재다운로드하면 대상 측 읽기 트래픽이 두 배로 늘어나며, 스테이징된 파일과 검증용 사본을 모두 저장할 공간이 일시적으로 필요합니다. 이러한 비용을 이해하고 있으며 독립적인 콘텐츠 검증 절차가 마련된 경우에만 메타데이터 모드를 선택하세요.

destination.redownload(uploaded, verification_copy)
verification_hash = sha256_file(verification_copy)
if verification_hash != local_hash:
    raise RuntimeError(
        f"SHA-256 mismatch after destination re-download: {relative!r}."
    )

state["completed"][relative] = {
    "source_id": item.id,
    "destination_id": uploaded.id,
    "bytes": actual_size,
    "sha256": local_hash,
    "destination_sha256": verification_hash,
}

불확실한 상태를 성공으로 간주하지 않고 재개하기

프로그램은 임시 파일을 작성한 뒤 이름을 바꾸는 방식으로 상태를 원자적으로 저장합니다. 검증된 항목은 이 영구 쓰기가 완료된 후에만 로컬 스테이징 영역에서 제거됩니다. 동일한 명령을 다시 실행하면 체크포인트에 기록된 항목은 건너뛰고 대기 중인 경로부터 계속 진행합니다.

제공업체가 업로드를 수락한 후 체크포인트가 기록되기 전에 충돌이 발생할 수 있습니다. 충돌 처리 방식이 fail이므로 다음 실행에서는 덮어쓰거나 성공했다고 잘못 표시하는 대신, 이미 존재하는 해당 대상 경로에서 중지됩니다. 객체를 검사하고 비교한 후, 검증된 복구 항목을 신중하게 추가하거나 새로운 대상 루트에서 다시 시작하세요.

OAuth 만료, 속도 제한, 일시적인 서버 오류 및 중단된 청크는 정해진 한도 내에서 재시도됩니다. 인증 오류나 지속적인 권한 오류가 발생하면 프로그램이 중지됩니다. 오류의 원인을 파악할 때까지 로그, 체크포인트 및 스테이징 콘텐츠를 보존하세요.

실질적인 인수 테스트 수행하기

• 빈 파일, 대용량 파일, 깊은 경로, Unicode 이름 및 Google 네이티브 문서가 포함된 작은 폴더부터 시작하세요.
• 먼저 --dry-run을 실행하고 인벤토리의 총 바이트 수를 공급자 인터페이스에 표시된 값과 비교하세요.
• 첫 번째 운영 배치를 처리하는 동안 로컬 여유 공간과 대상 할당량을 각각 모니터링하세요.
• 재다운로드 검증을 활성화한 상태로 유지하고 체크포인트를 마이그레이션 기록과 함께 보관하세요.
• 대상에서 대표적인 PDF, Office 파일, 이미지, 동영상, 압축 파일 및 변환된 네이티브 문서를 열어 확인하세요.
• 예상 폴더 수와 파일 수를 비교하고, 건너뛰거나 실패한 모든 항목을 조사한 다음, 다른 사용자의 접근도 테스트하세요.
• 정해진 병행 운영 기간 동안 원본을 변경하지 않고 유지하세요. 이 스크립트는 원본을 삭제하지 않습니다.

자주 묻는 질문

이 Python 스크립트가 원본 파일을 삭제하는 경우가 있나요?

아니요. 소스 삭제 기능은 구현되어 있지 않습니다. 엔진은 소스에서 파일을 다운로드하여 별도의 대상 루트에 기록하며, 검증에 성공하면 임시 로컬 스테이징 사본만 제거합니다.

양방향으로 전송할 수 있나요?

예. Google Drive 또는 OneDrive를 원본으로 설정하고 다른 공급자를 대상으로 설정하세요. 각 마이그레이션에 고유한 체크포인트와 대상 루트를 사용하세요.

공유 권한과 파일 기록도 보존되나요?

아니요. 이 버전은 현재 파일 콘텐츠와 폴더 경로를 복사합니다. 공유 ACL, 공개 링크, 버전, 댓글, 레이블, 보존 정책 및 조직별 메타데이터는 별도의 마이그레이션과 검증이 필요합니다.

방금 업로드한 파일을 다시 다운로드하는 이유는 무엇인가요?

업로드가 승인되고 메타데이터의 크기가 일치하더라도 대상에서 정확한 바이트를 다시 읽을 수 있다는 보장은 없습니다. 재다운로드 모드는 대상 콘텐츠의 SHA-256을 계산하고 정확히 일치하는 경우에만 체크포인트에 기록합니다.

Google 또는 Microsoft의 공식 도구인가요?

아니요. MIT 라이선스로 공개된 FileArk의 독립적인 참조 구현입니다. 코드를 검토하고 중요하지 않은 데이터로 테스트한 뒤 공급자 및 조직의 정책을 따르세요.

이 가이드에 사용된 공식 자료

• Google Workspace 학습 센터: OneDrive에서 Google Drive로 전환하기
• Google Drive 고객센터: 저장용량 및 파일 작동 방식
• Microsoft 지원: OneDrive에 파일 업로드 및 저장하기
• Google Drive API: 파일 다운로드 및 내보내기
• Google Drive API: 재개 가능한 업로드
• Google Drive API: 저장용량 할당량 필드
• Microsoft Graph: 드라이브 하위 항목 나열
• Microsoft Graph: 재개 가능한 업로드 세션 만들기
• Microsoft Graph: OneDrive 할당량 리소스