透過 Google Drive Activity API 提出要求

本指南說明如何使用 activity.query 方法,在 Google Drive Activity API 中提出要求。

查詢鍵

有 2 種方法可以要求活動:依 Google 雲端硬碟項目,或資料夾階層底下的所有項目。

  • itemName:這個鍵的格式為「items/ITEM_ID」。通常是雲端硬碟中的檔案。如果為這個金鑰指定資料夾,系統會顯示該資料夾的活動,例如建立或重新命名的時間。

  • ancestorName:此鍵的格式為「items/ITEM_ID」,且回應包含此資料夾下方子樹狀結構中所有項目的活動。

如未設定鍵,系統預設會使用「items/root」的 ancestorName,並顯示雲端硬碟中的所有項目的活動。

分頁

pageSize 欄位可讓您要求在每次回應中傳回活動的約略數量。實際傳回的活動數量會因實際情況而有所不同,因此應用程式應在回應中處理任意數量。

頁面大小有限,如果應用程式需要多項活動,請使用分頁提出多項要求,不要為 pageSize 設定較大的值。具體來說,如果要擷取的活動可能比回應內容更多,則回應也會包含 nextPageToken。如要擷取更多結果,請重複相同的要求,但新增具有先前回應中 nextPageToken 值的 pageToken 欄位。

整合

Action 物件通常會在單一 DriveActivity 資源中分組及傳回。部分 Action 群組會同時發生,例如將項目移至共用資料夾,觸發權限變更。

您也可以在要求中指定 ConsolidationStrategy (有時稱為匯總或批次處理)。這樣就能啟用其他相關的 Action 物件分組,例如多位演員編輯一個項目,或是一個 Actor 將多個檔案移至新的雲端硬碟資料夾。

雖然個別 Action 有一個 Actor 和一個 Target,但在分組後,產生的 DriveActivity 可能會有多個演員和多個目標。然而,即使在分組後,DriveActivity 資源中仍會有代表性或最重要的「主要」動作,視要求的整合策略而定。

因此,無論整合是否啟用,都可能足以讓許多用戶端只查看 DriveActivity 資源的頂層內容 (例如 primaryActionDetail 中的集體執行者和目標),並忽略回應中的詳細動作。

篩選器

您可以在 activity.query 要求中建構 filter 字串,以限制 DriveActivity 資源中可能傳回的動作。系統支援 timedetail.action_detail_case 2 個欄位。

依時間篩選

如要依照時間範圍限制動作,請指定欄位名稱 time 搭配日期值的數值運算子,並以選用的「AND」連結。請使用 1970 年 1 月 1 日或 RFC 3339 格式之後的毫秒數,例如:

  • time > 1452409200000 AND time <= 1492812924310
  • time >= "2016-01-10T01:02:03-05:00"

依類型篩選

如要依照動作類型限制,請使用「has」運算子 (:) 套用欄位名稱 detail.action_detail_case。請使用單數值或用括號括住的允許動作類型清單,並以空格分隔。如需動作類型的清單,請參閱 ActionDetail 物件。

如要從回應中排除動作類型,請在篩選器字串的開頭加上連字號 (-)。

以下是一些動作類型範例:

  • detail.action_detail_case:RENAME
  • detail.action_detail_case:(CREATE RESTORE)
  • -detail.action_detail_case:MOVE

組合

這些篩選條件可以在單一 filter 字串中合併,例如:

  • detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

要求範例

要求取得一個雲端硬碟項目的最新 10 個活動:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

針對祖系資料夾下每個雲端硬碟項目要求合併活動:

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

要求對雲端硬碟項目執行所有MOVERENAME操作:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

要求自 2018 年 1 月 1 日以來的所有活動 (美國東部標準時間):

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

要求在 2017 年 6 月 (世界標準時間) 以外的所有活動 (EDIT 項動作除外):

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}