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

Bình luận là ý kiến phản hồi của người dùng về một tệp, chẳng hạn như một người đọ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 bình luận: bình luận được ghim và bình luận không được ghim. Chú thích được ghim sẽ đượ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 được liên kết chỉ liên quan đến tài liệu.

Lưu ý: Đối với tệp blob, Google Drive API chỉ hỗ trợ 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. Drive API cho phép người dùng thêm bình luận 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 bình luận có phản hồi được gọi là cuộc thảo luận.

Đối với tất cả các phương thức (ngoại trừ delete) trên tài nguyên comments, bạn phải đặt fields tham số hệ thống để 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 Drive, bạn chỉ cần thực hiện thao tác này để trả về các trường không mặc định, nhưng đây là thao tác 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 một bình luận không được liên kết

Để thêm một nhận xét không được 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.

Nhận xét được chèn dưới dạng văn bản thuần tuý, nhưng phần 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 phù hợp để thêm nhận xét. Ngoài ra, chỉ nhà sáng tạo của một bình luận hoặc câu trả lời mới có thể xoá hoặc chỉnh sửa bình luận hoặc câu trả lời đó. Lỗi xảy ra khi người dùng không phải 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ọ đối với bình luận.

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

Để thêm 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 bằng các tham số fileId và commentId. Nội dung yêu cầu sử dụng trường content để thêm câu trả lời.

Phản hồi được chèn dưới dạng văn bản thuần tuý, nhưng phần 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 sẽ 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 câu trả lời cho bình luận đó.

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

Phần nội dung yêu cầu sử dụng trường action để giải quyết bình luận. Bạn cũng có thể đặt trường content để thêm 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 đã bị 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 nhận xét, giao diện người dùng của bạn phải cho biết rằng nhận xét đó đã được giải quyết. 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 như bình luận gốc.
• Ẩn nhận xét đã giải quyết.

Yêu cầu

Trong ví dụ này, chúng ta sẽ 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 ghim 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ể muốn liên kết nhận xét đó với một vùng trong tệp. Điểm neo xác định phiên bản tệp và khu vực trong một tệp mà một bình luận đề cập đến. Tài nguyên comments xác định trường anchor dưới dạng một chuỗi JSON.

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

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

Cách thêm bình luận được ghim:

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 nhận xét với bản sửa đổi bất kỳ, ngoại trừ 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 dùng head cho revisionID.

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

Cách bạn xác định một khu vực phụ thuộc vào loại nội dung tài liệu mà bạn đang làm việc. Để 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 phù hợp để thêm nhận xét. Ngoài ra, chỉ nhà sáng tạo của một bình luận hoặc câu trả lời mới có thể xoá hoặc chỉnh sửa bình luận hoặc câu 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 một revisionID (r) và khu vực (a). Khu vực (a) là một mảng JSON chứa trình phân loại khu vực chỉ định định dạng và vị trí mà một bình luận được neo vào. Trình 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 phân loại khu vực phù hợ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, thì có thể bạn sẽ sử dụng trình phân loại khu vực txt hoặc line.

Để xem danh sách các trình phân loại khu vực trong Drive API, hãy tham khảo Trình phân loại khu vực.

Ví dụ sau đây minh hoạ một chuỗi neo JSON neo các nhận xét vào các dòng ở hai khu vực riêng biệt của một tài liệu:

• Vùng đầu tiên bắt đầu từ dòng 12 ('n':12) và kéo dài trong 3 dòng ('l':3).
• Vùng 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ã nhận dạng của một bản sửa đổi cụ thể.

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 bình luận về những bản sửa đổi cũ có thể không còn áp dụng cho vị trí được neo nữa. Do đó, bạn phải cho biết rõ từng nhận xét thuộc về bản sửa đổi nào trong giao diện người dùng.

Nhận bình luậ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 bằng 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 sẽ 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ê bình luận

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

Truyền các tham số truy vấn sau để tuỳ chỉnh việc phân trang hoặc lọc bình luận:

• includeDeleted: Đặt thành true để thêm bình luận đã bị xoá. Bình luận đã xoá không có trường htmlContent hoặc content.

• pageSize: Số lượng bình luận tối đa cần trả về cho 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 các nhận xét về 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 bình luận trên một tệp, hãy sử dụng phương thức update trên tài nguyên comments bằng các tham số fileId và commentId. Phần nội dung yêu cầu sử dụng trường content để cập nhật bình luận.

Trường boolean resolved 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 câu trả lời cho 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 sẽ 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 bình luận trên tệp, hãy 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. Bình luận đã bị xoá không bao gồm các 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