Đưa ra yêu cầu trong Google Drive Activity API

Hướng dẫn này giải thích cách tạo yêu cầu trong API Hoạt động của Google Drive bằng phương thức activity.query.

Khoá truy vấn

Có 2 cách để yêu cầu hoạt động: theo mục trên Google Drive hoặc cho mọi mục trong hệ thống phân cấp thư mục.

  • itemName: Định dạng của khoá này là "items/ITEM_ID". Thông thường, đây là một tệp trong Drive. Nếu bạn chỉ định một thư mục cho khoá này, thì khoá này sẽ hiển thị hoạt động của thư mục đó, chẳng hạn như thời điểm tạo hoặc đổi tên thư mục.

  • ancestorName: Định dạng của khoá này là "items/ITEM_ID" và phản hồi bao gồm hoạt động trên tất cả các mục trong cây con bên dưới thư mục này.

Khi không đặt khoá nào, hệ thống sẽ mặc định sử dụng ancestorName của "items/root" và hiển thị hoạt động cho tất cả các mục trong Drive.

Phân trang

Trường pageSize cho phép bạn yêu cầu số lượng hoạt động gần đúng để trả về trong mỗi phản hồi. Số lượng hoạt động thực tế được trả về sẽ khác nhau, vì vậy, ứng dụng của bạn phải xử lý số lượng tuỳ ý trong phản hồi.

Kích thước trang bị giới hạn. Nếu ứng dụng của bạn cần nhiều hoạt động, hãy tạo nhiều yêu cầu bằng cách phân trang thay vì đặt giá trị lớn cho pageSize. Cụ thể, nếu có thể có nhiều hoạt động cần tìm nạp hơn so với nội dung có trong phản hồi, thì phản hồi đó cũng sẽ chứa nextPageToken. Để truy xuất thêm kết quả, hãy lặp lại cùng một yêu cầu nhưng thêm trường pageToken có giá trị nextPageToken từ phản hồi trước đó.

Hợp nhất

Các đối tượng Action thường được nhóm lại và trả về trong một tài nguyên DriveActivity. Một số nhóm Action xảy ra một cách tự nhiên, chẳng hạn như việc di chuyển một mục vào thư mục dùng chung sẽ kích hoạt thay đổi quyền.

Bạn cũng có thể chỉ định một ConsolidationStrategy (đôi khi được gọi là tổng hợp hoặc tạo lô) trong yêu cầu. Điều này cho phép các nhóm khác của các đối tượng Action có liên quan, chẳng hạn như một số đối tượng chỉnh sửa một mục hoặc một Actor di chuyển nhiều tệp vào một thư mục mới trên Drive.

Mặc dù một Action riêng lẻ có một Actor và một Target, nhưng sau khi nhóm, DriveActivity thu được có thể có nhiều đối tượng và nhiều mục tiêu. Tuy nhiên, ngay cả sau khi nhóm, luôn có một hành động "chính" đại diện hoặc quan trọng nhất trong tất cả các hành động trong tài nguyên DriveActivity, tuỳ thuộc vào chiến lược hợp nhất được yêu cầu.

Do đó, cho dù bạn có bật tính năng hợp nhất hay không, nhiều ứng dụng có thể chỉ cần xem nội dung cấp cao nhất của tài nguyên DriveActivity (chẳng hạn như các thực thể và mục tiêu tập thể trong primaryActionDetail) và bỏ qua các hành động chi tiết trong phản hồi.

Bộ lọc

Bạn có thể hạn chế các hành động có thể được trả về trong tài nguyên DriveActivity bằng cách tạo một chuỗi filter trong yêu cầu activity.query. Có 2 trường được hỗ trợ: time và detail.action_detail_case.

Lọc theo thời gian

Để hạn chế các hành động theo phạm vi thời gian, hãy chỉ định tên trường time bằng toán tử số trên giá trị ngày, được nối với "AND" (không bắt buộc). Sử dụng mili giây kể từ ngày 1 tháng 1 năm 1970 hoặc định dạng RFC 3339, chẳng hạn như:

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

Lọc theo loại

Để hạn chế theo loại hành động, hãy áp dụng tên trường detail.action_detail_case với toán tử "có" (:). Sử dụng một giá trị số ít hoặc danh sách các loại hành động được phép được đặt trong dấu ngoặc đơn, phân tách bằng dấu cách. Để tìm danh sách các loại hành động, hãy xem lại các đối tượng ActionDetail.

Để loại trừ một loại hành động khỏi phản hồi, hãy thêm dấu gạch nối (-) vào đầu chuỗi bộ lọc.

Sau đây là một số ví dụ về loại hành động:

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

Kết hợp

Bạn có thể kết hợp các điều kiện lọc này trong một chuỗi filter, chẳng hạn như:

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

Yêu cầu mẫu

Yêu cầu 10 hoạt động gần đây nhất đối với một mục trong Drive:

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

Yêu cầu hoạt động tổng hợp cho mọi mục trên Drive bên dưới một thư mục gốc:

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

Yêu cầu tất cả thao tác MOVE và RENAME trên một mục trong Drive:

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

Yêu cầu tất cả hoạt động kể từ ngày 1 tháng 1 năm 2018 theo giờ EST:

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

Yêu cầu tất cả hoạt động, ngoại trừ các hành động EDIT, trong tháng 6 năm 2017 theo giờ UTC:

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