本指南將說明 Google Drive Activity API 回應的主要元件,並提供範例及解讀方式。
物件
DriveActivity
:這是向 Drive Activity API 的查詢傳回的主要資源。說明一或多個執行者執行會影響一或多個目標的動作。Actor
:Actor
通常是使用者。不過,當管理員以使用者或自己身分執行,或由無法識別身分的人員執行時,系統事件有時可能會觸發Action
。Actor
訊息會封裝以下每個情況。Target
:Target
是活動的物件,例如檔案、資料夾、共用雲端硬碟或檔案註解。請注意,許多動作類型都支援多個目標類型。舉例來說,Edit
通常適用於雲端硬碟檔案,Rename
和Create
等其他動作也適用於雲端硬碟資料夾和共用雲端硬碟。非雲端硬碟項目的目標仍可參照單一項目,例如雲端硬碟的根資料夾,或是包含檔案註解的上層文件。Action
:每個DriveActivity
資源都有一或多個相關動作。Action
是獨立的事件,例如事件,其不僅包含動作的詳細類型和資訊,也同時包含Actor
、Target
,以及Timestamp
或TimeRange
。為避免重複,當Action
與整體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。這個 API 可以與 People API 搭配使用以取得更多資訊。
- ITEM_ID:雲端硬碟項目的 ID。
- TITLE:雲端硬碟項目的名稱。
請注意,此回應中的 Action
不包含 Actor
、Target
或 TimeStamp
,因為這與整個 DriveActivity
相同。
兩位使用者在同一時間編輯過同一個檔案:
開啟整合時,系統會將相關動作歸類為一個 DriveActivity
。在這個範例中,2 個相似的動作分為:一種 Edit
動作類型,來自 2 位不同的使用者。
"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。這個 API 可與 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。這個 API 可以與 People API 搭配使用以取得更多資訊。
- ITEM_ID_1:第一個雲端硬碟項目的 ID。
- ITEM_ID_2:第二個雲端硬碟項目的 ID。
- TITLE_1:第一個雲端硬碟項目的名稱。
- TITLE_2:第二個雲端硬碟項目的名稱。
請注意,此回應中的動作不包含 Actor
或 TimeStamp
,因為這與整個 DriveActivity
相同。