ניהול תגובות

תצוגה מקדימה למפתחים: זמינה כחלק מתוכנית התצוגה המקדימה למפתחים של Google Workspace, שמעניקה גישה מוקדמת לתכונות מסוימות.

ב-Google Sheets, משתמשים יכולים לשתף פעולה על ידי הוספת תגובות לתאים ספציפיים.

במאמר הזה מוסבר איך אפשר להשתמש ב-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)

בתשובה, התגובות מוחזרות בשני מיקומים:

• המערך הגלובלי 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."
      }
    }
  ]
}

מחיקת תגובות ותשובות

כדי למחוק תגובות ותשובות, יש שתי אפשרויות:

• מחיקת שרשור תגובות: כדי להסיר 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: כל העדכונים של התגובות שביקשת לשמור נכשלו, גם אם שינויים אחרים בגיליון האלקטרוני נשמרו.