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 một phản hồi trong API Hoạt động trên Google Drive, đưa ra ví dụ và cách diễn giải các thành phần đó.

Đối tượng

• DriveActivity – Đây là tài nguyên chính do các truy vấn trả về cho API Hoạt động trên Drive. Nó mô tả một hoặc nhiều thực thể 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 thuộc tính 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 của 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 đang đóng vai trò là người dùng hoặc là chính họ, hoặc khi một người không xác định thực hiện. 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. Xin 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 trên Drive, nhưng các thao tác khác như Rename và Create cũng có thể áp dụng cho thư mục trên Drive và bộ nhớ dùng chung. Các mục tiêu không phải là 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 một ổ hoặc tài liệu mẹ 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 là một thành phần độc lập, giống như một sự kiện, trong đó 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 các trường Target, Actor hoặc thời gian của riêng mình 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ụ: thông tin chi tiết về hành động Move có vị trí nguồn và đích đến, còn PermissionChange chỉ định người hiện có thể truy cập vào tài liệu và với những đặc quyền nào.

Ví dụ về câu trả lời

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

Một tài nguyên DriveActivity đơn giản có thể chỉ bao gồm một hành động, 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 People để biết thêm thông tin.
• ITEM_ID: mã nhận dạng của mục trên Drive.
• TITLE: tiêu đề của mục trên Drive.

Xin lưu ý rằng Action trong phản hồi này không bao gồm Actor, Target hoặc TimeStamp vì các giá trị này 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 tương tự nhau:

Khi bạn bật tính năng hợp nhất, các thao tác có 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 với nhau: một loại hành động Edit của 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 API People để 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ã nhận dạng của mục trên Drive.
• TITLE: tiêu đề của mục trên Drive.

Xin lưu ý rằng các hành động trong phản hồi này không bao gồm Target vì hành động này 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 hành động riêng lẻ. 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 thao tác Move liên quan với nhau vì các tệp được di chuyển từ cùng một nguồn đến cùng một đích đến cùng một lúc.

"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 People để biết 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.

Xin 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ì các hành động này giống với DriveActivity tổng thể.