Drive API v2 및 v3 비교 가이드

최신 Google Drive API 버전은 v3입니다. 검색에서 필드의 하위 집합만 반환하므로 v3의 성능이 더 좋습니다. v2 컬렉션이 필요한 경우가 아니라면 현재 버전을 사용하세요. v2를 사용하는 경우 v3로 마이그레이션하는 것이 좋습니다. 마이그레이션하려면 Drive API v3로 마이그레이션을 참고하세요. 버전 차이점의 전체 목록은 Drive API v2 및 v3 비교 참조를 참고하세요.

v2를 계속 사용하려면 Drive API v2 가이드 수정사항을 참고하여 v3 가이드의 일부 안내를 v2 개발자에 맞게 수정하는 방법을 알아보세요.

Drive API v3 개선사항에 대해 자세히 알아보려면 새 API 디자인을 설명하는 Google 엔지니어의 다음 동영상을 시청하세요.

V3 개선사항

성능을 최적화하고 API 동작 복잡성을 줄이기 위해 v3에서는 이전 API 버전에 비해 다음과 같은 개선사항을 제공합니다.

  • 파일 및 공유 드라이브 검색은 기본적으로 전체 리소스를 반환하지 않으며, 일반적으로 사용되는 필드의 하위 집합만 반환됩니다. fields에 관한 자세한 내용은 files.list 메서드와 drives.list 메서드를 참고하세요.
  • 이제 응답을 반환하는 거의 모든 메서드에 fields 매개변수가 필요합니다. fields가 필요한 모든 메서드의 목록은 Drive API 참조를 참고하세요.
  • 기능이 중복된 리소스가 삭제되었습니다. 예를 들면 다음과 같습니다.
    • files.list 메서드는 Children 및 Parents 컬렉션과 동일한 기능을 수행하므로 v3에서 삭제됩니다.
    • Realtime.* 메서드가 삭제되었습니다.
  • 앱 데이터는 기본적으로 검색에서 반환되지 않습니다. v2에서는 drive.appdata 범위를 설정할 수 있으며 files.list 메서드와 changes.list 메서드에서 애플리케이션 데이터를 반환하지만 성능이 저하됩니다. v3에서는 drive.appdata 범위를 설정하고 spaces=appDataFolder 쿼리 매개변수를 설정하여 애플리케이션 데이터를 요청합니다.
  • 모든 업데이트 작업에서 PUT 대신 PATCH를 사용합니다.
  • Google 문서를 내보내려면 files.export 메서드를 사용합니다.
  • changes.list 메서드 동작이 다릅니다. 변경 ID 대신 불투명 페이지 토큰을 사용하세요. 변경사항 컬렉션을 폴링하려면 먼저 초기 값에 대해 changes.getStartPageToken 메서드를 호출합니다. 후속 쿼리의 경우 changes.list 메서드는 newStartPageToken 값을 반환합니다.
  • 이제 업데이트 메서드는 쓰기 불가능한 필드를 지정하는 요청을 거부합니다.
  • about 리소스의 v2 exportFormats 및 importFormats 필드는 허용되는 가져오기 또는 내보내기 형식의 목록입니다. v3에서는 가능한 타겟의 MIME 유형을 지원되는 모든 가져오기 또는 내보내기에 매핑합니다.
  • v2 appdata 및 appfolder 별칭은 이제 v3에서 appDataFolder입니다.
  • properties 리소스가 v3에서 삭제되었습니다. files 리소스에는 실제 키-값 쌍이 포함된 properties 필드가 있습니다. properties 필드에는 공개 속성이 포함되고 appProperties 필드에는 비공개 속성이 포함되므로 공개 상태 필드가 필요하지 않습니다.
  • files 리소스의 modifiedTime 필드는 파일이 마지막으로 수정된 시간을 업데이트합니다. v2에서는 setModifiedDate 필드를 설정한 경우 업데이트 시에만 modifiedDate 필드를 변경할 수 있었습니다.
  • files 리소스의 viewedByMeTime 필드는 자동으로 업데이트되지 않습니다.
  • Google Docs 형식을 가져오려면 리소스 본문에서 적절한 타겟 mimeType를 설정합니다. v2에서는 ?convert=true를 설정합니다.
  • 형식이 지원되지 않으면 가져오기 작업에서 400 오류가 반환됩니다.
  • 독자와 댓글 작성자는 권한을 볼 수 없습니다.
  • 권한의 me 별칭이 삭제됩니다.
  • 일부 기능은 요청 리소스의 일부로 제공되었지만 요청 매개변수로 제공됩니다. 예를 들면 다음과 같습니다.
    • v2에서는 children.delete를 사용하여 상위 폴더에서 하위 파일을 삭제할 수 있습니다.
    • v3에서는 URL에 ?removeParents=parent_id이 있는 하위 요소에 files.update를 사용합니다.

그 밖의 차이점

v3에서는 필드와 매개변수 이름이 다릅니다. 다음은 몇 가지 예입니다.

  • name 속성은 files 리소스에서 title를 대체합니다.
  • Time는 Date 대신 모든 날짜 및 시간 필드의 접미사입니다.
  • 목록 작업은 결과 세트를 포함하기 위해 items 필드를 사용하지 않습니다. 리소스 유형은 결과 필드 (예: files 또는 changes)를 제공합니다.