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 método get en el recurso spreadsheets para recuperar una hoja de cálculo, los subprocesos de comentarios y los anclajes se omiten de forma predeterminada.
Para incluir comentarios en la respuesta, configura el parámetro de búsqueda commentsViewMode como COMMENTS_VIEW_MODE_INCLUDED.
Además, si el usuario que llama tiene acceso a los comentarios del archivo, configurar el parámetro de consulta en COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS también devuelve comentarios.
En la respuesta, se devuelven los campos comments y sheets.commentAnchors.
En el siguiente ejemplo de código, se muestra cómo usar una solicitud get que recupera los subprocesos 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 devuelven en dos ubicaciones:
- Es el array
commentsglobal que contiene los objetosCommentThread. - Es el array de
sheets.commentAnchorsque contiene objetosCommentAnchorque 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 devueltos especificando rangos (con el parámetro de consulta ranges en el método spreadsheets.get) u hojas (con el campo dataFilters en el cuerpo de la solicitud del método spreadsheets.getByDataFilter).
- Si filtras por rango o por hoja: Solo se devuelven 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 ni hoja: Se devuelven todos los hilos de comentarios, incluidos los comentarios no anclados.
Respuesta de muestra
En la siguiente respuesta de ejemplo en formato JSON, se muestra un subproceso de comentarios anclado a la celda A1 (fila 0, columna 0) de 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 método batchUpdate del recurso spreadsheets.
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 objeto InsertCommentRequest. Debes proporcionar el contenido del texto del comentario y el objeto coordinate en el que se ancla el comentario con un objeto GridCoordinate.
En el siguiente ejemplo en formato JSON, se muestra cómo agregar un subproceso de comentarios no asignado a la celda B2 (fila 1, columna 1) de 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 campo assigneeEmailAddress:
{
"requests": [
{
"insertComment": {
"content": "Please review the data in this cell.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Agregar una respuesta o tomar medidas
Para responder a un hilo de comentarios, resolverlo o volver a abrirlo, usa el objeto AddCommentReplyRequest.
Debes proporcionar el commentId y el post en el que la respuesta se representa con un objeto Post.
El objeto Post contiene la respuesta content y, de manera opcional, puede especificar un commentAction (incluida la acción para RESOLVE o REOPEN el hilo de comentarios). Se representa con un objeto CommentActionType.
También puedes reasignar un hilo de comentarios especificando un nuevo assigneeEmail en el objeto Post.
En el siguiente ejemplo de 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 de JSON, se muestra cómo resolver un debate (que no requiere el campo content):
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
En el siguiente ejemplo de JSON, se muestra cómo reasignar un debate:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
Cómo editar una publicación
Para editar el contenido de texto de una publicación que creaste, usa el objeto UpdateCommentPostRequest. Debes especificar el commentId del subproceso, el postId de la publicación que deseas editar y el nuevo content de texto sin formato.
En el siguiente ejemplo de JSON, se muestra cómo editar una publicación:
{
"requests": [
{
"updateCommentPost": {
"commentId": "COMMENT_ID",
"postId": "POST_ID",
"content": "This is the updated comment text."
}
}
]
}
Borrar comentarios y respuestas
Para borrar comentarios y respuestas, tienes dos opciones:
Borra un hilo de comentarios: Para quitar un
CommentThreadcompleto, usa el objetoDeleteCommentRequest. Solo puedes borrar un hilo de comentarios si eres el autor delheadPostdel hilo en el objetoCommentThread.Borra una respuesta: Para borrar una respuesta específica
Postde unCommentThread, usa el objetoDeleteCommentReplyRequest. Solo puedes borrar las respuestas que escribiste. No puedes borrar publicaciones de respuesta que contengan uncommentActiono unassigneeEmail.
En el siguiente ejemplo de JSON, se muestra cómo borrar un subproceso de comentarios:
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
Estado de actualización del comentario
Es posible que las solicitudes que requieren guardar subprocesos de comentarios (como insertar comentarios o agregar respuestas) experimenten fallas parciales. En estos casos, es posible que los cambios en el modelo de la hoja de cálculo (como la actualización de los valores de las celdas o la adición de hojas) se confirmen correctamente, pero es posible que no se guarden los comentarios asociados.
Para verificar si las actualizaciones de comentarios se aplicaron correctamente, consulta el campo commentUpdateState en el cuerpo de la respuesta del método spreadsheets.batchUpdate. El campo se representa con un objeto CommentUpdateState.
En CommentUpdateState, se muestran los siguientes estados:
NO_UPDATES_REQUESTED: No se solicitaron actualizaciones de comentarios en la operación por lotes.ALL_SAVED: Se aplicaron correctamente todas las actualizaciones de comentarios solicitadas.ALL_FAILED_UNKNOWN_REASON: No se pudieron guardar todas las actualizaciones de comentarios solicitadas, aunque se hayan confirmado otros cambios en la hoja de cálculo.