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, modifier, supprimer des commentaires ou y répondre de manière programmatique.
Lecture de commentaires
Lorsque vous utilisez la
get méthode sur la
spreadsheets ressource
pour récupérer une feuille de calcul, les fils de commentaires et les ancres sont omis par défaut.
Pour inclure des commentaires dans la réponse, définissez le
commentsViewMode
paramètre de requête sur
COMMENTS_VIEW_MODE_INCLUDED.
De plus, si l'utilisateur appelant dispose d'un 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 des 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 commentaires 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 emplacements :
- Le tableau
commentsglobal contenant lesCommentThreadobjets. - Le tableau
sheets.commentAnchorscontenant des objetsCommentAnchorqui associent des ID d'ancres de commentaires à des emplacements de 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
ranges
paramètre de requête dans la méthode spreadsheets.get) ou des feuilles (à l'aide du
dataFilters
champ 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 commentaires 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 ou par feuille : tous les fils de commentaires, 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 commentaires ancré dans 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
batchUpdate
méthode sur la
spreadsheets ressource.
Lorsque vous effectuez des mises à jour par lot impliquant des commentaires, vous devez surveiller les éventuels échecs partiels. Pour en savoir plus, consultez État de la mise à jour des commentaires.
Insérer un commentaire
Pour insérer un fil de commentaires dans une feuille de calcul, utilisez l'
InsertCommentRequest
objet. Vous devez fournir le contenu du texte du commentaire et les
coordinate
où le commentaire est ancré à l'aide d'un
GridCoordinate
objet.
L'exemple JSON suivant montre comment ajouter un fil de commentaires 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 fournissant son adresse e-mail dans le
assigneeEmailAddress
champ :
{
"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 commentaires, le résoudre ou le rouvrir, utilisez l'
AddCommentReplyRequest
objet.
Vous devez fournir le commentId et le
post
où la réponse est représentée par un
Post objet.
L'objet Post contient la réponse content et peut éventuellement spécifier une
commentAction
(y compris l'action permettant de RESOLVE ou REOPEN le fil de commentaires). Il est
représenté par un
CommentActionType
objet.
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 commentaires 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 commentaires :
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
Modifier un article
Pour modifier le contenu textuel d'un article que vous avez créé, utilisez l'
UpdateCommentPostRequest
objet. Vous devez spécifier le commentId du fil, le postId de l'article que vous souhaitez modifier et le nouveau content en texte brut.
L'exemple JSON suivant montre comment modifier un article :
{
"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, deux options s'offrent à vous :
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 du fil'sheadPostdans 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 créées. Vous ne pouvez pas supprimer les articles de réponse qui contiennent unecommentActionou unassigneeEmail.
L'exemple JSON suivant montre comment supprimer un fil de commentaires :
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
État de la mise à jour des commentaires
Les requêtes qui nécessitent l'enregistrement de fils de commentaires (par exemple, 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 (par exemple, la mise à jour des valeurs de 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 mises à jour des commentaires ont été appliquées, consultez le
commentUpdateState
champ dans le corps de la réponse de la spreadsheets.batchUpdate méthode. Le champ
est représenté par un
CommentUpdateState
objet.
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 mises à jour de commentaires demandées ont été appliquées.ALL_FAILED_UNKNOWN_REASON: toutes les mises à jour de commentaires demandées n'ont pas pu être enregistrées, même si d'autres modifications de la feuille de calcul ont pu être validées.