Quản lý bình luận và câu trả lời

Nhận xét là ý kiến phản hồi do người dùng cung cấp về một tệp, chẳng hạn như trình đọc tài liệu xử lý văn bản đề xuất cách diễn đạt lại một câu. Có hai loại nhận xét: nhận xét được liên kết và nhận xét không được liên kết. Chú thích được neo được liên kết với một vị trí cụ thể, chẳng hạn như một câu trong tài liệu xử lý văn bản, trong một phiên bản cụ thể của tài liệu. Ngược lại, một nhận xét không liên kết chỉ được liên kết với tài liệu.

Lưu ý: Trên tệp blob, API Google Drive chỉ hỗ trợ các nhận xét không được liên kết. Chúng tôi không hỗ trợ nhận xét được liên kết trên tệp blob hoặc tệp trình chỉnh sửa Google Tài liệu.

Phản hồi được đính kèm vào bình luận và thể hiện phản hồi của người dùng đối với bình luận đó. API Drive cho phép người dùng thêm nhận xét và phản hồi vào các tài liệu do ứng dụng của bạn tạo. Nhìn chung, một nhận xét có các phản hồi được gọi là cuộc thảo luận.

Đối với tất cả phương thức (ngoại trừ delete) trên tài nguyên comments, bạn phải đặt tham số hệ thống fields để chỉ định các trường cần trả về trong phản hồi. Trong hầu hết các phương thức của Drive, thao tác này chỉ bắt buộc để trả về các trường không phải mặc định, nhưng là bắt buộc đối với tài nguyên comments. Nếu bạn bỏ qua tham số này, phương thức sẽ trả về lỗi. Để biết thêm thông tin, hãy xem phần Trả về các trường cụ thể.

Thêm bình luận không liên kết

Để thêm một nhận xét không liên kết vào tài liệu, hãy gọi phương thức create bằng tham số fileId và tài nguyên comments chứa nhận xét.

Chú thích được chèn dưới dạng văn bản thuần tuý, nhưng nội dung phản hồi cung cấp một trường htmlContent chứa nội dung được định dạng để hiển thị.

Lưu ý quan trọng: Bạn nên kiểm tra để đảm bảo người dùng có quyền thích hợp để thêm bình luận. Ngoài ra, chỉ người tạo nhận xét hoặc bình luận trả lời mới có thể xoá hoặc chỉnh sửa nhận xét hoặc bình luận trả lời. Lỗi xảy ra khi người dùng không có vai trò là nhà sáng tạo cố gắng xoá hoặc chỉnh sửa bình luận. Để tránh những lỗi này, hãy kiểm tra trường author.me của tài nguyên comments để đảm bảo rằng người dùng đưa ra yêu cầu là tác giả của bình luận, sau đó xác minh quyền của họ liên quan đến bình luận đó.

Thêm câu trả lời cho một bình luận

Để thêm một câu trả lời cho một bình luận, hãy sử dụng phương thức replies.create trên tài nguyên replies với các tham số fileId và commentId. Nội dung yêu cầu sử dụng trường content để thêm nội dung trả lời.

Nội dung trả lời được chèn dưới dạng văn bản thuần tuý, nhưng nội dung phản hồi cung cấp một trường htmlContent chứa nội dung được định dạng để hiển thị.

Phương thức này trả về các trường được liệt kê trong trường fields.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp các tham số đường dẫn fileId và commentId cũng như nhiều trường.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Nội dung yêu cầu

{
  "content": "This is a reply to a comment."
}

Giải quyết nhận xét

Bạn chỉ có thể giải quyết một bình luận bằng cách đăng nội dung trả lời bình luận đó.

Để giải quyết một nhận xét, hãy sử dụng phương thức replies.create trên tài nguyên replies với các tham số fileId và commentId.

Nội dung yêu cầu sử dụng trường action để phân giải nhận xét. Bạn cũng có thể đặt trường content để thêm một câu trả lời đóng bình luận.

Khi một nhận xét được giải quyết, Drive sẽ đánh dấu tài nguyên nhận xét đó là resolved: true. Không giống như bình luận đã xoá, bình luận đã giải quyết có thể bao gồm các trường htmlContent hoặc content.

Khi ứng dụng của bạn giải quyết một bình luận, giao diện người dùng sẽ cho biết rằng bình luận đó đã được xử lý. Ví dụ: ứng dụng của bạn có thể:

• Không cho phép trả lời thêm và làm mờ tất cả các câu trả lời trước đó cùng với bình luận ban đầu.
• Ẩn nhận xét đã giải quyết.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp các tham số đường dẫn fileId và commentId cũng như nhiều trường.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Nội dung yêu cầu

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

Thêm nhận xét được liên kết vào bản sửa đổi mới nhất của tài liệu

Khi thêm nhận xét, bạn có thể liên kết nhận xét đó với một vùng trong tệp. Neo xác định bản sửa đổi tệp và vùng trong tệp mà nhận xét tham chiếu đến. Tài nguyên comments xác định trường anchor dưới dạng chuỗi JSON.

Lưu ý: Trên tệp blob, API Drive chỉ hỗ trợ các nhận xét không được liên kết. Chúng tôi không hỗ trợ nhận xét được liên kết trên tệp blob hoặc tệp trình chỉnh sửa Google Tài liệu.

Lưu ý quan trọng: Neo là không thể thay đổi và không thể đảm bảo vị trí của neo so với nội dung của tài liệu giữa các lần sửa đổi. Bạn nên sử dụng neo trong các tài liệu mà vị trí không thay đổi, chẳng hạn như tệp hình ảnh hoặc tài liệu chỉ có thể đọc.

Cách thêm bình luận được liên kết:

1. (Tùy chọn). Gọi phương thức revisions.list để liệt kê mọi revisionID cho một tài liệu. Chỉ làm theo bước này nếu bạn muốn liên kết một bình luận với bất kỳ bản sửa đổi nào khác ngoài bản sửa đổi mới nhất. Nếu bạn muốn sử dụng bản sửa đổi mới nhất, hãy sử dụng head cho revisionID.

2. Gọi phương thức create bằng tham số fileID, tài nguyên comments chứa nhận xét và chuỗi neo JSON chứa revisionID (r) và vùng (a).

Cách bạn xác định một vùng phụ thuộc vào loại nội dung tài liệu mà bạn đang xử lý. Để biết thêm thông tin, hãy tham khảo bài viết Xác định khu vực.

Lưu ý: Bạn nên kiểm tra để đảm bảo người dùng có quyền thích hợp để thêm bình luận. Ngoài ra, chỉ người tạo nhận xét hoặc bình luận trả lời mới có thể xoá hoặc chỉnh sửa nhận xét hoặc bình luận trả lời. Lỗi xảy ra khi một người không có vai trò là nhà sáng tạo cố gắng xoá hoặc chỉnh sửa bình luận. Để tránh các lỗi này, hãy kiểm tra trường author.me của tài nguyên comments (bình luận).

Xác định khu vực

Như đã đề cập trước đó, chuỗi neo JSON chứa revisionID (r) và vùng (a). Vùng (a) là một mảng JSON chứa các thuật toán phân loại vùng chỉ định định dạng và vị trí neo một nhận xét. Một thuật toán phân loại có thể là một hình chữ nhật hai chiều cho hình ảnh, một dòng văn bản trong tài liệu hoặc một khoảng thời gian trong video. Để xác định một khu vực, hãy chọn trình phân loại khu vực khớp với loại nội dung mà bạn đang cố gắng liên kết. Ví dụ: nếu nội dung của bạn là văn bản, bạn có thể sẽ sử dụng bộ phân loại khu vực txt hoặc line.

Để biết danh sách các thuật toán phân loại khu vực trong API Drive, hãy tham khảo phần Thuật toán phân loại khu vực.

Ví dụ sau đây cho thấy một chuỗi neo JSON liên kết các nhận xét với các dòng trong hai khu vực riêng biệt của một tài liệu:

• Khu vực đầu tiên bắt đầu từ dòng 12 ('n':12) và kéo dài trong 3 dòng ('l':3).
• Khu vực thứ hai chỉ bao gồm dòng 18 ('n':18, 'l':1`).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Thay thế REVISION_ID bằng head hoặc mã của một bản sửa đổi cụ thể.

Lưu ý quan trọng: Nếu ứng dụng của bạn cho phép người dùng cập nhật và chia sẻ nhiều bản sửa đổi của một tài liệu, thì các nhận xét về các bản sửa đổi cũ có thể không còn áp dụng cho vị trí được liên kết. Do đó, bạn phải chỉ rõ mỗi nhận xét thuộc bản sửa đổi nào trong giao diện người dùng.

Nhận bình luận

Để nhận nhận xét về một tệp, hãy sử dụng phương thức get trên tài nguyên comments với các tham số fileId và commentId. Nếu không biết mã nhận xét, bạn có thể liệt kê tất cả nhận xét bằng phương thức list.

Phương thức này trả về một thực thể của tài nguyên comments.

Để đưa các bình luận đã bị xoá vào kết quả, hãy đặt tham số truy vấn includedDeleted thành true.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp các tham số đường dẫn fileId và commentId cũng như nhiều trường.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Liệt kê nhận xét

Để liệt kê các nhận xét trên một tệp, hãy sử dụng phương thức list trên tài nguyên comments với tham số fileId. Phương thức này trả về danh sách các nhận xét.

Truyền các thông số truy vấn sau để tuỳ chỉnh tính năng phân trang hoặc lọc nhận xét:

• includeDeleted: Đặt thành true để bao gồm cả bình luận đã xoá. Các nhận xét đã xoá không bao gồm trường htmlContent hoặc content.

• pageSize: Số bình luận tối đa được trả về trên mỗi trang.

• pageToken: Mã thông báo trang, nhận được từ một lệnh gọi danh sách trước đó. Cung cấp mã thông báo này để truy xuất trang tiếp theo.

• startModifiedTime: Giá trị tối thiểu của trường modifiedTime cho chú thích kết quả.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp tham số đường dẫn fileId, tham số truy vấn includeDeleted và nhiều trường.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Cập nhật bình luận

Để cập nhật nhận xét về một tệp, hãy sử dụng phương thức update trên tài nguyên comments với các tham số fileId và commentId. Nội dung yêu cầu sử dụng trường content để cập nhật bình luận.

Trường resolved boolean trên tài nguyên comments ở chế độ chỉ đọc. Bạn chỉ có thể giải quyết một bình luận bằng cách đăng nội dung trả lời bình luận đó. Để biết thêm thông tin, hãy xem bài viết Giải quyết bình luận.

Phương thức này trả về các trường được liệt kê trong tham số truy vấn fields.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp các tham số đường dẫn fileId và commentId cũng như nhiều trường.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

Nội dung yêu cầu

{
  "content": "This comment is now updated."
}

Xóa nhận xét

Để xoá một nhận xét trên tệp, hãy sử dụng phương thức delete trên tài nguyên comments với các tham số fileId và commentId.

Khi một bình luận bị xoá, Drive sẽ đánh dấu tài nguyên bình luận đó là deleted: true. Các bình luận đã xoá không bao gồm trường htmlContent hoặc content.

Yêu cầu

Trong ví dụ này, chúng ta cung cấp các tham số đường dẫn fileId và commentId.

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID