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":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "driveItem":{ "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 相同。

兩位使用者在相近時間編輯同一個檔案

使用 ConsolidationStrategy 時，系統會將相關動作分組為一個合併的 DriveActivity。在這個範例中，兩個類似的動作會歸為一組：兩位使用者各有一個 Edit 動作類型。

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "timeRange":{
    "startTime":{ "seconds":"1541089823", "nanos":712000000 },
    "endTime":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } },
      "timestamp":{ "seconds":"1541089823", "nanos":712000000 }
    }
  ]
}]

輸出內容包含下列值：

  • ACCOUNT_ID_1：第一個使用者的 ID。您可以搭配使用 People API 取得更多資訊。
  • ACCOUNT_ID_2：第二位使用者的 ID。
  • ITEM_ID：雲端硬碟項目 ID。
  • TITLE：雲端硬碟項目的標題。

請注意，這個回應中的 Action 物件不包含 Target，因為它與整體 DriveActivity 相同。

這個範例也說明應用程式如何只使用 DriveActivity 中的摘要資訊，而不查看個別動作。回應表示兩位使用者在一段時間內編輯了特定檔案。

使用者將兩個檔案移至新目錄

在本例中，ConsolidationStrategy 將兩個相關的 Move 動作分組，因為檔案是從相同來源移至相同目的地。

"activities":[{
  "primaryActionDetail":{
    "move":{
      "addedParents":[ { ... } ]
      "removedParents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "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 雲端硬碟項目的標題。

請注意，這個回應中的 Action 物件不包含 Actor 或 timestamp，因為它們與整體 DriveActivity 相同。