Gestire i commenti

Documenti Google consente agli utenti di collaborare aggiungendo commenti alle diapositive e agli elementi della pagina.

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

Leggo i commenti

Quando utilizzi il get metodo sulla presentations risorsa per recuperare una presentazione, 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 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 il comments sia il commentAnchors.

Il seguente esempio di codice mostra come utilizzare una richiesta get che recupera i thread di commenti e i relativi ancoraggi da una presentazione:

GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=presentationId,comments,slides(objectId,commentAnchors)

Nella risposta, i commenti vengono restituiti in due posizioni:

  • L'array globale comments contenente gli CommentThread oggetti.
  • L'array commentAnchors contenente CommentAnchor oggetti che mappano gli ID degli ancoraggi dei commenti alle posizioni delle pagine o degli elementi della pagina (ancoraggi degli oggetti).

Leggo i commenti su una pagina specifica

Puoi anche recuperare i commenti e gli ancoraggi per una pagina specifica utilizzando il pages.get metodo sulla presentations.pages risorsa. Imposta il parametro di query commentsViewMode per includere i commenti per la pagina di destinazione specifica:

GET https://slides.googleapis.com/v1/presentations/PRESENTATION_ID/pages/PAGE_ID?commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED&fields=objectId,comments,commentAnchors

Esempio di risposta

La seguente risposta JSON di esempio mostra un thread di commenti ancorato a un intervallo di testo all'interno di una forma in una pagina della diapositiva:

{
  "presentationId": "PRESENTATION_ID",
  "slides": [
    {
      "objectId": "SLIDE_PAGE_ID",
      "commentAnchors": [
        {
          "anchorId": "ANCHOR_ID",
          "objectAnchors": [
            {
              "objectId": "SHAPE_OBJECT_ID",
              "shapeTextAnchors": {
                "ranges": [
                  {
                    "startIndex": 0,
                    "endIndex": 12
                  }
                ]
              }
            }
          ]
        }
      ]
    }
  ],
  "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 presentations risorsa.

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

Inserire un commento

Per inserire un thread di commenti in una presentazione, utilizza l' InsertCommentRequest oggetto. Devi fornire i contenuti del testo del commento e la posizione dell'ancoraggio. La posizione dell'ancoraggio deve specificare una delle seguenti opzioni:

  • objectId: l'ID oggetto di una pagina della diapositiva o di un elemento di pagina (ad esempio una forma o una tabella) a cui ancorare il commento.
  • shapeTextAnchor: ancora un commento a un intervallo di testo in una forma.
  • tableCellTextAnchor: ancora un commento a un intervallo di testo in una cella della tabella.
  • tableAnchor: ancora un commento a un intervallo di celle in una tabella.

Il seguente esempio JSON mostra come aggiungere un thread di commenti ancorato a una pagina della diapositiva:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added using the API.",
        "objectId": "SLIDE_PAGE_ID"
      }
    }
  ]
}

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

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this slide.",
        "assigneeEmailAddress": "ASSIGNEE_EMAIL_ADDRESS",
        "objectId": "SLIDE_PAGE_ID"
      }
    }
  ]
}

Aggiungere una risposta o intraprendere 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:

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

Modificare un post

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

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 che hai creato. 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 di presentazione (ad esempio l'aggiornamento dei contenuti o degli sfondi delle diapositive) 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 presentations.batchUpdate. Il campo è rappresentato da un CommentUpdateState oggetto.

I seguenti stati vengono restituiti in CommentUpdateState:

  • 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 alla presentazione.