O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar comentários

Com as Planilhas Google, os usuários podem colaborar 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 forma programática.

Ler comentários

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

Para incluir comentários na resposta, defina o parâmetro de consulta commentsViewMode como COMMENTS_VIEW_MODE_INCLUDED. Além disso, se o usuário que fez a chamada tiver acesso para comentar no arquivo, definir o parâmetro de consulta como COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS também vai 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 encadeamentos de comentários e â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 objetos CommentThread.
A matriz sheets.commentAnchors que contém objetos CommentAnchor que mapeiam IDs de âncora 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 parâmetro de consulta ranges no método spreadsheets.get) ou páginas (usando o campo dataFilters 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. Comentários não fixados (como aqueles 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 comentários não fixados, 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) da planilha com ID 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 forma programática usando o método batchUpdate no recurso spreadsheets.

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 em uma planilha, use o objeto InsertCommentRequest. Você precisa fornecer o conteúdo do texto do comentário e o coordinate em que ele está ancorado usando um objeto GridCoordinate.

O exemplo de 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 o ID 0:

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

Você pode atribuir um comentário a um usuário específico fornecendo o e-mail dele no campo assigneeEmailAddress:

{
  "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, use o objeto AddCommentReplyRequest.

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

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

Você também pode reatribuir uma conversa de comentários especificando um novo assigneeEmail no objeto Post.

O exemplo de 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 de JSON a seguir mostra como resolver uma conversa em um comentário (que não exige o campo content):

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

O exemplo de 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 objeto UpdateCommentPostRequest. É necessário especificar o commentId da conversa, o postId da postagem que você quer editar e o novo content de texto simples.

O exemplo de 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 sequência de comentários:para remover uma CommentThread inteira, use o objeto DeleteCommentRequest. Você só pode excluir uma sequência de comentários se for o autor do headPost da sequência no objeto CommentThread.
Excluir uma resposta:para excluir uma resposta específica Post de um CommentThread, use o objeto DeleteCommentReplyRequest. Só é possível excluir as respostas que você escreveu. Não é possível excluir postagens de resposta que contenham um commentAction ou um assigneeEmail.

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

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

Status da atualização do comentário

As solicitações que exigem o salvamento de conversas (como inserir comentários ou adicionar respostas) podem apresentar falhas parciais. Nesses casos, as mudanças no modelo da planilha (como atualização de valores de células ou adição de páginas) podem ser confirmadas, mas os comentários associados podem não ser salvos.

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

Os seguintes estados 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: não foi possível salvar todas as atualizações de comentários solicitadas, mesmo que outras mudanças na planilha tenham sido confirmadas.

Gerenciar comentários Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.