Drive API v2 和 v3 比較指南

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

如要繼續使用第 2 版，請參閱《Drive API v2 指南》修訂條款，瞭解第 3 版指南中的部分說明必須如何配合第 2 版開發人員修訂。

如要進一步瞭解 Drive API v3 改善項目，請觀看下方由 Google 工程師介紹的影片，其中會介紹新版 API 設計。

V3 改善項目

為達到最佳效能並降低 API 行為複雜度，第 3 版提供與舊版 API 相比的以下改善：

• 根據預設，檔案和共用雲端硬碟的搜尋內容不會傳回完整資源，只會傳回部分常用欄位。如要進一步瞭解 fields，請參閱 files.list 方法和 drives.list 方法。
• 所有傳回回應的方法現在都需要 fields 參數。如需所有需要 fields 的方法清單，請參閱 Drive API 參考資料。
• 已移除特徵重複的資源。以下列舉幾個例子：
  • files.list 方法執行的功能與 Children 和 Parents 集合相同，因此會從第 3 版中移除。
  • 已移除 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 值。
• Update 方法現在會拒絕指定無法寫入欄位的要求。
• about 資源中的 v2 exportFormats 和 importFormats 欄位是允許的匯入或匯出格式清單。在第 3 版中，這類 ID 是 MIME 類型對應，將可能目標對應至所有支援的匯入或匯出。
• v2 appdata 和 appfolder 別名現在在 v3 中為 appDataFolder。
• properties 資源已從 v3 中移除。files 資源具有包含真實鍵/值組合的 properties 欄位。properties 欄位包含公開屬性，appProperties 欄位則包含私人屬性，因此不需要顯示設定欄位。
• files 資源中的 modifiedTime 欄位會更新任何使用者上次修改檔案的時間。在第 2 版中，如果您設定了 setModifiedDate 欄位，則只有在更新時才能變更 modifiedDate 欄位。
• files 資源中的 viewedByMeTime 欄位不會自動更新。
• 如要匯入 Google 文件格式，請在資源主體中設定適當的目標 mimeType。在第 2 版中，您需要設定 ?convert=true。
• 如果系統不支援該格式，匯入作業會傳回 400 錯誤。
• 檢視者和加註者無法查看權限。
• 已移除權限的 me 別名。
• 部分功能屬於要求資源的一部分，但可做為要求參數使用。例如：
  • 在第 2 版中，您可以使用 children.delete 從上層資料夾移除子檔案。
  • 在第 3 版中，您要在網址中使用 ?removeParents=parent_id 對子項使用 files.update。

其他差異

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

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