Google Sheets permet aux utilisateurs de collaborer en ajoutant des commentaires dans des cellules spécifiques.
Ce document explique comment utiliser l'API Google Sheets pour lire, créer, répondre à, modifier ou supprimer des commentaires de manière programmatique.
Lecture de commentaires
Lorsque vous utilisez la méthode get sur la ressource spreadsheets pour récupérer une feuille de calcul, les fils de discussion et les ancres sont omis par défaut.
Pour inclure des commentaires dans la réponse, définissez le paramètre de requête commentsViewMode sur COMMENTS_VIEW_MODE_INCLUDED.
De plus, si l'utilisateur appelant a accès aux commentaires sur le fichier, la définition du paramètre de requête sur COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS renvoie également les commentaires.
Les champs comments et sheets.commentAnchors sont renvoyés dans la réponse.
L'exemple de code suivant montre comment utiliser une requête get qui récupère les fils de discussion et leurs ancres (plages de grille) à partir d'une feuille de calcul :
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)
Dans la réponse, les commentaires sont renvoyés à deux endroits :
- Tableau
commentsglobal contenant les objetsCommentThread. - Tableau
sheets.commentAnchorscontenant des objetsCommentAnchorqui associent les ID d'ancrage des commentaires aux emplacements des cellules (plages de grille).
Filtrer les commentaires par plage ou par feuille
Lorsque vous récupérez une feuille de calcul, vous pouvez filtrer les données renvoyées en spécifiant des plages (à l'aide du paramètre de requête ranges dans la méthode spreadsheets.get) ou des feuilles (à l'aide du champ dataFilters dans le corps de la requête de la méthode spreadsheets.getByDataFilter).
- Si vous filtrez par plage ou par feuille : seuls les fils de discussion ancrés dans les plages ou les feuilles spécifiées sont renvoyés. Les commentaires non ancrés (par exemple, les commentaires dont les coordonnées de cellule d'origine ont été supprimées) ne sont pas inclus.
- Si vous ne filtrez pas par plage ni par feuille : tous les fils de discussion, y compris les commentaires non ancrés, sont renvoyés.
Exemple de réponse
L'exemple de réponse JSON suivant montre un fil de discussion ancré à la cellule A1 (ligne 0, colonne 0) de la feuille dont l'ID est 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"
}
Créer et gérer des commentaires
Vous pouvez ajouter, modifier et supprimer des commentaires ou des réponses de manière programmatique à l'aide de la méthode batchUpdate sur la ressource spreadsheets.
Lorsque vous effectuez des mises à jour par lot impliquant des commentaires, vous devez surveiller les éventuels échecs partiels. Pour en savoir plus, consultez Vérifier l'état d'une mise à jour de commentaire.
Insérez un commentaire.
Pour insérer un fil de discussion dans une feuille de calcul, utilisez l'objet InsertCommentRequest. Vous devez fournir le contenu du texte du commentaire et le coordinate où le commentaire est ancré à l'aide d'un objet GridCoordinate.
L'exemple JSON suivant montre comment ajouter un fil de discussion de commentaire non attribué à la cellule B2 (ligne 1, colonne 1) de la feuille dont l'ID est 0 :
{
"requests": [
{
"insertComment": {
"content": "This is a comment added using the API.",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Vous pouvez attribuer un commentaire à un utilisateur spécifique en indiquant son adresse e-mail dans le champ assigneeEmailAddress :
{
"requests": [
{
"insertComment": {
"content": "Please review the data in this cell.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Ajouter une réponse ou effectuer une action
Pour répondre à un fil de discussion, le résoudre ou le rouvrir, utilisez l'objet AddCommentReplyRequest.
Vous devez fournir le commentId et le post, où la réponse est représentée par un objet Post.
L'objet Post contient la réponse content et peut éventuellement spécifier un commentAction (y compris l'action à RESOLVE ou REOPEN le fil de commentaires). Il est représenté par un objet CommentActionType.
Vous pouvez également réattribuer un fil de commentaires en spécifiant un nouvel assigneeEmail dans l'objet Post.
L'exemple JSON suivant montre comment répondre à un fil de discussion existant :
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
L'exemple JSON suivant montre comment résoudre un fil de commentaires (qui ne nécessite pas le champ content) :
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
L'exemple JSON suivant montre comment réattribuer un fil de discussion :
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
Modifier un post
Pour modifier le contenu textuel d'un post que vous avez créé, utilisez l'objet UpdateCommentPostRequest. Vous devez spécifier le commentId du thread, le postId du post que vous souhaitez modifier et le nouveau content en texte brut.
L'exemple JSON suivant montre comment modifier un post :
{
"requests": [
{
"updateCommentPost": {
"commentId": "COMMENT_ID",
"postId": "POST_ID",
"content": "This is the updated comment text."
}
}
]
}
Supprimer des commentaires et des réponses
Pour supprimer des commentaires et des réponses, vous avez deux options :
Supprimer un fil de commentaires : pour supprimer un
CommentThreadentier, utilisez l'objetDeleteCommentRequest. Vous ne pouvez supprimer un fil de commentaires que si vous êtes l'auteur de l'headPostdu fil dans l'objetCommentThread.Supprimer une réponse : pour supprimer une réponse spécifique
Postd'unCommentThread, utilisez l'objetDeleteCommentReplyRequest. Vous ne pouvez supprimer que les réponses que vous avez écrites. Vous ne pouvez pas supprimer les posts de réponse qui contiennent uncommentActionou unassigneeEmail.
L'exemple JSON suivant montre comment supprimer un fil de commentaires :
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
État de la modification du commentaire
Les requêtes qui nécessitent l'enregistrement de fils de commentaires (comme l'insertion de commentaires ou l'ajout de réponses) peuvent entraîner des échecs partiels. Dans ce cas, les modifications apportées au modèle de feuille de calcul (comme la mise à jour des valeurs des cellules ou l'ajout de feuilles) peuvent être validées, mais les commentaires associés peuvent ne pas être enregistrés.
Pour vérifier si les modifications apportées aux commentaires ont bien été appliquées, consultez le champ commentUpdateState dans le corps de la réponse de la méthode spreadsheets.batchUpdate. Le champ est représenté par un objet CommentUpdateState.
Les états suivants sont renvoyés dans CommentUpdateState :
NO_UPDATES_REQUESTED: aucune mise à jour de commentaire n'a été demandée dans l'opération par lot.ALL_SAVED: toutes les modifications demandées pour les commentaires ont été appliquées.ALL_FAILED_UNKNOWN_REASON: toutes les modifications demandées pour les commentaires n'ont pas pu être enregistrées, même si d'autres modifications apportées à la feuille de calcul ont pu être validées.