Hướng dẫn so sánh API Drive phiên bản 2 và phiên bản 3
Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Phiên bản mới nhất của Google Drive API là phiên bản 3. Hiệu suất trong phiên bản 3 tốt hơn vì các tìm kiếm chỉ trả về một tập hợp con các trường. Sử dụng phiên bản hiện tại, trừ phi bạn cần bộ sưu tập v2. Nếu bạn đang sử dụng phiên bản 2, hãy cân nhắc việc di chuyển sang phiên bản 3. Để di chuyển, hãy xem phần Di chuyển sang Drive API phiên bản 3. Để xem danh sách đầy đủ về điểm khác biệt giữa các phiên bản, hãy xem Tài liệu tham khảo so sánh Drive API phiên bản 2 và phiên bản 3.
Nếu bạn muốn tiếp tục sử dụng phiên bản 2, hãy xem nội dung sửa đổi Hướng dẫn về Drive API phiên bản 2 để tìm hiểu cách một số hướng dẫn trong hướng dẫn về phiên bản 3 phải được sửa đổi cho nhà phát triển phiên bản 2.
Để tìm hiểu thêm về những điểm cải tiến của Drive API phiên bản 3, bạn có thể xem video sau đây của các kỹ sư Google thảo luận về thiết kế API mới.
Các điểm cải tiến của V3
Để tối ưu hoá hiệu suất và giảm độ phức tạp của hành vi API, phiên bản 3 cung cấp những điểm cải tiến sau so với phiên bản API trước:
Theo mặc định, các cụm từ tìm kiếm tệp và bộ nhớ dùng chung sẽ không trả về toàn bộ tài nguyên, mà chỉ trả về một nhóm nhỏ các trường thường dùng. Để biết thêm thông tin chi tiết về fields, hãy xem phương thức files.list và phương thức drives.list.
Hầu hết các phương thức trả về phản hồi hiện đều yêu cầu tham số fields. Để biết danh sách tất cả các phương thức yêu cầu fields, hãy xem
tài liệu tham khảo về Drive API.
Đã xoá những tài nguyên có các chức năng trùng lặp. Một số ví dụ:
Phương thức files.list thực hiện cùng chức năng với các tập hợp Children và Parents, nên các tập hợp này sẽ bị xoá khỏi phiên bản 3.
Các phương thức Realtime.* đã bị xoá.
Theo mặc định, Dữ liệu ứng dụng không được trả về trong các lượt tìm kiếm. Trong phiên bản 2, bạn có thể đặt phạm vi drive.appdata và phạm vi này sẽ trả về dữ liệu ứng dụng từ phương thức files.list và phương thức changes.list, nhưng điều này sẽ làm giảm hiệu suất. Trong phiên bản 3, bạn đặt phạm vi drive.appdata, đồng thời đặt tham số truy vấn spaces=appDataFolder để yêu cầu dữ liệu ứng dụng.
Tất cả các thao tác cập nhật đều sử dụng PATCH thay vì PUT.
Để xuất Tài liệu trên Google, hãy sử dụng phương thức files.export.
Hành vi của phương thức changes.list sẽ khác. Thay vì mã nhận dạng thay đổi, hãy sử dụng mã thông báo trang không công khai. Để thăm dò tập hợp thay đổi, trước tiên, hãy gọi phương thức changes.getStartPageToken cho giá trị ban đầu. Đối với các truy vấn tiếp theo, phương thức changes.list sẽ trả về giá trị newStartPageToken.
Giờ đây, các phương thức cập nhật sẽ từ chối những yêu cầu chỉ định các trường không thể ghi.
Các trường exportFormats và importFormats phiên bản 2 trong tài nguyên about là danh sách các định dạng nhập hoặc xuất cho phép. Trong phiên bản 3, đây là các bản đồ loại MIME của các mục tiêu có thể có đối với tất cả các hoạt động nhập hoặc xuất được hỗ trợ.
Các bí danh appdata và appfolder của phiên bản 2 hiện là appDataFolder trong phiên bản 3.
Tài nguyên properties sẽ bị xoá khỏi phiên bản 3. Tài nguyên files có trường properties chứa các cặp khoá-giá trị thực. Trường properties chứa các thuộc tính công khai và trường appProperties chứa các thuộc tính riêng tư, vì vậy bạn không cần trường hiển thị.
Trường modifiedTime trong tài nguyên files sẽ cập nhật thời điểm sửa đổi tệp gần đây nhất. Trong phiên bản 2, trường modifiedDate chỉ có thể thay đổi khi cập nhật nếu bạn đặt trường setModifiedDate.
Trường viewedByMeTime trong tài nguyên files không tự động cập nhật.
Để nhập các định dạng của Google Tài liệu, bạn hãy đặt mục tiêu thích hợp mimeType trong nội dung tài nguyên. Trong phiên bản 2, bạn đặt ?convert=true.
Các thao tác nhập sẽ trả về lỗi 400 nếu định dạng không được hỗ trợ.
Người đọc và người nhận xét không thể xem quyền.
Bí danh me cho các quyền sẽ bị xoá.
Một số chức năng có trong tài nguyên yêu cầu nhưng thay vào đó, lại có dưới dạng một tham số yêu cầu. Ví dụ:
Trong phiên bản 2, bạn có thể dùng children.delete để xoá một tệp con khỏi thư mục mẹ.
Trong phiên bản 3, bạn sử dụng files.update trên trẻ em có ?removeParents=parent_id trong URL.
Các điểm khác biệt khác
Tên trường và tên tham số khác nhau trong phiên bản 3. Một số ví dụ bao gồm:
Thuộc tính name thay thế title trong tài nguyên files.
Time là hậu tố cho tất cả các trường ngày và giờ thay vì Date.
Các thao tác liệt kê không dùng trường items để chứa tập kết quả. Loại tài nguyên cung cấp một trường cho kết quả (chẳng hạn như files hoặc changes).
[[["Dễ hiểu","easyToUnderstand","thumb-up"],["Giúp tôi giải quyết được vấn đề","solvedMyProblem","thumb-up"],["Khác","otherUp","thumb-up"]],[["Thiếu thông tin tôi cần","missingTheInformationINeed","thumb-down"],["Quá phức tạp/quá nhiều bước","tooComplicatedTooManySteps","thumb-down"],["Đã lỗi thời","outOfDate","thumb-down"],["Vấn đề về bản dịch","translationIssue","thumb-down"],["Vấn đề về mẫu/mã","samplesCodeIssue","thumb-down"],["Khác","otherDown","thumb-down"]],["Cập nhật lần gần đây nhất: 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`)."]]
