Gerenciar comentários

O Google Sheets permite que os usuários colaborem adicionando comentários em células específicas.

Este documento mostra como usar a API Google Sheets para ler, criar, responder, atualizar ou excluir comentários de maneira programática.

Ler comentários

Quando você usa o get método no spreadsheets recurso para recuperar uma planilha, as conversas e as âncoras de comentários são omitidas por padrão.

Para incluir comentários na resposta, defina o commentsViewMode parâmetro de consulta como COMMENTS_VIEW_MODE_INCLUDED. Além disso, se o usuário que está chamando tiver acesso de comentários no arquivo, definir o parâmetro de consulta como COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS também retornará comentários.

Os campos comments e sheets.commentAnchors são retornados na resposta.

O exemplo de código a seguir mostra como usar uma solicitação get que recupera conversas de comentários e as âncoras (intervalos de grade) de uma planilha:

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)

Na resposta, os comentários são retornados em dois locais:

  • A matriz global comments que contém os CommentThread objetos.
  • A matriz sheets.commentAnchors que contém CommentAnchor objetos que mapeiam IDs de âncoras de comentários para locais de células (intervalos de grade).

Filtrar comentários por intervalo ou planilha

Ao recuperar uma planilha, é possível filtrar os dados retornados especificando intervalos (usando o ranges parâmetro de consulta no método spreadsheets.get) ou planilhas (usando o dataFilters campo no corpo da solicitação do método spreadsheets.getByDataFilter).

  • Se você filtrar por intervalo ou planilha: somente as conversas de comentários ancoradas nos intervalos ou planilhas especificados serão retornadas. Os comentários não ancorados (como comentários cuja coordenada de célula original foi excluída) não são incluídos.
  • Se você não filtrar por intervalo ou planilha: todas as conversas de comentários, incluindo as não ancoradas, serão retornadas.

Exemplo de resposta

O exemplo de resposta JSON a seguir mostra uma conversa de comentários ancorada na célula A1 (linha 0, coluna 0) na planilha com um ID de 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"
}

Criar e gerenciar comentários

É possível adicionar, editar e excluir comentários ou respostas de maneira programática usando o batchUpdate método no spreadsheets recurso.

Ao realizar atualizações em lote envolvendo comentários, monitore possíveis falhas parciais. Para mais informações, consulte Status da atualização de comentários.

Inserir um comentário

Para inserir uma conversa de comentários em uma planilha, use o InsertCommentRequest objeto. Você precisa fornecer o conteúdo do texto do comentário e o coordinate em que o comentário está ancorado usando um GridCoordinate objeto.

O exemplo JSON a seguir mostra como adicionar uma conversa de comentários não atribuída à célula B2 (linha 1, coluna 1) na planilha com um ID de 0:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

É possível atribuir um comentário a um usuário específico fornecendo o e-mail dele no assigneeEmailAddress campo:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review the data in this cell.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

Adicionar uma resposta ou realizar uma ação

Para responder, resolver ou reabrir uma conversa de comentários, use o AddCommentReplyRequest objeto.

Você precisa fornecer o commentId e o post em que a resposta é representada por um objeto Post.

O Post objeto contém o content da resposta e pode especificar opcionalmente uma commentAction (incluindo a ação para RESOLVE ou REOPEN a conversa de comentários). Ele é representado por um CommentActionType objeto.

Também é possível reatribuir uma conversa de comentários especificando um novo assigneeEmail no objeto Post.

O exemplo JSON a seguir mostra como responder a uma conversa de comentários:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

O exemplo JSON a seguir mostra como resolver uma conversa de comentários (que não exige o campo content):

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

O exemplo JSON a seguir mostra como reatribuir uma conversa de comentários:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "ASSIGNEE_EMAIL"
        }
      }
    }
  ]
}

Editar uma postagem

Para editar o conteúdo de texto de uma postagem criada por você, use o UpdateCommentPostRequest objeto. Você precisa especificar o commentId da conversa, o postId da postagem que quer editar e o novo content de texto simples.

O exemplo JSON a seguir mostra como editar uma postagem:

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "COMMENT_ID",
        "postId": "POST_ID",
        "content": "This is the updated comment text."
      }
    }
  ]
}

Excluir comentários e respostas

Para excluir comentários e respostas, você tem duas opções:

  • Excluir uma conversa de comentários: Para remover uma CommentThread inteira, use o objeto DeleteCommentRequest. Só é possível excluir uma conversa de comentários se você for o autor da conversa headPost no objeto CommentThread.

  • Excluir uma resposta: Para excluir uma resposta específica Post de um CommentThread, use o DeleteCommentReplyRequest objeto. Só é possível excluir as respostas que você criou. Não é possível excluir postagens de resposta que contenham uma commentAction ou um assigneeEmail.

O exemplo JSON a seguir mostra como excluir uma conversa de comentários:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

Status da atualização de comentários

As solicitações que exigem a economia de conversas de comentários (como inserir comentários ou adicionar respostas) podem apresentar falhas parciais. Nesses casos, as mudanças no modelo de planilha (como atualizar valores de células ou adicionar planilhas) podem ser confirmadas, mas os comentários associados podem falhar ao salvar.

É possível verificar se as atualizações de comentários foram aplicadas consultando o commentUpdateState campo no corpo da resposta do método spreadsheets.batchUpdate. O campo é representado por um CommentUpdateState objeto.

Os estados a seguir são retornados em CommentUpdateState:

  • NO_UPDATES_REQUESTED: nenhuma atualização de comentário foi solicitada na operação em lote.
  • ALL_SAVED: todas as atualizações de comentários solicitadas foram aplicadas.
  • ALL_FAILED_UNKNOWN_REASON: todas as atualizações de comentários solicitadas não foram salvas, mesmo que outras mudanças na planilha tenham sido confirmadas.