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 mà các truy vấn trả về cho API Hoạt động trong Drive. 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 giá trị này mô tả lần lượ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 đang đóng vai trò là người dùng hoặc 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, ổ đĩa 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 thao tác liên quan. Action là một loại dữ liệu độ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 trùng lặp, Action không điền sẵn các trường Target, Actor hoặc thời gian của riêng nó 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à có những đặc quyền nào.

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

Hãy xem nội dung sau để biết các câu trả lời mẫu.

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

Một tài nguyên DriveActivity 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":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[ { "driveItem":{ "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 đối tượng Action trong phản hồi này không bao gồm Actor, Target hoặc timestamp vì các đối tượng 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 thời điểm tương tự nhau

Khi sử dụng ConsolidationStrategy, các thao tác có liên quan sẽ được nhóm thành một DriveActivity kết hợp. Trong ví dụ này, hai hành động tương tự nhau được nhóm lại với nhau: một loại hành động Edit của hai người dùng khác nhau.

"activities":[{
  "primaryActionDetail":{ "edit":{} },
  "actors":[
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
    { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_2" } } }
  ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID", "title":"TITLE", "file":{} } }
  ],
  "timeRange":{
    "startTime":{ "seconds":"1541089823", "nanos":712000000 },
    "endTime":{ "seconds":"1541089830", "nanos":830000000 }
  },
  "actions":[
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID_1" } } },
      "timestamp":{ "seconds":"1541089830", "nanos":830000000 }
    },
    {
      "detail":{ "edit":{} },
      "actor":{ "user":{ "knownUser":{ "personName":"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 đối tượng Action trong phản hồi này không bao gồm Target vì đối tượ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. Phản hồi cho biết hai người dùng đã chỉnh sửa một tệp nhất định trong một khoảng thời gian.

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

Trong ví dụ này, ConsolidationStrategy đã nhóm hai 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":[{
  "primaryActionDetail":{
    "move":{
      "addedParents":[ { ... } ]
      "removedParents":[ { ... } ]
    }
  },
  "actors":[ { "user":{ "knownUser":{ "personName":"people/ACCOUNT_ID" } } } ],
  "targets":[
    { "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } },
    { "driveItem":{ "name":"items/ITEM_ID_2", "title":"* TITLE_2", "file":{} } }
  ],
  "timestamp":{ "seconds":"1541090960", "nanos":985000000 },
  "actions":[
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "name":"items/ITEM_ID_1", "title":"TITLE_1", "file":{} } }
    },
    {
      "detail":{ "move":{ "addedParents":[ { ... } ] "removedParents":[ { ... } ] } },
      "target":{ "driveItem":{ "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 đối tượng Action trong phản hồi này không bao gồm Actor hoặc timestamp vì các đối tượng này giống với DriveActivity tổng thể.