Drive API v2 和 v3 比較指南

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

如要繼續使用 v2，請參閱 Drive API 第 2 版指南修訂條款，瞭解如何為第 2 版開發人員修訂 v3 指南中的部分操作說明。

如要進一步瞭解 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 方法傳回應用程式資料，但會降低效能。在 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 資源已從第 3 版中移除。files 資源的 properties 欄位包含真實的鍵/值組合。properties 欄位包含公開屬性，而 appProperties 欄位包含私人屬性，因此不需要瀏覽權限欄位。
• files 資源中的 modifiedTime 欄位會更新上次任何修改檔案的時間。在 v2 中，只有在您設定 setModifiedDate 欄位時，modifiedDate 欄位才能在更新時變動。
• files 資源中的 viewedByMeTime 欄位不會自動更新。
• 如要匯入 Google 文件格式，您必須在資源主體中設定適當的目標 mimeType。在第 2 版中，您需要設定 ?convert=true。
• 如果系統不支援這種格式，匯入作業會傳回 400 錯誤。
• 讀者和加註者無法查看權限。
• 已移除權限的 me 別名。
• 某些功能可做為要求資源的一部分，但可以做為要求參數使用。例如：
  • 在第 2 版中，您可以使用 children.delete 從上層資料夾移除子項檔案。
  • 在第 3 版中，您將在含有 ?removeParents=parent_id 的子項上使用 files.update。

其他差異

欄位和參數名稱在第 3 版不同。以下列舉幾個例子：

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