Google Drive API의 changes.list와 startPageToken을 활용하면, 전체 스캔 없이 마지막 동기화 지점부터 변경된 파일만 효율적으로 감지하고 동기화하는 폴링 기반 패턴을 구현할 수 있습니다. 이는 Google Drive의 내용을 외부 시스템(예: 정적 사이트 생성기의 소스 파일 디렉토리)과 주기적으로 동기화해야 하는 자동화 작업에서, 실시간 웹훅 대신 더 단순하고 신뢰성 높은 주기적 폴링을 구현할 때 사용됩니다. 핵심은 Drive의 전역 변경 로그를 증분적으로 조회하여 네트워크 호출과 처리량을 최소화하는 것입니다.
Google Drive는 사용자의 전체 Drive(My Drive 및 공유 드라이브)에 대한 변경 이벤트를 시간 순서의 로그로 유지합니다. 이 로그는 페이지 단위로 접근 가능하며, 각 페이지는 고유한 startPageToken으로 식별됩니다. 첫 동기화 시 changes.getStartPageToken을 호출하여 현재 시점의 토큰을 획득하고 영구 저장소(예: 파일 시스템의 JSON 상태 파일)에 저장합니다. 이 토큰은 이후 동기화의 기준점이 됩니다.
다음 실행 시 저장된 startPageToken을 사용해 changes.list를 호출하면, API는 해당 토큰 이후 발생한 모든 변경 사항(파일 생성, 수정, 이동, 삭제, 권한 변경)을 페이지네이션으로 반환합니다. 응답에는 새로운 newStartPageToken이 포함되어, 다음 조회의 시작점으로 사용됩니다. 반환된 변경 목록을 대상 폴더 ID나 파일 경로 패턴으로 필터링한 후, 각 변경의 changeType(예: file, drive 등)과 removed 플래그를 확인해 로컬 파일 시스템에 반영합니다(다운로드, 업데이트, 삭제). 성공적으로 동기화 후 새로운 newStartPageToken을 저장소에 갱신합니다. 이는 다음 실행의 기준이 되며, 중간 실패 시 재시도할 수 있는 체크포인트 역할을 합니다.
이 패턴을 사용해 Drive의 특정 공유 폴더(예: wiki/blog, wiki/zt/literature) 내 Markdown 파일을 정적 사이트의 소스 디렉토리(src/app/docs/)로 동기화하는 경우, 몇 가지 사항을 설계에 반영해야 합니다. 자동화된 서버 환경(예: GitHub Actions)에서는 사용자 상호작용이 불가능하므로, Service Account를 생성하고 대상 폴더를 해당 서비스 계정 이메일과 공유하는 방식이 가장 단순하며, 장기적인 토큰 갱신 관리가 필요 없습니다. OAuth 클라이언트와 리프레시 토큰을 재사용할 수도 있지만, 토큰 만료와 재동의 문제가 발생할 수 있습니다.
폴링 간 상태(startPageToken, 마지막 동기화 시간, 감시 중인 폴더 ID)를 유지해야 합니다. 스크립트가 실행되는 환경이 상태를 유지하지 않는다면(예: 일회성 컨테이너), 반드시 영구 저장소(동일 리포지토리 내 파일, 외부 스토리지)에 상태를 보관하고 로드해야 합니다. changes.list는 전체 Drive의 변경을 반환하므로, 관심 있는 특정 폴더 하위의 변경만 처리하려면 추가 필터링 로직이 필요합니다. driveId와 folderId를 사용해 files.list와 결합하거나, 응답의 fileId로 파일 메타데이터를 추가 조회해 부모 폴더를 확인할 수 있습니다.
변경 항목의 removed 속성이 true이면 해당 파일이 Drive에서 삭제되었거나 접근 권한이 변경된 것입니다. 로컬 파일 시스템에서 대응하는 파일을 삭제해야 동기화 상태가 유지됩니다. 정기적 크론 작업(예: 매일 아침 9시)으로 실행할 때, GitHub Actions의 schedule 트리거는 UTC 기준이며 정각에 집중되는 부하를 피하기 위해 몇 분의 오프셋을 두는 것이 좋습니다. concurrency 제어를 설정해 동시에 여러 실행이 겹치지 않도록 해야 합니다.
이 패턴에는 트레이드오프와 대안이 존재합니다. Drive API는 파일 변경 시 실시간 알림을 보내는 watch 채널 생성도 지원합니다. 그러나 채널은 최대 24시간 후 만료되므로 주기적인 갱신이 필요하고, 공개적으로 접근 가능한 엔드포인트가 필요합니다. 반면 증분 폴링 패턴은 외부 엔드포인트 없이 클라이언트가 주도하며, 상태 토큰 관리만으로 장기 실행이 가능해 설정이 더 단순합니다. 매번 files.list로 전체 파일 목록을 가져와 비교하는 방식은 파일이 많을수록 비효율적입니다. 증분 패턴은 변경된 부분만 처리하므로 API 할당량 사용과 실행 시간을 크게 줄입니다.
네트워크 지연이나 부분 실패로 인해 변경 로그의 일부를 놓칠 수 있습니다. startPageToken은 안정적이지만, 매우 오랜 기간(예: 1개월 이상) 동기화를 중단했다가 재개할 경우 토큰이 만료될 수 있습니다. 이때는 getStartPageToken으로 최신 토큰을 받아 초기화하거나, 안전장치로 특정 시점 이후의 files.list를 폴백으로 실행해야 합니다. 이 패턴의 본질은 변경 로그를 체크포인트 기반으로 순회하는 것이며, Google Drive뿐만 아니라 유사한 변경 히스토리를 제공하는 다른 스토리지 시스템에도 적용 가능한 일반적인 동기화 전략입니다.
관련 항목으로는 Google Drive API Watch 채널 (실시간 웹훅 방식), 상태 기반 폴링(Stateful Polling) 패턴, 서비스 계정(Service Account) 인증 흐름, Git 기반 컨텐츠 동기화 전략 등이 있습니다.