مدیریت نظرات

پیش‌نمایش توسعه‌دهندگان: به عنوان بخشی از برنامه پیش‌نمایش توسعه‌دهندگان Google Workspace موجود است که دسترسی زودهنگام به برخی ویژگی‌ها را فراهم می‌کند.

گوگل شیت به کاربران اجازه می‌دهد با اضافه کردن نظرات در مورد سلول‌های خاص، با یکدیگر همکاری کنند.

این سند نشان می‌دهد که چگونه می‌توانید از API گوگل شیت برای خواندن، ایجاد، پاسخ دادن، به‌روزرسانی یا حذف نظرات به صورت برنامه‌نویسی شده استفاده کنید.

نظرات را بخوانید

وقتی از متد get روی منبع spreadsheets برای بازیابی یک صفحه گسترده استفاده می‌کنید، رشته‌های کامنت و anchorها به طور پیش‌فرض حذف می‌شوند.

برای گنجاندن نظرات در پاسخ، پارامتر کوئری 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 است که شناسه‌های لنگر نظر را به مکان‌های سلول (محدوده‌های شبکه) نگاشت می‌کنند.

فیلتر کردن نظرات بر اساس محدوده یا برگه

هنگام بازیابی یک صفحه گسترده، می‌توانید داده‌های برگشتی را با مشخص کردن محدوده‌ها (با استفاده از پارامتر query 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 : تمام به‌روزرسانی‌های درخواستی نظرات ذخیره نشدند، حتی اگر تغییرات دیگری در صفحه‌گسترده اعمال شده باشد.