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

Hướng dẫn này giải thích cách gửi yêu cầu trong API Hoạt động trên 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 nội dung bên dưới hệ phân cấp của thư mục.

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

  • 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 có khoá nào được đặt, theo mặc định, khoá sẽ sử dụng ancestorName của "items/root" và hiển thị hoạt động cho mọi mục trong Drive của bạn.

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 được trả về thực tế sẽ khác nhau, vì vậy, ứng dụng nên 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 thực hiện nhiều yêu cầu bằng cách sử dụng tính năng phân trang thay vì đặt mộ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 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 yêu cầu trên 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 và trả về trong một tài nguyên DriveActivity duy nhất. Một số nhóm Action diễn ra tự phát, 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 sự 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 phân lô) trong yêu cầu. Điều này cho phép các nhóm đối tượng Action khác có liên quan, chẳng hạn như một số diễn viên chỉnh sửa một mục hoặc một Actor di chuyển nhiều tệp vào thư mục Drive mới.

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 diễn viên và nhiều mục tiêu. Tuy nhiên, ngay cả sau khi nhóm lại, luôn có một hành động "chính" mang tính đại diện hoặc quan trọng nhất trong tất 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ù có bật tính năng hợp nhất hay không, nhiều ứng dụng 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 tác nhân và mục tiêu tập thể trong primaryActionDetail) và bỏ qua các thao tác chi tiết trong phản hồi.

Bộ lọc

Bạn có thể hạn chế các thao tác 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ế hành động theo phạm vi thời gian, hãy chỉ định tên trường time với toán tử số trên giá trị ngày, kết hợp bằng "AND" (không bắt buộc). Hãy 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 thao tác, hãy áp dụng tên trường detail.action_detail_case bằng toán tử "có" (:). Dùng giá trị số ít hoặc danh sách các loại thao tác được phép đặt trong 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 xét các đối tượng ActionDetail.

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

Dưới đâ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 duy nhất, 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 cho một mục trên 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 thư mục đối tượng cấp trên:

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

Yêu cầu tất cả thao tác MOVE và RENAME đối với một mục trên 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ả cá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"
}