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ư 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 đượ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.

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.

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 hành động này để trả về các trường không mặc định, nhưng đây là hành động bắt buộc đối với tài nguyên comments. Nếu bạn bỏ qua tham số fields, phương thức này 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 hạn chế đối với bình luận

Các điều kiện ràng buộc sau đây sẽ được thực thi khi bạn làm việc với chú thích được ghim và chú thích không được ghim bằng Drive API:

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

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 một vùng trong tệp mà 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.

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

  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ỉ 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ấ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 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 neo JSON chứa revisionID (r) và khu vực (a).

Mã mẫu sau đây cho biết cách tạo một bình luận được liên kết:

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()

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

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, 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.

Bình luận đượ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ị.

Đoạn mã mẫu sau đây cho biết cách tạo một chú thích không được liên kết:

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()

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 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 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 tôi 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 create trên tài nguyên replies với 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 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 comments 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 tôi 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."
}

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 tôi 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 về 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 tôi 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