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

Bình luận 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ư 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 neo và bình luận không được neo. Bình luận đượ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, bình luận không được neo chỉ được liên kết với tài liệu.

Phản hồi được đính kèm vào bình luận và thể hiện phản ứng của người dùng đối với bình luận đó. API Drive 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. Tập hợp bình luận và phản hồi được gọi là thảo luận.

Sử dụng tham số fields

Đố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 tài nguyên Drive, bạn chỉ cần thực hiện thao tác này để trả về các trường không phải là trường mặc định, nhưng bắt buộc phải thực hiện đối với tài nguyên comments. Nếu bạn bỏ qua tham số fields, 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ể.

Các ràng buộc về bình luận

Các ràng buộc sau đây được thực thi khi bạn làm việc với bình luận được neo và bình luận không được neo bằng API Drive:

Loại bình luận	Loại tệp
Được neo	Nhà phát triển có thể xác định định dạng riêng cho thông số kỹ thuật về điểm neo. Điểm neo được lưu và trả về khi truy xuất bình luận. Tuy nhiên, các ứng dụng trình chỉnh sửa Google Workspace coi những bình luận này là bình luận không được neo.
Không được neo	Được hỗ trợ trên các tài liệu Google Workspace. Các tài liệu này sẽ hiển thị bình luận không được neo trong chế độ xem "Tất cả bình luận". Bình luận không được neo không xuất hiện trên các tệp PDF được kết xuất trong trình xem trước tệp Drive, mặc dù các bình luận này được lưu và có thể truy xuất thông qua API Drive.

Thêm bình luận được neo vào bản sửa đổi mới nhất của tài liệu

Khi thêm bình luận, bạn có thể muốn neo bình luận đó vào một vùng trong tệp. Điểm neo xác định một vùng trong tệp mà bình luận tham chiếu đến. Tài nguyên comments xác định trường anchor là một chuỗi JSON.

Quan trọng: Điểm neo là bất biến và vị trí của điểm neo so với nội dung của tài liệu không được đảm bảo giữa các bản sửa đổi. Bạn nên sử dụng điểm neo trong các 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 neo:

1. (Tùy chọn). Gọi phương thức list trên tài nguyên revisions để liệt kê mọi revisionID cho một tài liệu. Chỉ thực hiện bước này nếu bạn muốn neo một bình luận vào 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 trên tài nguyên comments bằng tham số fileID , tài nguyên comments chứa bình luận và chuỗi điểm neo JSON chứa revisionID (r) và vùng (a).

Mã mẫu sau đây cho thấy cách tạo một bình luận được neo:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

API Drive trả về một thực thể của đối tượng tài nguyên comments, bao gồm chuỗi anchor.

Lưu ý: Chúng tôi khuyên bạn nên kiểm tra để đảm bảo rằng người dùng có quyền phù hợp để thêm bình luận. Ngoài ra, chỉ người tạo bình luận hoặc phản hồi mới có thể xoá hoặc chỉnh sửa bình luận hoặc phản hồi. Lỗi xảy ra khi một người có vai trò không phải là người 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 bình luận.

Thêm bình luận không được neo

Để thêm bình luận không được neo, hãy gọi phương thức create bằng tham số fileId và tài nguyên comments chứa bình luận.

Bình luận đượ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 trường htmlContent chứa nội dung được định dạng để hiển thị.

Mã mẫu sau đây cho thấy cách tạo một bình luận không được neo:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

Quan trọng: Bạn nên kiểm tra để đảm bảo rằng người dùng có quyền phù hợp để thêm bình luận. Ngoài ra, chỉ người tạo bình luận hoặc phản hồi mới có thể xoá hoặc chỉnh sửa bình luận hoặc phản hồi. Lỗi xảy ra khi một người dùng có vai trò không phải là người 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 phản hồi vào bình luận

Để thêm phản hồi vào bình luận, hãy sử dụng phương thức 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 phản hồi.

Phản hồ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 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 tôi cung cấp các tham số đường dẫn fileId và commentId cùng 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 bình luận

Bạn chỉ có thể giải quyết bình luận bằng cách đăng phản hồi cho bình luận đó.

Để giải quyết bình luận, hãy sử dụng create phương thức 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 action để giải quyết bình luận. Bạn cũng có thể đặt trường content để thêm phản hồi đóng bình luận.

Khi một bình luận được giải quyết, Drive sẽ đánh dấu tài nguyên comments 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 của bạn 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 phản hồi thêm và làm mờ tất cả các phản hồi trước đó cùng với bình luận ban đầu.
• Ẩn bình luận đã giải quyết.

Yêu cầu

Trong ví dụ này, chúng tôi cung cấp các tham số đường dẫn fileId và commentId cùng 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."
}

Lấy bình luận

Để lấy bình luận về một tệp, hãy sử dụng get phương thức trên tài nguyên comments bằng các tham số fileId và commentId. Nếu không biết mã bình luận, bạn có thể liệt kê tất cả bình luận 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 bình luận đã xoá vào kết quả, hãy đặt tham số truy vấn includedDeleted query parameter thành true.

Yêu cầu

Trong ví dụ này, chúng tôi cung cấp các tham số đường dẫn fileId và commentId cùng 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ê bình luận về một tệp, hãy sử dụng list phương thức trên tài nguyên comments bằng tham số fileId. Phương thức này trả về danh sách bình luận.

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

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

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

• pageToken: Mã thông báo trang, nhận được 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 bình luận kết quả.

Yêu cầu

Trong ví dụ này, chúng tôi 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 về 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. 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 là trường chỉ đọc. Bạn chỉ có thể giải quyết bình luận bằng cách đăng phản hồi cho bình luận đó. Để biết thêm thông tin, hãy xem phần 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 tôi cung cấp các tham số đường dẫn fileId và commentId cùng 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."
}

Xoá bình luận

Để xoá bình luận về một tệp, hãy sử dụng phương thức delete trên tài nguyên comments bằng 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 đã 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 tôi 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

Chủ đề có liên quan

• Tổng quan về tệp và thư mục
• Quản lý bản sửa đổi tệp