จัดการความคิดเห็นและการตอบกลับ

ความคิดเห็น คือความคิดเห็นที่ผู้ใช้แสดงต่อไฟล์ เช่น ผู้อ่านเอกสารประมวลผลคำแนะนำให้ปรับคำพูดในประโยคใหม่ ความคิดเห็นมี 2 ประเภท ได้แก่ ความคิดเห็นที่ยึดกับตำแหน่ง และ ความคิดเห็นที่ไม่ยึดกับตำแหน่ง ความคิดเห็นที่ยึดกับตำแหน่งจะเชื่อมโยงกับตำแหน่งที่เฉพาะเจาะจง เช่น ประโยคในเอกสารประมวลผลคำ ภายในเวอร์ชันที่เฉพาะเจาะจงของเอกสาร ในทางกลับกัน ความคิดเห็นที่ไม่ยึดกับตำแหน่งจะเชื่อมโยงกับเอกสารเท่านั้น

การตอบกลับ จะแนบกับความคิดเห็นและแสดงถึงการตอบสนองของผู้ใช้ต่อความคิดเห็น Drive API ช่วยให้ผู้ใช้เพิ่มความคิดเห็นและการตอบกลับลงในเอกสารที่แอปของคุณสร้างขึ้นได้ โดยรวมแล้ว ความคิดเห็นที่มีการตอบกลับจะเรียกว่า การสนทนา

ใช้พารามิเตอร์ `fields`

สำหรับเมธอดทั้งหมด (ยกเว้น delete) ในทรัพยากร comments คุณ ต้อง ตั้งค่า fields พารามิเตอร์ ระบบ เพื่อ ระบุช่องที่จะแสดงผลในการตอบกลับ ในเมธอดทรัพยากรไดรฟ์ส่วนใหญ่ การดำเนินการนี้จำเป็นเฉพาะเมื่อต้องการแสดงผลช่องที่ไม่ใช่ค่าเริ่มต้น แต่จำเป็นสำหรับทรัพยากร comments หากไม่ใส่พารามิเตอร์ fields เมธอดจะแสดงข้อผิดพลาด ดูข้อมูลเพิ่มเติมได้ที่ แสดงผลช่องที่เฉพาะเจาะจง

ข้อจำกัดของความคิดเห็น

ระบบจะบังคับใช้ข้อจำกัดต่อไปนี้เมื่อทำงานกับความคิดเห็นที่ยึดกับตำแหน่งและความคิดเห็นที่ไม่ยึดกับตำแหน่งด้วย Drive API

ประเภทความคิดเห็น ประเภทไฟล์
ยึดกับตำแหน่ง
  • นักพัฒนาแอปสามารถกำหนดรูปแบบของตนเองสำหรับการระบุตำแหน่งได้
  • ระบบจะบันทึกและแสดงผลตำแหน่งเมื่อดึงข้อมูลความคิดเห็น แต่แอปเครื่องมือแก้ไข Google Workspace จะถือว่าความคิดเห็นเหล่านี้เป็นความคิดเห็นที่ไม่ยึดกับตำแหน่ง
ไม่ยึดกับตำแหน่ง
  • รองรับในเอกสาร Google Workspace ซึ่งจะแสดงความคิดเห็นในมุมมอง "ความคิดเห็นทั้งหมด"
  • ความคิดเห็นที่ไม่ยึดกับตำแหน่งจะไม่แสดงใน PDF ที่แสดงในโปรแกรมแสดงตัวอย่างไฟล์ของไดรฟ์ แม้ว่าระบบจะบันทึกความคิดเห็นไว้และดึงข้อมูลผ่าน Drive API ได้

เพิ่มความคิดเห็นที่ยึดกับตำแหน่งลงในการแก้ไขล่าสุดของเอกสาร

เมื่อเพิ่มความคิดเห็น คุณอาจต้องการยึดความคิดเห็นไว้กับภูมิภาคในไฟล์ ตำแหน่ง จะกำหนดภูมิภาคในไฟล์ที่ความคิดเห็นอ้างถึง ทรัพยากร comments จะกำหนดช่อง anchor เป็นสตริง JSON

วิธีเพิ่มความคิดเห็นที่ยึดกับตำแหน่ง

  1. (ไม่บังคับ) เรียกใช้เมธอด list ในทรัพยากร revisions เพื่อแสดงรายการ revisionID ทั้งหมดสำหรับเอกสาร ทำตามขั้นตอนนี้เฉพาะในกรณีที่คุณต้องการยึดความคิดเห็นไว้กับการแก้ไขอื่นที่ไม่ใช่การแก้ไขล่าสุด หากต้องการใช้การแก้ไขล่าสุด ให้ใช้ head สำหรับ revisionID

  2. เรียกใช้เมธอด create ในทรัพยากร comments ด้วยพารามิเตอร์ fileID ทรัพยากร comments ที่มีความคิดเห็น และสตริงตำแหน่ง JSON ที่มี revisionID (r) และภูมิภาค (a)

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีสร้างความคิดเห็นที่ยึดกับตำแหน่ง

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 จะแสดงผลอินสแตนซ์ของออบเจ็กต์ทรัพยากร comments ซึ่งมีสตริง anchor

เพิ่มความคิดเห็นที่ไม่ยึดกับตำแหน่ง

หากต้องการเพิ่มความคิดเห็นที่ไม่ยึดกับตำแหน่ง ให้เรียกใช้เมธอด create ด้วยพารามิเตอร์ fileId และทรัพยากร comments ที่มีความคิดเห็น

ระบบจะแทรกความคิดเห็นเป็นข้อความธรรมดา แต่เนื้อหาการตอบกลับจะมีช่อง htmlContent ที่มีเนื้อหาที่จัดรูปแบบไว้สำหรับแสดง

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีสร้างความคิดเห็นที่ไม่ยึดกับตำแหน่ง

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

เพิ่มการตอบกลับในความคิดเห็น

หากต้องการเพิ่มการตอบกลับในความคิดเห็น ให้ใช้ create เมธอดใน replies ทรัพยากรที่มี fileId และ commentId พารามิเตอร์ เนื้อหาคำขอใช้ช่อง content เพื่อเพิ่มการตอบกลับ

ระบบจะแทรกการตอบกลับเป็นข้อความธรรมดา แต่เนื้อหาการตอบกลับจะมีช่อง htmlContent ที่มีเนื้อหาที่จัดรูปแบบไว้สำหรับแสดง

เมธอดจะแสดงผลช่องที่ระบุไว้ในช่อง fields

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทาง fileId และ commentId รวมถึงช่องหลายช่อง

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

เนื้อความของคำขอ

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

ยุติความคิดเห็น

คุณจะยุติความคิดเห็นได้โดยการโพสต์การตอบกลับความคิดเห็นเท่านั้น

หากต้องการยุติความคิดเห็น ให้ใช้เมธอด create ในทรัพยากร replies ที่มีพารามิเตอร์ fileId และ commentId

เนื้อหาคำขอใช้ช่อง actionเพื่อยุติ ความคิดเห็น นอกจากนี้ คุณยังตั้งค่าช่อง content เพื่อเพิ่มการตอบกลับที่จะปิดความคิดเห็นได้ด้วย

เมื่อยุติความคิดเห็น ไดรฟ์จะทำเครื่องหมายทรัพยากร comments เป็น resolved: true ความคิดเห็นที่ยุติแล้ว อาจมีช่อง htmlContent หรือ content ซึ่งแตกต่างจากความคิดเห็นที่ถูกลบ

เมื่อแอปของคุณยุติความคิดเห็น UI ของแอปควรระบุว่ามีการจัดการความคิดเห็นแล้ว ตัวอย่างเช่น แอปของคุณอาจทำสิ่งต่อไปนี้

  • ไม่อนุญาตให้มีการตอบกลับเพิ่มเติมและทำให้การตอบกลับก่อนหน้าทั้งหมดรวมถึงความคิดเห็นเดิมจางลง
  • ซ่อนความคิดเห็นที่ยุติแล้ว

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทาง fileId และ commentId รวมถึงช่องหลายช่อง

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

เนื้อความของคำขอ

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

รับความคิดเห็น

หากต้องการรับความคิดเห็นในไฟล์ ให้ใช้เมธอด get ในทรัพยากร comments ที่มีพารามิเตอร์ fileId และ commentId หากไม่ทราบรหัสความคิดเห็น คุณสามารถ แสดงรายการความคิดเห็นทั้งหมดได้โดยใช้เมธอด list

เมธอดจะแสดงผลอินสแตนซ์ของทรัพยากร comments

หากต้องการรวมความคิดเห็นที่ถูกลบไว้ในผลลัพธ์ ให้ตั้งค่าincludedDeletedพารามิเตอร์การค้นหา เป็น true

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทาง fileId และ commentId รวมถึงช่องหลายช่อง

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

แสดงรายการความคิดเห็น

หากต้องการแสดงรายการความคิดเห็นในไฟล์ ให้ใช้ list เมธอดในทรัพยากร comments ที่มี fileId พารามิเตอร์ เมธอดจะแสดงรายการความคิดเห็น

ส่งพารามิเตอร์การค้นหาต่อไปนี้เพื่อปรับแต่งการแบ่งหน้าหรือกรองความคิดเห็น

  • includeDeleted: ตั้งค่าเป็น true เพื่อรวมความคิดเห็นที่ถูกลบ ความคิดเห็นที่ถูกลบจะไม่มีช่อง htmlContent หรือ content

  • pageSize: จำนวนความคิดเห็นสูงสุดที่จะแสดงผลต่อหน้า

  • pageToken: โทเค็นหน้าเว็บที่ได้รับจากการเรียกใช้รายการก่อนหน้า ระบุโทเค็นนี้เพื่อดึงข้อมูลหน้าถัดไป

  • startModifiedTime: ค่าต่ำสุดของช่อง modifiedTime สำหรับความคิดเห็นในผลลัพธ์

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทาง fileId พารามิเตอร์การค้นหา includeDeleted และช่องหลายช่อง

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

อัปเดตความคิดเห็น

หากต้องการอัปเดตความคิดเห็นในไฟล์ ให้ใช้เมธอด update ในทรัพยากร comments ที่มีพารามิกเตอร์ fileId และ commentId เนื้อหาคำขอใช้ช่อง content เพื่ออัปเดตความคิดเห็น

ช่องบูลีน resolved ในทรัพยากร comments เป็นแบบอ่านอย่างเดียว คุณจะยุติความคิดเห็นได้โดยการโพสต์การตอบกลับความคิดเห็นเท่านั้น ดูข้อมูลเพิ่มเติมได้ที่ยุติ ความคิดเห็น

เมธอดจะแสดงผลช่องที่ระบุไว้ในพารามิเตอร์การค้นหา fields

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทาง fileId และ commentId รวมถึงช่องหลายช่อง

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

เนื้อความของคำขอ

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

ลบความคิดเห็น

หากต้องการลบความคิดเห็นในไฟล์ ให้ใช้เมธอด delete ในทรัพยากร comments ที่มีพารามิเตอร์ fileId และ commentId

เมื่อลบความคิดเห็น ไดรฟ์จะทำเครื่องหมายทรัพยากรความคิดเห็นเป็น deleted: true ความคิดเห็นที่ถูกลบจะไม่มีช่อง htmlContent หรือ content

คำขอ

ในตัวอย่างนี้ เราจะระบุพารามิเตอร์เส้นทาง fileId และ commentId

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