Drive API v2 및 v3 비교 가이드

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

v2를 계속 사용하려면 Drive API v2 가이드 수정안을 참고하여 v2 개발자를 위해 v3 가이드의 안내를 어떻게 수정해야 하는지 알아보세요.

Drive API v3 개선사항에 관해 자세히 알아보려면 Google 엔지니어가 새로운 API 설계를 설명하는 다음 동영상을 시청하세요.

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에서 modifiedDate 필드는 setModifiedDate 필드를 설정한 경우 업데이트 시에만 변경할 수 있었습니다.
  • 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 대신).
  • list 작업은 결과 집합을 포함하는 데 items 필드를 사용하지 않습니다. 리소스 유형은 결과에 관한 필드 (예: files 또는 changes)를 제공합니다.