本指南說明 Google Drive Activity API v1 和 v2 之間的差異,以及如何變更 v1 應用程式以支援 v2 API。
授權
v1 API 使用這個範圍:
https://www.googleapis.com/auth/activity
v2 API 需要下列其中一個範圍:
https://www.googleapis.com/auth/drive.activity
https://www.googleapis.com/auth/drive.activity.readonly
資源名稱
在 v1 API 中,Google 雲端硬碟項目和使用者等物件的 ID 是不透明字串。在 v2 API 中,這些物件通常是以資源名稱進行參照。詳情請參閱 Cloud API 設計指南。
這類 ID 通常可以轉換。舉例來說,系統會使用資源名稱 items/ITEM_ID_V1
參照 v2 API 中的雲端硬碟項目。
要求數量
第 2 版的要求格式與第 1 版類似。具體來說,您仍然可以要求雲端硬碟檔案或雲端硬碟祖系的活動,但請注意,您必須將要求參數的格式設為資源名稱,並在前面加上 items/
。
「分組」現已改稱合併,且已移除 source
和 userId
要求參數。
此外,您還可以使用新的「篩選器」選項來限制回應中傳回的活動資料類型。
動作
在 v1 API 中,活動類型以及與該活動相關聯的資料位於不同欄位中。舉例來說,如果 primaryEventType
欄位包含 move
值,應用程式會假設頂層 move
欄位已填入新增及移除的父項。
在第 2 版 API 中,這些欄位不再不同。ActionDetail
訊息只設有一個欄位。此屬性代表動作類型,包含與動作相關的詳細資料。舉例來說,代表移動的 ActionDetail
只會設定 move
欄位,而該欄位會列出新增及移除的父項。
v1 API 的 primaryEventType
欄位大致對應至第 2 版 primaryActionDetail
。
Actors
在 v1 API 中,如果執行者是已知的使用者,傳回的活動會包含 User
,而且可視需要包含頂層欄位,例如 fromUserDeletion
。
在 v2 API 中,您可以使用更豐富的 Actor
類型,並在執行者是已知使用者時填入 user.knownUser
。如果應用程式需要使用者的詳細資訊,可以傳遞 KnownUser
欄位 personName
給 people.get
方法,從 People API 中查詢。
目標
在 v1 API 中,目標一律為雲端硬碟項目。在 v2 API 中,目標可以是雲端硬碟中的其他物件類型。例如,對磁碟機所做的變更具有 Drive
的目標類型。系統仍會傳回共用雲端硬碟的根資料夾 (以 root
欄位中的 DriveItem
表示),但這不是活動的立即目標。類似的概念也適用於 FileComment
資源,該資源的 parent
欄位會參照包含目標註解執行緒的雲端硬碟項目。
合併活動
在 v1 API 中,若設定整合 (「分組」) 策略,回應樣式就會改變。具體來說,在整合功能開啟時,每個活動都會包含組成 singleEvents
和 combinedEvent
,其中彙整了這些組成事件的常見活動。整合關閉時,combinedEvent
欄位會包含每個活動的原始未合併事件。這些事件都可能代表多種動作,例如建立和分享項目。
在 v2 API 中,回應樣式不會根據整合策略而變更,因為傳回的 DriveActivity
一律包含完整的演員、目標和動作。