本指南將說明 Google Drive Activity API 回應的主要元件,並提供範例及解讀方式。
物品
DriveActivity
:這是對 Drive Activity API 的查詢傳回的主要資源。內容說明一或多位演員執行一或多個動作,影響一或多個目標。Actor
:一般來說,Actor
是使用者。不過,有時系統事件可能會在管理員的身分、管理員本身或不受身分人士執行時觸發Action
。Actor
訊息會封裝這些情況。Target
:Target
是活動的物件 (例如檔案、資料夾、共用雲端硬碟或檔案註解)。請注意,許多動作類型支援多種目標。舉例來說,Edit
通常適用於雲端硬碟檔案,Rename
和Create
等其他動作也適用於雲端硬碟資料夾和共用雲端硬碟。不屬於雲端硬碟項目的目標仍可參照同一個檔案,例如雲端硬碟的根資料夾,或含有檔案註解的上層文件。Action
- 每個DriveActivity
資源都有一或多個相關動作。Action
是獨立式 (例如事件),其中不僅包含動作的詳細類型和資訊,還有Actor
、Target
和Timestamp
或TimeRange
。為避免重複,當這些欄位與整體DriveActivity
相同時,Action
不會填入專屬的Target
、Actor
或時間欄位。ActionDetail
- 這是Action
的特定類型和詳細資訊。舉例來說,Move
動作詳細資料具有來源和目的地位置,PermissionChange
則指定哪些使用者目前可以存取文件,並具備哪些權限。
回覆範例
使用者在雲端硬碟中編輯了檔案:
簡易的 DriveActivity
資源可能只包含一項動作,例如使用者編輯一個檔案。
"activities":[{
"primary_action_detail":{ "edit":{} },
"actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
"targets":[ { "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } } ],
"timestamp":{ "seconds":"1536794657", "nanos":791000000 },
"actions":[ { "detail":{ "edit":{} } } ]
}]
輸出結果包含下列值:
- ACCOUNT_ID:使用者的 ID。也可以與 People API 搭配使用,取得更多資訊。
- ITEM_ID:雲端硬碟項目的 ID。
- TITLE:雲端硬碟項目的標題。
請注意,此回應中的 Action
不包含 Actor
、Target
或 TimeStamp
,因為這些值與整體 DriveActivity
相同。
有兩名使用者在相同時間編輯了同一個檔案:
整合開啟時,相關動作會分組為一個 DriveActivity
。在這個範例中,系統會將 2 個類似的動作分組:有 2 位不同使用者的一個 Edit
動作類型。
"activities":[{
"primary_action_detail":{ "edit":{} },
"actors":[
{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } }
],
"targets":[
{ "drive_item":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
],
"time_range":{
"start_time":{ "seconds":"1541089823", "nanos":712000000 },
"end_time":{ "seconds":"1541089830", "nanos":830000000 }
},
"actions":[
{
"detail":{ "edit":{} },
"actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_1" } } },
"timestamp":{ "seconds":"1541089830", "nanos":830000000 }
},
{
"detail":{ "edit":{} },
"actor":{ "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID_2" } } },
"timestamp":{ "seconds":"1541089823", "nanos":712000000 }
}
]
}]
輸出結果包含下列值:
- ACCOUNT_ID_1:第一位使用者的 ID。也可以與 People API 搭配使用,取得更多資訊。
- ACCOUNT_ID_2:第二位使用者的 ID。
- ITEM_ID:雲端硬碟項目的 ID。
- TITLE:雲端硬碟項目的標題。
請注意,此回應中的動作不含 Target
,因為其與整體 DriveActivity
相同。
此範例也說明應用程式如何只使用 DriveActivity
中的摘要資訊,而不查看個別動作。回應表示有 2 位使用者在一段時間內編輯了指定檔案。
使用者已將 2 個檔案移至新目錄:
在這個範例中,合併策略會將 2 個相關的 Move
動作分組,因為檔案已同時從相同來源移至同一個目的地。
"activities":[{
"primary_action_detail":{
"move":{
"added_parents":[ { ... } ]
"removed_parents":[ { ... } ]
}
},
"actors":[ { "user":{ "known_user":{ "person_name":"people/ACCOUNT_ID" } } } ],
"targets":[
{ "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
{ "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
],
"timestamp":{ "seconds":"1541090960", "nanos":985000000 },
"actions":[
{
"detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
"target":{ "drive_item":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
},
{
"detail":{ "move":{ "added_parents":[ { ... } ] "removed_parents":[ { ... } ] } },
"target":{ "drive_item":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
}
]
}]
輸出結果包含下列值:
- ACCOUNT_ID:使用者的 ID。也可以與 People API 搭配使用,取得更多資訊。
- ITEM_ID_1:第一個雲端硬碟項目的 ID。
- ITEM_ID_2:第二個雲端硬碟項目的 ID。
- TITLE_1:第一個雲端硬碟項目的標題。
- TITLE_2:第二個雲端硬碟項目的標題。
請注意,此回應中的動作不含 Actor
或 TimeStamp
,因為這些動作與整體 DriveActivity
相同。