Cómo administrar comentarios

Google Sheets permite que los usuarios colaboren agregando comentarios en celdas específicas.

En este documento, se muestra cómo puedes usar la API de Google Sheets para leer, crear, responder, actualizar o borrar comentarios de forma programática.

Cómo leer comentarios

Cuando usas el get método en el spreadsheets recurso para recuperar una hoja de cálculo, los hilos de comentarios y los anclajes se omiten de forma predeterminada.

Para incluir comentarios en la respuesta, establece el commentsViewMode parámetro de consulta en COMMENTS_VIEW_MODE_INCLUDED. Además, si el usuario que llama tiene acceso a los comentarios en el archivo, establecer el parámetro de consulta en COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS también muestra los comentarios.

Los campos comments y sheets.commentAnchors se muestran en la respuesta.

En la siguiente muestra de código, se muestra cómo usar una solicitud get que recupera los hilos de comentarios y sus anclajes (rangos de cuadrícula) de una hoja de cálculo:

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

En la respuesta, los comentarios se muestran en dos ubicaciones:

  • El array comments global que contiene los CommentThread objetos.
  • El array sheets.commentAnchors que contiene CommentAnchor objetos que asignan IDs de anclaje de comentarios a ubicaciones de celdas (rangos de cuadrícula).

Cómo filtrar comentarios por rango o hoja

Cuando recuperas una hoja de cálculo, puedes filtrar los datos que se muestran especificando rangos (con el ranges parámetro de consulta en el método spreadsheets.get) o hojas (con el dataFilters campo en el cuerpo de la solicitud del método spreadsheets.getByDataFilter).

  • Si filtras por rango o hoja: Solo se muestran los hilos de comentarios anclados dentro de los rangos o las hojas especificados. No se incluyen los comentarios no anclados (como los comentarios cuya coordenada de celda original se borró).
  • Si no filtras por rango o hoja: Se muestran todos los hilos de comentarios, incluidos los comentarios no anclados.

Respuesta de muestra

En la siguiente respuesta de muestra en formato JSON, se muestra un hilo de comentarios anclado a la celda A1 (fila 0, columna 0) en la hoja con un 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"
}

Cómo crear y administrar comentarios

Puedes agregar, editar y borrar comentarios o respuestas de forma programática con el batchUpdate método en el spreadsheets recurso.

Cuando realices actualizaciones por lotes que involucren comentarios, debes supervisar posibles fallas parciales. Para obtener más información, consulta Estado de actualización de comentarios.

Cómo insertar un comentario

Para insertar un hilo de comentarios en una hoja de cálculo, usa el InsertCommentRequest objeto. Debes proporcionar el contenido del texto del comentario y la coordinate en la que se ancla el comentario con un objeto GridCoordinate.

En el siguiente ejemplo en formato JSON, se muestra cómo agregar un hilo de comentarios no asignado a la celda B2 (fila 1, columna 1) en la hoja con un ID de 0:

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

Puedes asignar un comentario a un usuario específico si proporcionas su correo electrónico en el assigneeEmailAddress campo:

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

Cómo agregar una respuesta o realizar una acción

Para responder a un hilo de comentarios, resolverlo o volver a abrirlo, usa el AddCommentReplyRequest objeto.

Debes proporcionar el commentId y el post donde la respuesta está representada por un objeto Post.

El objeto Post contiene el content de la respuesta y, de manera opcional, puede especificar un commentAction (incluida la acción para RESOLVE o REOPEN el hilo de comentarios). Se representa con un CommentActionType objeto.

También puedes reasignar un hilo de comentarios si especificas un assigneeEmail nuevo en el objeto Post.

En el siguiente ejemplo en formato JSON, se muestra cómo responder a un hilo de comentarios existente:

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

En el siguiente ejemplo en formato JSON, se muestra cómo resolver un hilo de comentarios (que no requiere el campo content):

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

En el siguiente ejemplo en formato JSON, se muestra cómo reasignar un hilo de comentarios:

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

Cómo editar una entrada

Para editar el contenido de texto de una entrada que creaste, usa el UpdateCommentPostRequest objeto. Debes especificar el commentId del hilo, el postId de la entrada que quieres editar y el nuevo content de texto sin formato.

En el siguiente ejemplo en formato JSON, se muestra cómo editar una entrada:

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

Cómo borrar comentarios y respuestas

Para borrar comentarios y respuestas, tienes dos opciones:

  • Borrar un hilo de comentarios: Para quitar un CommentThread, usa el objeto DeleteCommentRequest. Solo puedes borrar un hilo de comentarios si eres el autor de la thread's headPost en el objeto CommentThread.

  • Borrar una respuesta: Para borrar una respuesta específica Post de un CommentThread, usa el DeleteCommentReplyRequest objeto. Solo puedes borrar las respuestas que creaste. No puedes borrar las entradas de respuesta que contengan un commentAction o un assigneeEmail.

En el siguiente ejemplo en formato JSON, se muestra cómo borrar un hilo de comentarios:

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

Estado de actualización de comentarios

Las solicitudes que requieren guardar hilos de comentarios (como insertar comentarios o agregar respuestas) pueden experimentar fallas parciales. En estos casos, los cambios en el modelo de hoja de cálculo (como actualizar valores de celdas o agregar hojas) pueden confirmarse correctamente, pero es posible que no se guarden los comentarios asociados.

Para verificar si las actualizaciones de comentarios se aplicaron correctamente, consulta el commentUpdateState campo en el cuerpo de la respuesta del método spreadsheets.batchUpdate. El campo está representado por un CommentUpdateState objeto.

Los siguientes estados se muestran en CommentUpdateState:

  • NO_UPDATES_REQUESTED: No se solicitaron actualizaciones de comentarios en la operación por lotes.
  • ALL_SAVED: Todas las actualizaciones de comentarios solicitadas se aplicaron correctamente.
  • ALL_FAILED_UNKNOWN_REASON: No se guardaron todas las actualizaciones de comentarios solicitadas, aunque es posible que se hayan confirmado otros cambios en la hoja de cálculo.