Gestire i commenti

Presentazioni Google consente agli utenti di collaborare aggiungendo commenti alle slide e agli elementi della pagina.

Questo documento mostra come utilizzare l'API Google Slides per leggere, creare, rispondere, aggiornare o eliminare i commenti in modo programmatico.

Leggo i commenti

Quando utilizzi il metodo get sulla risorsa presentations per recuperare una presentazione, 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 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 oggetti CommentThread.
  • L'array commentAnchors contenente oggetti CommentAnchor che mappano gli ID ancoraggio dei commenti alle posizioni della pagina o degli elementi della pagina (ancoraggi degli oggetti).

Leggere i commenti su una pagina specifica

Puoi anche recuperare commenti e ancore per una pagina specifica utilizzando il metodo pages.get sulla risorsa presentations.pages. Imposta il parametro di query commentsViewMode in modo da includere i commenti per il target di pagina specifico:

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 slide:

{
  "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 metodo batchUpdate nella risorsa presentations.

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 una presentazione, utilizza l'oggetto InsertCommentRequest. Devi fornire i contenuti del testo del commento e la posizione dell'ancoraggio. La posizione dell'ancora deve specificare una delle seguenti opzioni:

  • objectId: L'ID oggetto di una pagina della slide o di un elemento della 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 di una 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 presentazione:

{
  "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 campo assigneeEmailAddress:

{
  "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'oggetto AddCommentReplyRequest.

Devi fornire commentId e post in cui 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:

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

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 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 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 dell'aggiornamento del 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 di presentazione (come l'aggiornamento dei contenuti o degli sfondi delle slide) 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 presentations.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 alla presentazione potrebbero essere state eseguite.