Drive API v2 和 v3 比較指南

最新版 Google 雲端硬碟 API 為 v3。由於搜尋只會傳回部分欄位，因此 v3 的效能較佳。除非您需要 v2 集合，否則請使用目前版本。如果您使用的是 v2，請考慮遷移至 v3。如要遷移，請參閱「遷移至 Drive API v3」。如需完整的版本差異清單，請參閱 Drive API v2 和 v3 比較參考資料。

如果您想繼續使用第 2 版，請參閱 Drive API 第 2 版指南修訂版，瞭解如何針對第 2 版開發人員修改第 3 版指南中的部分操作說明。

如要進一步瞭解 Drive API 第 3 版的改善項目，請觀看以下影片，由 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 來要求應用程式資料。
• 所有更新作業都會使用 PATCH 而非 PUT。
• 如要匯出 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 欄位會更新上次有人修改檔案的時間。在第 2 版中，只有在您設定 setModifiedDate 欄位時，modifiedDate 欄位才會在更新時變更。
• files 資源中的 viewedByMeTime 欄位不會自動更新。
• 如要匯入 Google 文件格式，請在資源主體中設定適當的目標 mimeType。在 v2 中，您設定 ?convert=true。
• 如果不支援格式，匯入作業會傳回 400 錯誤。
• 讀者和加註者無法查看權限。
• 系統已移除權限的 me 別名。
• 部分功能原本是要求資源的一部分，但現在改為要求參數。例如：
  • 在 v2 中，您可以使用 children.delete 從父資料夾移除子檔案。
  • 在 v3 中，您可以在網址中使用 ?removeParents=parent_id 在子項上使用 files.update。

其他差異

在 v3 中，欄位和參數名稱有所不同。例如：

• name 屬性會取代 files 資源中的 title。
• Time 是所有日期和時間欄位的後置字串，而非 Date。
• 清單作業不會使用 items 欄位來包含結果集。資源類型會為結果提供欄位 (例如 files 或 changes)。