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)를 제공합니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[],[],null,["# Drive API v2 and v3 comparison guide\n\nThe latest Google Drive API version is v3. The performance in v3 is better because\nsearches only return a subset of fields. Use the current version unless you need\nthe [v2](/workspace/drive/api/v2/reference) collection. If you're using v2, consider\nmigrating to v3. To migrate, see [Migrate to Drive API v3](/workspace/drive/api/guides/migrate-to-v3). For a complete list of version differences, see\nthe [Drive API v2 and v3 comparison\nreference](/workspace/drive/api/guides/v2-to-v3-reference).\n\nIf you want to continue to use v2, see the [Guide to Drive API v2](/workspace/drive/api/guides/v2-guide) amendment to learn how some instructions in the v3\nguides must be amended for v2 developers.\n\nTo learn more about Drive API v3 improvements, you can watch the\nfollowing video by Google engineers discussing the new API design. \n\nV3 improvements\n---------------\n\nTo optimize performance and reduce API behavior complexity, v3 provides these\nimprovements over the previous API version:\n\n- Searches for files and shared drives don't return full resources by default, only a subset of commonly used fields gets returned. For more details on `fields`, see the [`files.list`](/workspace/drive/api/v3/reference/files/list) method and the [`drives.list`](/workspace/drive/api/v3/reference/drives/list) method.\n- Almost all methods that return a response now require the `fields` parameter. For a list of all methods requiring `fields`, see the [Drive API reference](/workspace/drive/api/v3/reference).\n- Resources that have duplicate capabilities were removed. Some examples:\n - The `files.list` method accomplishes the same functionality as the `Children` and `Parents` collections, so they're removed from v3.\n - The `Realtime.*` methods have been removed.\n- App Data isn't returned by default in searches. In v2, you can set the `drive.appdata` scope, and it returns application data from the `files.list` method and the [`changes.list`](/workspace/drive/api/v2/reference/changes/list) method, but it slows performance. In v3, you set the `drive.appdata` scope, and also set the query parameter `spaces=appDataFolder` to request application data.\n- All update operations use PATCH instead of PUT.\n- To export Google Documents, use the [`files.export`](/workspace/drive/api/v2/reference/files/export) method.\n- The `changes.list` method behavior is different. Instead of change IDs, use opaque page tokens. To poll the change collection, first call the [`changes.getStartPageToken`](/workspace/drive/api/v2/reference/changes/getStartPageToken) method for the initial value. For subsequent queries, the `changes.list` method returns the `newStartPageToken` value.\n- Update methods now reject requests that specify non-writable fields.\n- The v2 `exportFormats` and `importFormats` fields in the [`about`](/workspace/drive/api/reference/rest/v3/about) resource are lists of allowable import or export formats. In v3, they're MIME type maps of possible targets to all supported imports or exports.\n- The v2 `appdata` and `appfolder` aliases are now `appDataFolder` in v3.\n- The `properties` resource is removed from v3. The [`files`](/workspace/drive/api/v3/reference/files) resource has the `properties` field that contains true key-value pairs. The `properties` field contains public properties, and the `appProperties` field contains private properties, so the visibility field isn't needed.\n- The `modifiedTime` field in the `files` resource updates the last time anyone modified the file. In v2, the `modifiedDate` field was only mutable on update if you set the `setModifiedDate` field.\n- The `viewedByMeTime` field in the `files` resource doesn't automatically update.\n- To import Google Docs formats, you set the appropriate target `mimeType` in the resource body. In v2, you set `?convert=true`.\n- Import operations return a 400 error if the format isn't supported.\n- Readers and commenters can't view permissions.\n- The `me` alias for permissions is removed.\n- Some functionality was available as part of the request resource but is instead available as a request parameter. For example:\n - In v2, you can use `children.delete` to remove a child file from a parent folder.\n - In v3, you use`files.update` on the child with `?removeParents=parent_id` in the URL.\n\nOther differences\n-----------------\n\nFields and parameter names are different in v3. Some examples include:\n\n- The `name` property replaces `title` in the `files` resource.\n- `Time` is the suffix for all date and time fields instead of `Date`.\n- List operations don't use the `items` field to contain the result set. The resource type provides a field for the results (such as `files` or `changes`)."]]
