مدیریت نظرات

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

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

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

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

وقتی از متد get روی منبع presentations برای بازیابی یک ارائه استفاده می‌کنید، رشته‌های نظر و لنگرها به طور پیش‌فرض حذف می‌شوند.

برای گنجاندن نظرات در پاسخ، پارامتر کوئری commentsViewMode را روی COMMENTS_VIEW_MODE_INCLUDED تنظیم کنید. علاوه بر این، اگر کاربر فراخوانی‌کننده به نظرات روی فایل دسترسی داشته باشد، تنظیم پارامتر کوئری روی COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS نیز نظرات را برمی‌گرداند.

هر دو فیلد comments و commentAnchors در پاسخ برگردانده می‌شوند.

نمونه کد زیر نحوه استفاده از یک درخواست get را نشان می‌دهد که رشته‌های نظر و لنگرهای آنها را از یک ارائه بازیابی می‌کند:

GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=presentationId,comments,slides(objectId,commentAnchors)

در پاسخ، نظرات در دو مکان برگردانده می‌شوند:

• آرایه سراسری comments که شامل اشیاء CommentThread است.
• آرایه commentAnchors حاوی اشیاء CommentAnchor که شناسه‌های لنگر نظر را به مکان‌های صفحه یا عنصر صفحه (لنگرهای شیء) نگاشت می‌کنند.

خواندن نظرات در یک صفحه خاص

همچنین می‌توانید با استفاده از متد pages.get در منبع presentations.pages ، نظرات و لنگرها را برای یک صفحه خاص بازیابی کنید. پارامتر پرس و جوی commentsViewMode را طوری تنظیم کنید که شامل نظرات برای صفحه هدف خاص باشد:

GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID/pages/PAGE_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=objectId,comments,commentAnchors

پاسخ نمونه

نمونه پاسخ JSON زیر، یک رشته نظر را نشان می‌دهد که به یک محدوده متنی درون یک شکل در صفحه اسلاید متصل شده است:

{
  "presentationId": "PRESENTATION_ID",
  "slides": [
    {
      "objectId": "SLIDE_PAGE_ID",
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "objectAnchors": [
            {
              "objectId": "SHAPE_OBJECT_ID",
              "shapeTextAnchors": {
                "ranges": [
                  {
                    "startIndex": 0,
                    "endIndex": 12
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "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 در منبع presentations ، به صورت برنامه‌نویسی شده نظرات یا پاسخ‌ها را اضافه، ویرایش و حذف کنید.

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

درج نظر

برای درج یک رشته نظر در یک ارائه، از شیء InsertCommentRequest استفاده کنید. شما باید محتوای متن نظر و محل قرارگیری آن را مشخص کنید. محل قرارگیری آن باید یکی از موارد زیر را مشخص کند:

• objectId : شناسه شیء یک صفحه اسلاید یا یک عنصر صفحه (مانند شکل یا جدول) که نظر به آن متصل می‌شود.
• shapeTextAnchor : یک کامنت را به طیفی از متن در یک شکل متصل می‌کند.
• tableCellTextAnchor : یک نظر را به طیف وسیعی از متن در یک سلول جدول متصل می‌کند.
• tableAnchor : یک نظر را به طیف وسیعی از سلول‌های یک جدول متصل می‌کند.

نمونه JSON زیر نحوه اضافه کردن یک رشته نظر متصل به صفحه اسلاید را نشان می‌دهد:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "objectId": "SLIDE_PAGE_ID"
      }
    }
  ]
}

شما می‌توانید با وارد کردن ایمیل یک کاربر خاص در فیلد assigneeEmailAddress یک نظر را به او اختصاص دهید:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this slide.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "objectId": "SLIDE_PAGE_ID"
      }
    }
  ]
}

پاسخی اضافه کنید یا اقدامی انجام دهید

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

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

ویرایش یک پست

برای ویرایش محتوای متنی پستی که نوشته‌اید، از شیء 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 در بدنه پاسخ متد presentations.batchUpdate ، تأیید کنید که آیا به‌روزرسانی‌های کامنت با موفقیت اعمال شده‌اند یا خیر. این فیلد توسط یک شیء CommentUpdateState نمایش داده می‌شود.

حالت‌های زیر در CommentUpdateState برگردانده می‌شوند:

• NO_UPDATES_REQUESTED : هیچ به‌روزرسانی نظری در عملیات دسته‌ای درخواست نشد.
• ALL_SAVED : تمام به‌روزرسانی‌های درخواستی نظرات با موفقیت اعمال شدند.
• ALL_FAILED_UNKNOWN_REASON : تمام به‌روزرسانی‌های درخواستی نظرات ذخیره نشدند، حتی اگر تغییرات دیگری در ارائه اعمال شده باشد.