Utilizzare commenti e suggerimenti

Google Docs consente ai collaboratori di collaborare scrivendo commenti e apportando suggerimenti che fungono da modifiche differite in attesa di approvazione.

Puoi utilizzare l'API per visualizzare le modifiche suggerite in linea nel testo del documento. Puoi anche leggere, creare, rispondere, aggiornare o eliminare in modo programmatico i thread di commenti e suggerimenti.

Quando utilizzi il metodo documents.get per recuperare i contenuti del documento, questi potrebbero includere suggerimenti non risolti. Per controllare il modo in cui documents.get rappresenta i suggerimenti, utilizza il parametro facoltativo SuggestionsViewMode. Con questo parametro sono disponibili le seguenti condizioni di filtro:

  • Ottieni contenuti con SUGGESTIONS_INLINE, in modo che il testo in attesa di eliminazione o inserimento venga visualizzato nel documento.
  • Visualizza i contenuti in anteprima con tutti i suggerimenti accettati.
  • Visualizza i contenuti come anteprima, senza suggerimenti, con tutti i suggerimenti rifiutati.

Se non fornisci SuggestionsViewMode, l'API Google Docs utilizza un'impostazione predefinita appropriata per i privilegi dell'utente corrente.

Per controllare se i commenti vengono inclusi durante il recupero di un documento, utilizza il parametro facoltativo commentsViewMode. I commenti vengono restituiti solo se i suggerimenti vengono restituiti in linea. Quando imposti commentsViewMode, devi configurare anche suggestionsViewMode come segue:

  • Se commentsViewMode è impostato su COMMENTS_VIEW_MODE_INCLUDED, suggestionsViewMode deve essere impostato su SUGGESTIONS_INLINE.
  • Se commentsViewMode è impostato su COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS, suggestionsViewMode deve essere impostato su SUGGESTIONS_INLINE o DEFAULT_FOR_CURRENT_ACCESS.

Se imposti commentsViewMode su COMMENTS_VIEW_MODE_INCLUDED, devi impostare anche includeTabsContent su true. Se utilizzi una maschera di campo che fa riferimento al campo tabs (o a qualsiasi sottocampo), l'API considera implicitamente la richiesta come se avessi impostato includeTabsContent su true.

Suggerimenti e indici

Uno dei motivi per cui SuggestionsViewMode è importante è che gli indici nella risposta potrebbero variare a seconda che siano presenti suggerimenti, come mostrato nell'esempio seguente.

Contenuti con suggerimenti Contenuti senza suggerimenti 
{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 51,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 50,
          "textRun": {
           "content": "Suggested insertion",
           "suggestedInsertionIds": [
            "suggest.vcti8ewm4mww"
           ],
           "textStyle": {}
          }
         },
         {
          "startIndex": 50,
          "endIndex": 51,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 51,
       "endIndex": 81,
       "paragraph": {
        "elements": [
         {
          "startIndex": 51,
          "endIndex": 81,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},


{
 "tabs": [
  {
   "documentTab": {
    "body": {
     "content": [
      {
       "startIndex": 1,
       "endIndex": 31,
       "paragraph": {
        "elements": [
         {
          "startIndex": 1,
          "endIndex": 31,
          "textRun": {
           "content": "Text preceding the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 31,
       "endIndex": 32,
       "paragraph": {
        "elements": [
         {
          "startIndex": 31,
          "endIndex": 32,
          "textRun": {
           "content": "\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      },
      {
       "startIndex": 32,
       "endIndex": 62,
       "paragraph": {
        "elements": [
         {
          "startIndex": 32,
          "endIndex": 62,
          "textRun": {
           "content": "Text following the suggestion\n",
           "textStyle": {}
          }
         }
        ],
        "paragraphStyle": {
         "namedStyleType": "NORMAL_TEXT",
         "direction": "LEFT_TO_RIGHT"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

Nella risposta precedente, il paragrafo contenente la riga "Testo dopo il suggerimento" mostra la differenza quando si utilizza SuggestionsViewMode. Con il valore impostato su SUGGESTIONS_INLINE, l'startIndex di ParagraphElement inizia a 51 e endIndex si interrompe a 81. Senza suggerimenti, l'intervallo di startIndex e endIndex va da 32 a 62.

Visualizzare i contenuti senza suggerimenti

Il seguente esempio di codice parziale mostra come ottenere un documento come anteprima con tutti i suggerimenti rifiutati (se presenti) impostando il parametro SuggestionsViewMode su PREVIEW_WITHOUT_SUGGESTIONS.

Java

final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();

Python

SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS"
result = (
  service.documents()
  .get(
      documentId=DOCUMENT_ID,
      includeTabsContent=True,
      suggestionsViewMode=SUGGEST_MODE,
  )
  .execute()
)

L'omissione del parametro SuggestionsViewMode equivale a fornire DEFAULT_FOR_CURRENT_ACCESS come valore del parametro.

Suggerimenti di stile

I documenti possono anche avere suggerimenti di stile. Si tratta di modifiche suggerite alla formattazione e alla presentazione, non ai contenuti.

A differenza degli inserimenti o delle eliminazioni di testo, questi non compensano gli indici, anche se potrebbero dividere un TextRun in blocchi più piccoli, ma aggiungono solo annotazioni sulla modifica dello stile suggerita.

Una di queste annotazioni è un SuggestedTextStyle, che è composto da due parti:

  • Il textStyle, che descrive lo stile del testo dopo la modifica suggerita, ma non indica cosa è cambiato.

  • textStyleSuggestionState, che indica in che modo il suggerimento modifica i campi di textStyle.

Puoi visualizzarlo nell'estratto della scheda del documento seguente, che include una modifica dello stile suggerita:

[01] "paragraph": {
[02]    "elements": [
[03]        {
[04]            "endIndex": 106,
[05]            "startIndex": 82,
[06]            "textRun": {
[07]                "content": "Some text that does not ",
[08]                "textStyle": {}
[09]            }
[10]        },
[11]        {
[12]            "endIndex": 115,
[13]            "startIndex": 106,
[14]            "textRun": {
[15]                "content": "initially",
[16]                "suggestedTextStyleChanges": {
[17]                    "suggest.xymysbs9zldp": {
[18]                        "textStyle": {
[19]                            "backgroundColor": {},
[20]                            "baselineOffset": "NONE",
[21]                            "bold": true,
[22]                            "fontSize": {
[23]                                "magnitude": 11,
[24]                                "unit": "PT"
[25]                            },
[26]                            "foregroundColor": {
[27]                                "color": {
[28]                                    "rgbColor": {}
[29]                                }
[30]                            },
[31]                            "italic": false,
[32]                            "smallCaps": false,
[33]                            "strikethrough": false,
[34]                            "underline": false
[35]                        },
[36]                        "textStyleSuggestionState": {
[37]                            "boldSuggested": true,
[38]                            "weightedFontFamilySuggested": true
[39]                        }
[40]                    }
[41]                },
[42]                "textStyle": {
[43]                    "italic": true
[44]                }
[45]            }
[46]        },
[47]        {
[48]            "endIndex": 143,
[49]            "startIndex": 115,
[50]            "textRun": {
[51]                "content": " contain any boldface text.\n",
[52]                "textStyle": {}
[53]            }
[54]        }
[55]    ],
[56]    "paragraphStyle": {
[57]        "direction": "LEFT_TO_RIGHT",
[58]        "namedStyleType": "NORMAL_TEXT"
[59]    }
[60] }

Nell'esempio precedente, il paragrafo è composto da tre sequenze di testo, a partire dalle righe 6, 14 e 50. Esamina l'esecuzione del testo centrale:

  • Riga 16: è presente un oggetto suggestedTextStyleChanges.
  • Riga 18: textStyle specifica varie formattazioni.
  • Riga 36: textStyleSuggestionState indica che solo la parte in grassetto di questa specifica era il suggerimento.
  • Riga 42: Lo stile in corsivo di questa sequenza di testo fa parte del documento corrente (e non è interessato dal suggerimento).

Solo le funzionalità di stile impostate su true in textStyleSuggestionState fanno parte del suggerimento.

Creare e gestire i commenti

Puoi aggiungere commenti e risposte, modificare i commenti ed eliminare commenti o risposte in modo programmatico utilizzando il metodo documents.batchUpdate.

Quando esegui aggiornamenti batch che coinvolgono commenti o suggerimenti, devi monitorare eventuali errori parziali. Per saperne di più, vedi Stato aggiornamento di commenti e suggerimenti.

Inserire un commento

Per inserire un thread di commenti, utilizza l'oggetto InsertCommentRequest. Devi fornire i contenuti del testo del commento e una posizione di ancoraggio (ad esempio un intervallo) a cui è allegato il commento.

Il seguente esempio JSON aggiunge un thread di commenti non assegnato all'intervallo specificato:

{
  "requests": [
    {
      "insertComment": {
        "content": "This is a comment added via the API.",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

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

{
  "requests": [
    {
      "insertComment": {
        "content": "Please review this paragraph.",
        "assigneeEmailAddress": "user@example.com",
        "range": {
          "startIndex": 10,
          "endIndex": 25
        }
      }
    }
  ]
}

Aggiungere una risposta o intraprendere un'azione

Per rispondere a un thread di commenti o suggerimenti oppure per risolvere o riaprire un thread, utilizza AddCommentReplyRequest.

Una risposta è rappresentata da un oggetto Post. L'oggetto Post contiene la risposta content e può specificare facoltativamente un commentAction (per RESOLVE o REOPEN il thread).

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

Di seguito sono riportati alcuni esempi di risposte a un thread di commenti esistente:

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

Il seguente esempio risolve un thread di commenti, che non richiede contenuti:

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

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

{
  "requests": [
    {
      "addCommentReply": {
        "commentId": "comment_thread_id",
        "post": {
          "content": "Replying to the comment thread.",
          "assigneeEmail": "user@example.com"
        }
      }
    }
  ]
}

Modificare un post

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

Tieni presente che non puoi modificare il post principale di un thread di suggerimenti (in quanto vengono generati dalle modifiche in modalità Suggerimenti).

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

Eliminare commenti e risposte

  • Eliminare un thread di commenti:per rimuovere un intero thread di commenti, utilizza DeleteCommentRequest. Puoi eliminare un thread di commenti solo se sei l'autore del post principale del thread.
  • Eliminare una risposta:per eliminare un post di risposta specifico, utilizza DeleteCommentReplyRequest. Puoi eliminare solo le risposte che hai scritto. Non puoi eliminare i post di risposta che contengono azioni o assegnatari.

L'esempio seguente elimina un thread di commenti:

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

Scrivere suggerimenti e gestire i thread di suggerimenti

Puoi scrivere le modifiche come suggerimenti anziché come modifiche dirette e accettare, rifiutare o eliminare in modo programmatico i thread di suggerimenti.

Quando esegui aggiornamenti batch che coinvolgono suggerimenti, devi monitorare la presenza di potenziali errori parziali. Per saperne di più, vedi Stato aggiornamento di commenti e suggerimenti.

Creare suggerimenti utilizzando la modalità Suggerimento

Per applicare le modifiche come suggerimenti, imposta il campo writeMode dell'oggetto WriteControl su SUGGEST nella richiesta di aggiornamento batch. Tutti gli aggiornamenti nella richiesta vengono elaborati come suggerimenti.

{
  "requests": [
    {
      "insertText": {
        "text": "suggested insertion text",
        "location": {
          "index": 1
        }
      }
    }
  ],
  "writeControl": {
    "writeMode": "SUGGEST"
  }
}

Richieste non supportate in modalità di suggerimento

Quando utilizzi WriteMode.SUGGEST, i seguenti tipi di richieste non sono supportati e restituiranno un errore:

  • AddDocumentTab
  • CreateNamedRange
  • DeleteFooter
  • DeleteHeader
  • DeleteNamedRange
  • DeleteTab
  • UpdateDocumentTabProperties
  • UpdateTableColumnProperties

Inoltre, non puoi suggerire modifiche al formato del documento o alle impostazioni di intestazione e piè di pagina. In UpdateDocumentStyle, i suggerimenti non sono supportati per i seguenti tipi di stile:

  • documentFormat
  • useEvenPageHeaderFooter
  • useFirstPageHeaderFooter

Accettare, rifiutare o eliminare i thread di suggerimenti

Puoi gestire i thread di suggerimenti utilizzando le seguenti richieste:

  • Accetta suggerimento:utilizza AcceptSuggestionRequest per accettare il suggerimento. Per farlo, devi disporre dell'accesso in modifica al documento.
  • Rifiutare il suggerimento:utilizza RejectSuggestionRequest per rifiutare il suggerimento. Per farlo, devi disporre dell'accesso in modifica al documento o essere l'autore del suggerimento.
  • Eliminare il suggerimento:utilizza DeleteSuggestionRequest per eliminare il suggerimento. Per farlo, devi essere l'autore del suggerimento.

Il seguente esempio accetta un thread di suggerimenti:

{
  "requests": [
    {
      "acceptSuggestion": {
        "suggestionId": "suggestion_thread_id"
      }
    }
  ]
}

Stato dell'aggiornamento di commenti e suggerimenti

Le richieste che richiedono il salvataggio di thread di commenti o suggerimenti (ad esempio l'inserimento di commenti, l'aggiunta di risposte o la formulazione di suggerimenti) potrebbero subire errori parziali. In questi casi, le modifiche al modello del documento (come inserimenti o eliminazioni di testo) potrebbero essere salvate correttamente nel modello di Documenti, ma i commenti o i suggerimenti associati potrebbero non essere salvati.

Puoi verificare se gli aggiornamenti dei commenti o dei suggerimenti sono stati applicati correttamente controllando il campo commentUpdateState in BatchUpdateDocumentResponse.

I seguenti stati vengono restituiti in CommentUpdateState:

  • NO_UPDATES_REQUESTED: nell'operazione batch non sono stati richiesti aggiornamenti di commenti o suggerimenti.
  • ALL_SAVED: tutti gli aggiornamenti di commenti o suggerimenti richiesti sono stati applicati correttamente.
  • ALL_FAILED_UNKNOWN_REASON: tutti gli aggiornamenti di commenti o suggerimenti richiesti non sono stati salvati, anche se le modifiche al modello di Documenti potrebbero essere state eseguite.