ניהול תגובות

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