Drive Activity API 資料模型

本指南將說明 Google Drive Activity API 回應的主要元件，並提供範例及解讀方式。

物品

  • DriveActivity：這是對 Drive Activity API 的查詢傳回的主要資源。內容說明一或多位演員執行一或多個動作，影響一或多個目標。

  • Timestamp 和 TimeRange：分別說明活動發生的單一時間點，或活動發生一段時間的開始和結束時間。

  • 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 相同。