In Google Sheets können Nutzer zusammenarbeiten, indem sie bestimmten Zellen Kommentare hinzufügen.
In diesem Dokument wird beschrieben, wie Sie mit der Google Sheets API programmatisch Kommentare lesen, erstellen, beantworten, aktualisieren oder löschen können.
Kommentare lesen
Wenn Sie die Methode get für die Ressource spreadsheets verwenden, um eine Tabelle abzurufen, werden Kommentar-Threads und Anker standardmäßig ausgelassen.
Wenn Sie Kommentare in die Antwort einfügen möchten, setzen Sie den Abfrageparameter commentsViewMode auf COMMENTS_VIEW_MODE_INCLUDED.
Wenn der aufrufende Nutzer außerdem Zugriff auf Kommentare für die Datei hat, werden auch Kommentare zurückgegeben, wenn der Abfrageparameter auf COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS gesetzt ist.
Sowohl das Feld comments als auch das Feld sheets.commentAnchors werden in der Antwort zurückgegeben.
Das folgende Codebeispiel zeigt, wie Sie eine get-Anfrage verwenden, um Kommentarthreads und ihre Anker (Rasterbereiche) aus einer Tabelle abzurufen:
GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)
In der Antwort werden Kommentare an zwei Stellen zurückgegeben:
- Das globale
comments-Array mit denCommentThread-Objekten. - Das Array
sheets.commentAnchorsmitCommentAnchor-Objekten, in denen Kommentaranker-IDs Zellpositionen (Rasterbereichen) zugeordnet werden.
Kommentare nach Bereich oder Tabellenblatt filtern
Beim Abrufen einer Tabelle können Sie die zurückgegebenen Daten filtern, indem Sie Bereiche (mit dem Abfrageparameter ranges in der Methode spreadsheets.get) oder Tabellenblätter (mit dem Feld dataFilters im Anfragetext der Methode spreadsheets.getByDataFilter) angeben.
- Wenn Sie nach Bereich oder Tabellenblatt filtern: Es werden nur die Kommentar-Threads zurückgegeben, die in den angegebenen Bereichen oder Tabellenblättern verankert sind. Nicht verankerte Kommentare (z. B. Kommentare, deren ursprüngliche Zellkoordinate gelöscht wurde) sind nicht enthalten.
- Wenn Sie nicht nach Bereich oder Tabellenblatt filtern: Alle Kommentar-Threads, einschließlich nicht verankerten Kommentaren, werden zurückgegeben.
Beispielantwort
Die folgende JSON-Beispielantwort zeigt einen Kommentarthread, der an Zelle A1 (Zeile 0, Spalte 0) im Tabellenblatt mit der ID 0 verankert ist:
{
"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"
}
Kommentare erstellen und verwalten
Mit der Methode batchUpdate für die Ressource spreadsheets können Sie Kommentare oder Antworten programmatisch hinzufügen, bearbeiten und löschen.
Wenn Sie Batch-Updates mit Kommentaren durchführen, sollten Sie auf potenzielle Teilausfälle achten. Weitere Informationen zum Status von Kommentaraktualisierungen
Kommentar einfügen
Verwenden Sie das Objekt InsertCommentRequest, um einen Kommentarthread in eine Tabelle einzufügen. Sie müssen den Inhalt des Kommentartexts und die coordinate angeben, in der der Kommentar mit einem GridCoordinate-Objekt verankert ist.
Das folgende JSON-Beispiel zeigt, wie Sie der Zelle B2 (Zeile 1, Spalte 1) im Tabellenblatt mit der ID 0 einen nicht zugewiesenen Kommentarthread hinzufügen:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added using the API.",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Sie können einen Kommentar einem bestimmten Nutzer zuweisen, indem Sie seine E-Mail-Adresse im Feld assigneeEmailAddress angeben:
{
"requests": [
{
"insertComment": {
"content": "Please review the data in this cell.",
"assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
"coordinate": {
"sheetId": 0,
"rowIndex": 1,
"columnIndex": 1
}
}
}
]
}
Antwort hinzufügen oder Maßnahmen ergreifen
Wenn Sie auf einen Kommentarthread antworten, ihn schließen oder wieder öffnen möchten, verwenden Sie das Objekt AddCommentReplyRequest.
Sie müssen die commentId und die post angeben, wobei die Antwort durch ein Post-Objekt dargestellt wird.
Das Post-Objekt enthält die Antwort content und kann optional eine commentAction angeben (einschließlich der Aktion zum RESOLVE oder REOPEN des Kommentarbereichs). Sie wird durch ein CommentActionType-Objekt dargestellt.
Sie können einen Kommentarthread auch neu zuweisen, indem Sie eine neue assigneeEmail im Post-Objekt angeben.
Das folgende JSON-Beispiel zeigt, wie Sie auf einen vorhandenen Kommentarstrang antworten:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Das folgende JSON-Beispiel zeigt, wie ein Kommentarthread aufgelöst wird (dazu ist das Feld content nicht erforderlich):
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Das folgende JSON-Beispiel zeigt, wie Sie einen Kommentarthread neu zuweisen:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread.",
"assigneeEmail": "ASSIGNEE_EMAIL"
}
}
}
]
}
Beitrag bearbeiten
Wenn Sie den Textinhalt eines von Ihnen erstellten Beitrags bearbeiten möchten, verwenden Sie das Objekt UpdateCommentPostRequest. Sie müssen die commentId des Threads, die postId des Beitrags, den Sie bearbeiten möchten, und den neuen content-Klartext angeben.
Das folgende JSON-Beispiel zeigt, wie Sie einen Beitrag bearbeiten:
{
"requests": [
{
"updateCommentPost": {
"commentId": "COMMENT_ID",
"postId": "POST_ID",
"content": "This is the updated comment text."
}
}
]
}
Kommentare und Antworten löschen
Du hast zwei Möglichkeiten, Kommentare und Antworten zu löschen:
Kommentar-Thread löschen:Wenn Sie einen gesamten
CommentThreadentfernen möchten, verwenden Sie das ObjektDeleteCommentRequest. Sie können einen Kommentar-Thread nur löschen, wenn Sie der Autor desheadPostdes Threads imCommentThread-Objekt sind.Antwort löschen:Wenn Sie eine bestimmte Antwort
Postaus einemCommentThreadlöschen möchten, verwenden Sie das ObjektDeleteCommentReplyRequest. Sie können nur Antworten löschen, die Sie selbst verfasst haben. Sie können keine Antwortbeiträge löschen, die eincommentActionoder einassigneeEmailenthalten.
Das folgende JSON-Beispiel zeigt, wie ein Kommentarthread gelöscht wird:
{
"requests": [
{
"deleteComment": {
"commentId": "COMMENT_ID"
}
}
]
}
Status der Kommentaraktualisierung
Bei Anfragen, bei denen Kommentar-Threads gespeichert werden müssen (z. B. beim Einfügen von Kommentaren oder beim Hinzufügen von Antworten), kann es zu teilweisen Fehlern kommen. In diesen Fällen werden die Änderungen am Tabellenmodell (z. B. das Aktualisieren von Zellwerten oder das Hinzufügen von Tabellen) möglicherweise erfolgreich übernommen, die zugehörigen Kommentare werden aber nicht gespeichert.
Sie können prüfen, ob Kommentaraktualisierungen erfolgreich angewendet wurden, indem Sie das Feld commentUpdateState im Antworttext der spreadsheets.batchUpdate-Methode prüfen. Das Feld wird durch ein CommentUpdateState-Objekt dargestellt.
Die folgenden Status werden in CommentUpdateState zurückgegeben:
NO_UPDATES_REQUESTED: Im Batchvorgang wurden keine Kommentaraktualisierungen angefordert.ALL_SAVED: Alle angeforderten Kommentaraktualisierungen wurden erfolgreich angewendet.ALL_FAILED_UNKNOWN_REASON: Alle angeforderten Kommentaraktualisierungen konnten nicht gespeichert werden, obwohl andere Tabellenänderungen möglicherweise übernommen wurden.