Utilizzare commenti e suggerimenti

Documenti Google consente ai collaboratori di collaborare scrivendo commenti e fornendo suggerimenti che fungono da modifiche posticipate in attesa di approvazione.

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

Quando utilizzi il documents.get metodo 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:

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

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

Suggerimenti e indici

Un motivo per cui SuggestionsViewMode è importante è che gli indici nella risposta potrebbero variare a seconda della presenza di suggerimenti, come mostrato di seguito.

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 sopra, il paragrafo contenente la riga "Testo dopo il suggerimento" mostra la differenza quando si utilizza SuggestionsViewMode. Con il valore impostato su SUGGESTIONS_INLINE, il startIndex di ParagraphElement inizia da 51 e il endIndex si ferma a 81. Senza suggerimenti, l'intervallo startIndex e endIndex va da 32 a 62.

Recuperare i contenuti senza suggerimenti

Il seguente esempio di codice parziale mostra come recuperare 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()
)

Omettere il 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, anziché modifiche ai contenuti.

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

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

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

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

Puoi vedere questo 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 sopra, il paragrafo è composto da tre esecuzioni 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 esecuzione 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 documents.batchUpdate metodo.

Quando esegui aggiornamenti batch che coinvolgono commenti o suggerimenti, devi monitorare eventuali errori parziali. Per ulteriori informazioni, consulta Stato dell'aggiornamento di commenti e suggerimenti.

Inserire un commento

Per inserire un thread di commenti, utilizza l'InsertCommentRequest oggetto. 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 la sua 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 Post oggetto. L'oggetto Post contiene il content della risposta e può facoltativamente specificare un commentAction (per RESOLVE o REOPEN il thread).

Il seguente esempio risponde 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"
        }
      }
    }
  ]
}

Modificare un post

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

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

{
  "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 di cui sei l'autore. Non puoi eliminare i post di risposta che contengono azioni o assegnatari.

Il seguente esempio 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 i thread di suggerimenti in modo programmatico.

Quando esegui aggiornamenti batch che coinvolgono suggerimenti, devi monitorare eventuali errori parziali. Per ulteriori informazioni, consulta Stato dell'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à suggerimento

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

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

Inoltre, non puoi suggerire modifiche al formato del documento o alle impostazioni di intestazioni/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:

  • Accettare il suggerimento: utilizza AcceptSuggestionRequest per accettare il suggerimento. Per questa operazione è necessario l'accesso in modifica al documento.
  • Rifiutare il suggerimento: utilizza RejectSuggestionRequest per rifiutare il suggerimento. Per questa operazione è necessario l'accesso in modifica al documento o essere l'autore del suggerimento.
  • Eliminare il suggerimento: utilizza DeleteSuggestionRequest per eliminare il suggerimento. Per questa operazione 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 creazione di suggerimenti) potrebbero riscontrare errori parziali. In questi casi, le modifiche al modello del documento (ad esempio inserimenti o eliminazioni di testo) potrebbero essere state eseguite correttamente nel modello di Documenti, ma i commenti o i suggerimenti associati potrebbero non essere stati salvati.

Puoi verificare se gli aggiornamenti di commenti o suggerimenti sono stati applicati correttamente controllando il commentUpdateState field in the 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: non è stato possibile salvare tutti gli aggiornamenti di commenti o suggerimenti richiesti, anche se le modifiche al modello di Documenti potrebbero essere state eseguite.