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 不會與自身的 DriveActivity 相同時，不會填入其專屬的 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 個類似的動作會分成一組：來自兩個不同使用者的 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 相同。