In Google Sheets können Nutzer zusammenarbeiten, indem sie Kommentare zu bestimmten Zellen hinzufügen.
In diesem Dokument wird beschrieben, wie Sie mit der Google Sheets API Kommentare programmatisch 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 Kommentarthreads und Anker standardmäßig ausgelassen.
Wenn Sie Kommentare in die Antwort einbeziehen 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 durch Festlegen des Abfrageparameters auf COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS auch Kommentare zurückgegeben.
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, mit der Kommentar-Threads und ihre Anker (Rasterbereiche) aus einer Tabelle abgerufen werden:
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
sheets.commentAnchors-Array mitCommentAnchor-Objekten, in denen Kommentaranker-IDs Zellpositionen (Rasterbereichen) zugeordnet werden.
Kommentare nach Bereich oder Tabellenblatt filtern
Wenn Sie eine Tabelle abrufen, 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 verankerter Kommentare, 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 mögliche Teilausfälle achten. Weitere Informationen finden Sie unter Status von Kommentaraktualisierungen.
Kommentar einfügen
Wenn Sie einen Kommentarthread in eine Tabelle einfügen möchten, verwenden Sie das Objekt InsertCommentRequest. 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) des Tabellenblatts mit der ID 0 einen nicht zugewiesenen Kommentar-Thread 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 Kommentar-Thread 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 Objekt Post 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 Kommentar-Thread auch neu zuweisen, indem Sie ein neues assigneeEmail im Post-Objekt angeben.
Das folgende JSON-Beispiel zeigt, wie Sie auf einen vorhandenen Kommentarthread antworten:
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Das folgende JSON-Beispiel zeigt, wie ein Kommentarthread geschlossen wird (dazu ist das Feld content nicht erforderlich):
{
"requests": [
{
"addCommentReply": {
"commentId": "COMMENT_ID",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Das folgende JSON-Beispiel zeigt, wie ein Kommentarthread neu zugewiesen wird:
{
"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 Nur-Text content 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 ganzen
CommentThreadentfernen möchten, verwenden Sie dasDeleteCommentRequest-Objekt. 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, für die Kommentar-Threads gespeichert werden müssen (z. B. beim Einfügen von Kommentaren oder 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 Methode spreadsheets.batchUpdate 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.