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 개선사항에 대해 자세히 알아보려면 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에서는 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)를 제공합니다.