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 in modo programmatico.

Leggo i commenti

Quando utilizzi il metodo get sulla risorsa spreadsheets 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 parametro di query commentsViewMode su COMMENTS_VIEW_MODE_INCLUDED. Inoltre, se l'utente chiamante 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 che sheets.commentAnchors.

Il seguente esempio di codice mostra come utilizzare una richiesta get che recupera i thread di commenti e i relativi ancoraggi (intervalli della 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 oggetti CommentThread.
  • L'array sheets.commentAnchors contenente oggetti CommentAnchor che mappano gli ID ancoraggio dei commenti alle posizioni delle celle (intervalli della griglia).

Filtrare i commenti per intervallo o foglio

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

  • Se filtri per intervallo o foglio: vengono restituite solo le discussioni dei commenti ancorate all'interno degli intervalli o dei 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) del foglio con un 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 metodo batchUpdate nella risorsa spreadsheets.

Quando esegui aggiornamenti batch che coinvolgono i commenti, devi monitorare potenziali errori parziali. Per maggiori informazioni, vedi Stato dell'aggiornamento dei commenti.

Inserire un commento

Per inserire un thread di commenti in un foglio di lavoro, utilizza l'oggetto InsertCommentRequest. Devi fornire i contenuti del testo del commento e il 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) del 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 campo assigneeEmailAddress:

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

Aggiungere una risposta o intraprendere un'azione

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

Devi fornire commentId e post dove la risposta è rappresentata da un oggetto Post.

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

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 di testo di un post che hai creato, utilizza l'oggetto UpdateCommentPostRequest. Devi specificare l'commentId del thread, l'postId del post che vuoi modificare e il nuovo content in formato di 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.

  • Elimina una risposta:per eliminare una risposta specifica Post da un CommentThread, utilizza l'oggetto DeleteCommentReplyRequest. Puoi eliminare solo le risposte che hai scritto. 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 aggiornamento commento

Le richieste che richiedono il salvataggio dei thread di commenti (ad esempio l'inserimento di commenti o l'aggiunta di risposte) potrebbero subire 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 salvate correttamente, ma i commenti associati potrebbero non essere salvati.

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

In CommentUpdateState vengono restituiti i seguenti stati:

  • NO_UPDATES_REQUESTED: Non sono stati richiesti aggiornamenti dei commenti nell'operazione batch.
  • 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 altre modifiche al foglio di lavoro potrebbero essere state eseguite.