Gestire i commenti

Fogli Google consente agli utenti di collaborare aggiungendo commenti a celle specifiche.

Questo documento mostra come utilizzare l'API Google Sheets per leggere, creare, rispondere, aggiornare o eliminare i commenti a livello di programmazione.

Leggo i commenti

Quando utilizzi il get metodo sulla spreadsheets risorsa per recuperare un foglio di lavoro, i thread di commenti e gli ancoraggi vengono omessi per impostazione predefinita.

Per includere i commenti nella risposta, imposta il commentsViewMode parametro di query su COMMENTS_VIEW_MODE_INCLUDED. Inoltre, se l'utente che chiama ha accesso ai commenti sul file, l'impostazione del parametro di query su COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS restituisce anche i commenti.

Nella risposta vengono restituiti sia i campi comments sia i campi sheets.commentAnchors.

Il seguente esempio di codice mostra come utilizzare una richiesta get che recupera i thread di commenti e i relativi ancoraggi (intervalli di griglia) da un foglio di lavoro:

GET https://sheets.googleapis.com/v4/spreadsheets/SPREADSHEET_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=spreadsheetId,comments,sheets(properties(sheetId,title),commentAnchors)

Nella risposta, i commenti vengono restituiti in due posizioni:

  • L'array globale comments contenente gli CommentThread oggetti.
  • L'array sheets.commentAnchors contenente CommentAnchor oggetti che mappano gli ID di ancoraggio dei commenti alle posizioni delle celle (intervalli di griglia).

Filtra i commenti per intervallo o foglio

Quando recuperi un foglio di lavoro, puoi filtrare i dati restituiti specificando gli intervalli (utilizzando il ranges parametro di query nel metodo spreadsheets.get) o i fogli (utilizzando il dataFilters campo nel corpo della richiesta del metodo spreadsheets.getByDataFilter).

  • Se filtri per intervallo o foglio: vengono restituiti solo i thread di commenti ancorati negli intervalli o nei fogli specificati. I commenti non ancorati (ad esempio i commenti le cui coordinate della cella originale sono state eliminate) non sono inclusi.
  • Se non filtri per intervallo o foglio: vengono restituiti tutti i thread di commenti, inclusi i commenti non ancorati.

Esempio di risposta

La seguente risposta JSON di esempio mostra un thread di commenti ancorato alla cella A1 (riga 0, colonna 0) nel foglio con ID 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"
}

Creare e gestire i commenti

Puoi aggiungere, modificare ed eliminare commenti o risposte a livello di programmazione utilizzando il batchUpdate metodo sulla spreadsheets risorsa.

Quando esegui aggiornamenti batch che coinvolgono i commenti, devi monitorare eventuali errori parziali. Per saperne di più, vedi Stato dell'aggiornamento dei commenti.

Inserisci un commento

Per inserire un thread di commenti in un foglio di lavoro, utilizza l' InsertCommentRequest oggetto. Devi fornire i contenuti del testo del commento e le coordinate in cui il commento è ancorato utilizzando un GridCoordinate oggetto.

Il seguente esempio JSON mostra come aggiungere un thread di commenti non assegnato alla cella B2 (riga 1, colonna 1) nel foglio con ID 0:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

Puoi assegnare un commento a un utente specifico fornendo il suo indirizzo email nel assigneeEmailAddress campo:

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review the data in this cell.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "coordinate": {
          "sheetId": 0,
          "rowIndex": 1,
          "columnIndex": 1
        }
      }
    }
  ]
}

Aggiungi una risposta o intraprendi un'azione

Per rispondere a un thread di commenti, risolverlo o riaprirlo, utilizza l' AddCommentReplyRequest oggetto.

Devi fornire il commentId e il post in cui la risposta è rappresentata da un Post oggetto.

L'oggetto Post contiene il content della risposta e può facoltativamente specificare un commentAction (inclusa l'azione per RESOLVE o REOPEN il thread di commenti). È rappresentato da un CommentActionType oggetto.

Puoi anche riassegnare un thread di commenti specificando un nuovo assigneeEmail nell'oggetto Post.

Il seguente esempio JSON mostra come rispondere a un thread di commenti esistente:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread."
        }
      }
    }
  ]
}

Il seguente esempio JSON mostra come risolvere un thread di commenti (che non richiede il campo content):

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "commentAction": "RESOLVE"
        }
      }
    }
  ]
}

Il seguente esempio JSON mostra come riassegnare un thread di commenti:

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "COMMENT_ID",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "ASSIGNEE_EMAIL"
        }
      }
    }
  ]
}

Modificare un post

Per modificare il contenuto del testo di un post di cui sei l'autore, utilizza l' UpdateCommentPostRequest oggetto. Devi specificare il commentId del thread, il postId del post che vuoi modificare e il nuovo content in testo normale.

Il seguente esempio JSON mostra come modificare un post:

{
  "requests": [
    {
      "updateCommentPost": {
        "commentId": "COMMENT_ID",
        "postId": "POST_ID",
        "content": "This is the updated comment text."
      }
    }
  ]
}

Eliminare commenti e risposte

Per eliminare commenti e risposte, hai due opzioni:

  • Eliminare un thread di commenti: per rimuovere un intero CommentThread, utilizza l'oggetto DeleteCommentRequest. Puoi eliminare un thread di commenti solo se sei l'autore del thread's headPost nell'oggetto CommentThread.

  • Eliminare una risposta: per eliminare un Post di risposta specifico da un CommentThread, utilizza l' DeleteCommentReplyRequest oggetto. Puoi eliminare solo le risposte di cui sei l'autore. Non puoi eliminare i post di risposta che contengono un commentAction o un assigneeEmail.

Il seguente esempio JSON mostra come eliminare un thread di commenti:

{
  "requests": [
    {
      "deleteComment": {
        "commentId": "COMMENT_ID"
      }
    }
  ]
}

Stato dell'aggiornamento dei commenti

Le richieste che richiedono il salvataggio dei thread di commenti (ad esempio l'inserimento di commenti o l'aggiunta di risposte) potrebbero riscontrare errori parziali. In questi casi, le modifiche al modello del foglio di lavoro (ad esempio l'aggiornamento dei valori delle celle o l'aggiunta di fogli) potrebbero essere eseguite correttamente, ma i commenti associati potrebbero non essere salvati.

Puoi verificare se gli aggiornamenti dei commenti sono stati applicati correttamente controllando il commentUpdateState campo nel corpo della risposta del metodo spreadsheets.batchUpdate. Il campo è rappresentato da un CommentUpdateState oggetto.

In CommentUpdateState vengono restituiti i seguenti stati:

  • NO_UPDATES_REQUESTED: nell'operazione batch non sono stati richiesti aggiornamenti dei commenti.
  • ALL_SAVED: tutti gli aggiornamenti dei commenti richiesti sono stati applicati correttamente.
  • ALL_FAILED_UNKNOWN_REASON: non è stato possibile salvare tutti gli aggiornamenti dei commenti richiesti, anche se potrebbero essere state eseguite altre modifiche al foglio di lavoro.