Эта страница переведена с помощью Cloud Translation API.

Управление комментариями

Google Sheets позволяет пользователям совместно работать, добавляя комментарии к определенным ячейкам.

В этом документе показано, как использовать API Google Sheets для программного чтения, создания, ответа на комментарии, обновления или удаления комментариев.

Читать комментарии

При использовании метода 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 : Все запрошенные обновления комментариев не удалось сохранить, даже несмотря на то, что другие изменения в электронной таблице могли быть зафиксированы.