Drive API v2 和 v3 比較指南

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

如要繼續使用第 2 版，請參閱「Drive API 第 2 版指南」修訂內容，瞭解第 3 版指南中的部分操作說明，如何為第 2 版開發人員進行修訂。

如要進一步瞭解 Drive API v3 的改良之處，請觀看下列影片，聽取 Google 工程師討論新版 API 設計。

V3 改善項目

為提升效能及簡化 API 行為，v3 相較於舊版 API 有下列改良之處：

• 根據預設，搜尋檔案和共用雲端硬碟不會傳回完整資源，只會傳回常用欄位的子集。如要進一步瞭解 fields，請參閱 files.list 方法和 drives.list 方法。
• 現在，幾乎所有會傳回回應的方法都需要 fields 參數。如要查看需要 fields 的所有方法清單，請參閱 Drive API 參考資料。
• 已移除功能重複的資源。舉例來說：
  • files.list 方法可達成與 Children 和 Parents 集合相同的用途，因此已從第 3 版中移除。
  • 已移除 Realtime.* 方法。
• 根據預設，搜尋結果不會顯示應用程式資料。在第 2 版中，您可以設定 drive.appdata 範圍，並從 files.list 方法和 changes.list 方法傳回應用程式資料，但這會降低效能。在第 3 版中，您會設定 drive.appdata 範圍，並設定查詢參數 spaces=appDataFolder 來要求應用程式資料。
• 所有更新作業都會使用 PATCH，而非 PUT。
• 如要匯出 Google 文件，請使用 files.export 方法。
• changes.list 方法的行為有所不同。請改用不透明網頁權杖，而非變更 ID。如要輪詢變更集合，請先呼叫 changes.getStartPageToken 方法取得初始值。後續查詢時，changes.list 方法會傳回 newStartPageToken 值。
• 更新方法現在會拒絕指定不可寫入欄位的要求。
• about 資源中的 v2 exportFormats 和 importFormats 欄位是允許匯入或匯出格式的清單。在第 3 版中，這些是可能目標的 MIME 類型對應，適用於所有支援的匯入或匯出作業。
• v2 的 appdata 和 appfolder 別名現在是 v3 的 appDataFolder。
• 系統會從 v3 移除 properties 資源。files 資源具有 properties 欄位，其中包含實際的鍵/值組合。properties 欄位包含公開屬性，appProperties 欄位包含私人屬性，因此不需要瀏覽權限欄位。
• files 資源中的 modifiedTime 欄位會更新檔案上次修改的時間。在第 2 版中，只有在設定 setModifiedDate 欄位時，才能在更新時變更 modifiedDate 欄位。
• files 資源中的 viewedByMeTime 欄位不會自動更新。
• 如要匯入 Google 文件格式，請在資源主體中設定適當的目標 mimeType。在第 2 版中，您會設定 ?convert=true。
• 如果格式不受支援，匯入作業會傳回 400 錯誤。
• 讀者和加註者無法查看權限。
• 移除權限的 me 別名。
• 部分功能原本是要求資源的一部分，但現在改為要求參數。例如：
  • 在第 2 版中，您可以使用 children.delete 從上層資料夾移除子項檔案。
  • 在第 3 版中，您會在網址中使用 files.update，對子項使用 ?removeParents=parent_id。

其他差異

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

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