Mô hình dữ liệu Drive Activity API

Hướng dẫn này giải thích các thành phần chính của phản hồi trong Google Drive Activity API, đồng thời trình bày các ví dụ và cách diễn giải các phản hồi đó.

Đối tượng

  • DriveActivity – Đây là tài nguyên chính do các truy vấn trả về API Hoạt động Drive. Phương diện này mô tả một hoặc nhiều đối tượng thực hiện một hoặc nhiều hành động ảnh hưởng đến một hoặc nhiều mục tiêu.

  • Timestamp và TimeRange – Các giá trị này lần lượt mô tả một thời điểm duy nhất khi hoạt động xảy ra, hoặc thời điểm bắt đầu và kết thúc khi hoạt động xảy ra trong một khoảng thời gian.

  • Actor – Thông thường, Actor là người dùng cuối. Tuy nhiên, đôi khi, một sự kiện hệ thống có thể kích hoạt Action khi quản trị viên đóng vai trò là người dùng hoặc là chính họ, hoặc khi được thực hiện bởi một người không thể xác định danh tính. Thông báo Actor đóng gói từng trường hợp trong số này.

  • Target – Target là đối tượng của một hoạt động, chẳng hạn như tệp, thư mục, bộ nhớ dùng chung hoặc nhận xét về tệp. Lưu ý rằng nhiều loại hành động hỗ trợ nhiều loại mục tiêu. Ví dụ: mặc dù Edit thường áp dụng cho các tệp trong Drive, nhưng các thao tác khác như Rename và Create cũng có thể áp dụng cho các thư mục trong Drive và bộ nhớ dùng chung. Những mục tiêu không phải là các mục trên Drive vẫn có thể tham chiếu đến một mục, chẳng hạn như thư mục gốc của ổ đĩa hoặc tài liệu gốc có chứa nhận xét về tệp.

  • Action – Mỗi tài nguyên DriveActivity có một hoặc nhiều hành động liên quan. Action độc lập, giống như một sự kiện, ở chỗ nó không chỉ bao gồm loại và thông tin chi tiết về hành động mà còn bao gồm Actor, Target và Timestamp hoặc TimeRange. Để tránh tình trạng dư thừa, Action không điền sẵn Target, Actor hoặc trường thời gian khi các trường đó giống với DriveActivity tổng thể.

  • ActionDetail – Đây là loại cụ thể và thông tin chi tiết về Action. Ví dụ: chi tiết thao tác Move có vị trí nguồn và đích, còn PermissionChange chỉ định những người hiện có thể truy cập vào một tài liệu và có các đặc quyền.

Câu trả lời mẫu

Một người dùng đã chỉnh sửa một tệp trong Drive:

Tài nguyên DriveActivity đơn giản có thể chỉ bao gồm một thao tác, chẳng hạn như người dùng chỉnh sửa một tệp.

"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":{} } } ]
}]

Kết quả này bao gồm các giá trị sau:

  • ACCOUNT_ID: mã nhận dạng của người dùng. Bạn có thể sử dụng API này với API Mọi người để nhận thêm thông tin.
  • ITEM_ID: Mã của mục trên Drive.
  • TITLE: tiêu đề của mục trên Drive.

Lưu ý rằng Action trong phản hồi này không bao gồm Actor, Target hoặc TimeStamp vì chúng giống với DriveActivity tổng thể.

Hai người dùng đã chỉnh sửa cùng một tệp vào những thời điểm giống nhau:

Khi bật tính năng hợp nhất, các hành động liên quan sẽ được nhóm thành một DriveActivity. Trong ví dụ này, 2 hành động tương tự được nhóm lại: một loại hành động Edit từ 2 người dùng khác nhau.

"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 }
    }
  ]
}]

Kết quả này bao gồm các giá trị sau:

  • ACCOUNT_ID_1: mã nhận dạng của người dùng đầu tiên. Bạn có thể sử dụng API này với People API để biết thêm thông tin.
  • ACCOUNT_ID_2: mã nhận dạng của người dùng thứ hai.
  • ITEM_ID: Mã của mục trên Drive.
  • TITLE: tiêu đề của mục trên Drive.

Lưu ý rằng các hành động trong phản hồi này không bao gồm Target vì nó giống với DriveActivity tổng thể.

Ví dụ này cũng minh hoạ cách các ứng dụng có thể chỉ sử dụng thông tin tóm tắt trong DriveActivity mà không xem xét từng thao tác. Phản hồi cho biết 2 người dùng đã chỉnh sửa một tệp nhất định trong một khoảng thời gian.

Một người dùng đã di chuyển 2 tệp vào một thư mục mới:

Trong ví dụ này, chiến lược hợp nhất đã nhóm 2 hành động Move có liên quan vì các tệp được di chuyển từ cùng một nguồn sang cùng một đích đến tại cùng một thời điểm.

"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":{} } }
    }
  ]
}]

Kết quả này bao gồm các giá trị sau:

  • ACCOUNT_ID: mã nhận dạng của người dùng. Bạn có thể sử dụng API này với API Mọi người để nhận thêm thông tin.
  • ITEM_ID_1: Mã của mục đầu tiên trên Drive.
  • ITEM_ID_2: Mã của mục thứ hai trên Drive.
  • TITLE_1: tiêu đề của mục đầu tiên trên Drive.
  • TITLE_2: tiêu đề của mục thứ hai trên Drive.

Lưu ý rằng các hành động trong phản hồi này không bao gồm Actor hoặc TimeStamp vì chúng giống với DriveActivity tổng thể.