changes.list 증분 동기화는 주기적 폴링 환경에서 웹훅 없이도 Drive 변경사항을 효율적으로 감지할 수 있는 메커니즘이다. GitHub Actions 크론 작업처럼 하루 한 번 동기화하는 시나리오에 적합하다.
동작 원리
Drive API의 changes.list는 페이지 토큰(pageToken) 기반의 변경 로그를 제공한다. 이 로그는 Google Drive 전체(사용자 또는 서비스 계정이 접근 가능한 모든 파일)에 대한 수정, 생성, 삭제, 권한 변경 등의 이벤트를 시간 순으로 유지한다.
동기화 시작 시 changes.getStartPageToken을 호출해 현재 시작 페이지 토큰을 얻고 저장한다. 이후 실행에서는 저장된 토큰을 changes.list의 pageToken 파라미터로 전달해, 해당 토큰 이후에 발생한 변경사항만 조회한다. 응답에는 변경 목록과 다음 조회의 시작점이 될 newStartPageToken이 포함되며, 이 새 토큰을 저장해 다음 폴링의 기준점을 이동시킨다.
적용 시나리오
이 메커니즘은 웹훅을 사용하지 않는 주기적 폴링 환경에 적합하다. 웹훅은 설정 복잡도와 만료 갱신 관리가 필요하지만, changes.list 기반 폴링은 상태 파일에 페이지 토큰만 유지하면 되어 운영이 단순하다. 특히 하루 한 번 정도의 빈도로 동기화하는 블로그나 문서 저장소 시나리오에서 실용적이다.
실제 적용 시, changes.list는 전체 Drive의 변경 로그를 반환하므로, 관심 있는 특정 폴더(예: wiki/blog, wiki/zt/literature 등) 하위의 파일만 필터링하는 추가 로직이 필요하다. 변경 항목 각각은 파일 ID와 변경 유형을 포함하며, 이를 바탕으로 실제 파일 메타데이터를 files.get으로 조회하거나, 삭제된 경우 로컬 파일을 제거하는 작업을 수행한다. 서비스 계정을 사용할 경우, 동기화 대상 폴더를 해당 서비스 계정 이메일에 공유해야 하며, drive.readonly 범위로 읽기 전용 동기화를 구성할 수 있다.
상태 관리
상태 관리는 일반적으로 저장소 내부의 파일(예: .sync/drive-state.json)에 마지막 pageToken과 동기화 시간을 저장하는 방식으로 이루어진다. 이 파일은 동기화 작업이 commit과 push를 통해 저장소에 변경사항을 반영하는 경우 함께 업데이트되어 상태의 지속성을 보장한다.
참고
Google Drive API changes.list 메서드 문서를 참고할 수 있다.