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

Google ชีตช่วยให้ผู้ใช้ทำงานร่วมกันได้โดยการเพิ่มความคิดเห็นในเซลล์ที่เฉพาะเจาะจง

เอกสารนี้แสดงวิธีใช้ Google Sheets API เพื่ออ่าน สร้าง ตอบกลับ อัปเดต หรือลบความคิดเห็นโดยใช้โปรแกรม

อ่านความคิดเห็น

เมื่อใช้วิธี get ในแหล่งข้อมูล spreadsheets เพื่อดึงข้อมูลสเปรดชีต ระบบจะละเว้นชุดความคิดเห็นและจุดยึดโดยค่าเริ่มต้น

หากต้องการรวมความคิดเห็นไว้ในคำตอบ ให้ตั้งค่าพารามิเตอร์การค้นหา commentsViewMode เป็น COMMENTS_VIEW_MODE_INCLUDED นอกจากนี้ หากผู้ใช้ที่เรียกใช้มีสิทธิ์เข้าถึงความคิดเห็นในไฟล์ การตั้งค่าพารามิเตอร์การค้นหาเป็น COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS จะแสดงความคิดเห็นด้วย

ทั้งฟิลด์ comments และ sheets.commentAnchors จะแสดงในคำตอบ

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้คำขอ get ที่ดึงข้อมูล เธรดความคิดเห็นและจุดยึด (ช่วงตารางกริด) จากสเปรดชีต

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)

ในการตอบกลับ ระบบจะแสดงความคิดเห็นใน 2 ตำแหน่งต่อไปนี้

• อาร์เรย์ comments ทั่วโลกที่มีออบเจ็กต์ CommentThread
• อาร์เรย์ sheets.commentAnchors ที่มีออบเจ็กต์ CommentAnchor ซึ่งแมปรหัสจุดยึดของความคิดเห็นกับตำแหน่งเซลล์ (ช่วงตารางกริด)

กรองความคิดเห็นตามช่วงหรือชีต

เมื่อดึงข้อมูลสเปรดชีต คุณจะกรองข้อมูลที่แสดงผลได้โดยการระบุ ช่วง (ใช้พารามิเตอร์การค้นหา ranges ในเมธอด spreadsheets.get) หรือชีต (ใช้ฟิลด์ dataFilters ในเนื้อหาคำขอของเมธอด spreadsheets.getByDataFilter)

• หากกรองตามช่วงหรือชีต: ระบบจะแสดงเฉพาะชุดความคิดเห็นที่ยึด ไว้ภายในช่วงหรือชีตที่ระบุ ระบบจะไม่รวมความคิดเห็นที่ไม่ได้ยึด (เช่น ความคิดเห็นที่มีการลบพิกัดเซลล์ต้นฉบับ)
• หากไม่กรองตามช่วงหรือชีต ระบบจะแสดงชุดความคิดเห็นทั้งหมด รวมถึงความคิดเห็นที่ไม่ได้ยึด

ตัวอย่างการตอบกลับ

ตัวอย่างการตอบกลับ JSON ต่อไปนี้แสดงชุดความคิดเห็นที่ยึดกับเซลล์ A1 (แถว 0 คอลัมน์ 0) ในชีตที่มีรหัส 0

{
  "spreadsheetId": "SPREADSHEET_ID",
  "sheets": [
    {
      "properties": {
        "sheetId": 0,
        "title": "Sheet1"
      },
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "range": {
            "sheetId": 0,
            "startRowIndex": 0,
            "endRowIndex": 1,
            "startColumnIndex": 0,
            "endColumnIndex": 1
          }
        }
      ]
    }
  ],
  "comments": [
    {
      "commentId": "COMMENT_ID",
      "anchorId": "ANCHOR_ID",
      "headPost": {
        "postId": "POST_ID",
        "content": "This is a comment thread head post.",
        "contentHtml": "The content of the post as HTML.",
        "author": {
          "displayName": "DISPLAY_NAME",
          "me": true,
          "user": "users/USER"
        },
        "createTime": "2026-07-01T10:13:12Z",
        "updateTime": "2026-07-01T10:13:12Z"
      },
      "replies": [
        {
          "postId": "REPLY_POST_ID",
          "content": "This is a reply to the comment.",
          "author": {
            "displayName": "DISPLAY_NAME",
            "me": false
          },
          "createTime": "2026-07-01T10:15:00Z",
          "updateTime": "2026-07-01T10:15:00Z"
        }
      ],
      "status": "OPEN"
    }
  ],
  "commentsViewMode": "COMMENTS_VIEW_MODE_INCLUDED"
}

สร้างและจัดการความคิดเห็น

คุณสามารถเพิ่ม แก้ไข และลบความคิดเห็นหรือการตอบกลับโดยใช้โปรแกรมได้โดยใช้เมธอด batchUpdate ในแหล่งข้อมูล spreadsheets

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

แทรกความคิดเห็น

หากต้องการแทรกชุดข้อความความคิดเห็นลงในสเปรดชีต ให้ใช้ InsertCommentRequest ออบเจ็กต์ คุณต้องระบุเนื้อหาข้อความความคิดเห็นและ coordinate ที่ความคิดเห็นยึดไว้โดยใช้ออบเจ็กต์ GridCoordinate

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีเพิ่มชุดข้อความความคิดเห็นที่ไม่ได้กำหนดให้กับเซลล์ B2 (แถว 1 คอลัมน์ 1) ในชีตที่มีรหัส 0

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

คุณมอบหมายความคิดเห็นให้ผู้ใช้ที่เฉพาะเจาะจงได้โดยระบุอีเมลของผู้ใช้ในช่อง assigneeEmailAddress

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review the data in this cell.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

ตอบกลับหรือดำเนินการ

หากต้องการตอบกลับชุดข้อความความคิดเห็น แก้ไข หรือเปิดชุดข้อความอีกครั้ง ให้ใช้ AddCommentReplyRequest ออบเจ็กต์

คุณต้องระบุ commentId และ post ซึ่งการตอบกลับจะแสดงด้วยออบเจ็กต์ Post

ออบเจ็กต์ Post มีการตอบกลับ content และอาจระบุ commentAction (รวมถึงการดำเนินการเพื่อRESOLVEหรือREOPENชุดข้อความความคิดเห็น) ได้ โดยแสดงด้วยออบเจ็กต์ CommentActionType

นอกจากนี้ คุณยังกำหนดชุดความคิดเห็นใหม่ได้โดยระบุ assigneeEmail ใหม่ในออบเจ็กต์ Post

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีตอบกลับชุดความคิดเห็นที่มีอยู่

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีแก้ไขชุดข้อความความคิดเห็น (ซึ่งไม่จำเป็นต้องมีฟิลด์ content)

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีมอบหมายชุดความคิดเห็นอีกครั้ง

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "ASSIGNEE_EMAIL"
        }
      }
    }
  ]
}

แก้ไขโพสต์

หากต้องการแก้ไขเนื้อหาข้อความของโพสต์ที่คุณสร้าง ให้ใช้ออบเจ็กต์ UpdateCommentPostRequest คุณต้องระบุcommentIdของเธรด postIdของโพสต์ ที่ต้องการแก้ไข และcontentข้อความธรรมดาใหม่

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีแก้ไขโพสต์

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "COMMENT_ID",
        "postId": "POST_ID",
        "content": "This is the updated comment text."
      }
    }
  ]
}

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

หากต้องการลบความคิดเห็นและการตอบกลับ คุณมี 2 ตัวเลือกดังนี้

• ลบชุดความคิดเห็น: หากต้องการนำCommentThreadทั้งหมดออก ให้ใช้ ออบเจ็กต์ DeleteCommentRequest คุณจะลบชุดความคิดเห็นได้ก็ต่อเมื่อคุณเป็นผู้เขียนheadPost ของชุดความคิดเห็นนั้นในออบเจ็กต์ CommentThread

• ลบการตอบ: หากต้องการลบการตอบที่เฉพาะเจาะจง Post จาก CommentThread ให้ใช้ ออบเจ็กต์ DeleteCommentReplyRequest คุณจะลบได้เฉพาะคำตอบที่คุณเขียนเท่านั้น คุณไม่สามารถลบโพสต์ตอบกลับที่มี commentAction หรือ assigneeEmail ได้

ตัวอย่าง JSON ต่อไปนี้แสดงวิธีลบเธรดความคิดเห็น

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

สถานะการอัปเดตความคิดเห็น

คำขอที่ต้องบันทึกชุดความคิดเห็น (เช่น การแทรกความคิดเห็นหรือ การเพิ่มคำตอบ) อาจทำงานไม่สำเร็จบางส่วน ในกรณีเหล่านี้ การเปลี่ยนแปลงโมเดลสเปรดชีต (เช่น การอัปเดตค่าเซลล์หรือการเพิ่มชีต) อาจ ได้รับการยืนยันสำเร็จ แต่ความคิดเห็นที่เชื่อมโยงอาจบันทึกไม่สำเร็จ

คุณตรวจสอบได้ว่าการอัปเดตความคิดเห็นมีผลสำเร็จหรือไม่โดยดูฟิลด์ commentUpdateState ในเนื้อหาการตอบกลับของเมธอด spreadsheets.batchUpdate ฟิลด์นี้แสดงด้วยออบเจ็กต์ CommentUpdateState

ระบบจะแสดงสถานะต่อไปนี้ใน CommentUpdateState

• NO_UPDATES_REQUESTED: ไม่มีการขออัปเดตความคิดเห็นในการดำเนินการแบบกลุ่ม
• ALL_SAVED: เราได้อัปเดตความคิดเห็นตามที่คุณขอเรียบร้อยแล้ว
• ALL_FAILED_UNKNOWN_REASON: การอัปเดตความคิดเห็นที่ขอทั้งหมดบันทึกไม่สำเร็จ แม้ว่าการเปลี่ยนแปลงอื่นๆ ในสเปรดชีตอาจได้รับการบันทึกแล้วก็ตาม