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가 아닌 모든 날짜 및 시간 필드의 접미사입니다.
  • 목록 작업은 결과 집합을 포함하는 데 items 필드를 사용하지 않습니다. 리소스 유형은 결과의 필드를 제공합니다 (예: files 또는 changes).