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。為避免重複，如果 Action 的 Target、Actor 或時間欄位與整體 DriveActivity 相同，就不會填入資料。

  • 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：第一個 Google 雲端硬碟項目的標題。
  • TITLE_2：第二個 Google 雲端硬碟項目的標題。

請注意，這個回應中的動作不包含 Actor 或 TimeStamp，因為它們與整體 DriveActivity 相同。