Google Docs permet aux collaborateurs de travailler ensemble en ajoutant des commentaires et des suggestions qui sont des modifications différées en attente d'approbation.
Vous pouvez utiliser l'API pour afficher les modifications suggérées en ligne dans le texte du document. Dans l'aperçu pour les développeurs, vous pouvez également lire, créer, répondre à, modifier ou supprimer des fils de commentaires et de suggestions de manière programmatique.
Lorsque vous utilisez la méthode documents.get pour récupérer le contenu d'un document, celui-ci peut inclure des suggestions non résolues. Pour contrôler la façon dont documents.get représente les suggestions, utilisez le paramètre facultatif SuggestionsViewMode. Les conditions de filtre suivantes sont disponibles avec ce paramètre :
- Obtenez du contenu avec
SUGGESTIONS_INLINE. Le texte en attente de suppression ou d'insertion s'affiche dans le document. - Obtenez un aperçu du contenu avec toutes les suggestions acceptées.
- Obtenez un aperçu du contenu, sans suggestions, avec toutes les suggestions refusées.
Si vous ne fournissez pas SuggestionsViewMode, l'API Google Docs utilise un paramètre par défaut adapté aux droits d'accès de l'utilisateur actuel.
Suggestions et index
L'une des raisons pour lesquelles SuggestionsViewMode est important est que les index de la réponse peuvent varier selon qu'il y a des suggestions ou non, comme indiqué ci-dessous.
| Contenu avec suggestions | Contenu sans suggestions |
|---|---|
{
"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"
}
}
}
]
}
}
}
]
},
|
Dans la réponse ci-dessus, le paragraphe contenant la ligne "Texte suivant la suggestion" montre la différence lorsque vous utilisez SuggestionsViewMode. Si la valeur est définie sur SUGGESTIONS_INLINE, le startIndex de ParagraphElement commence à 51 et le endIndex s'arrête à 81. Sans suggestions, les valeurs startIndex et endIndex sont comprises entre 32 et 62.
Obtenir du contenu sans suggestions
L'exemple de code partiel suivant montre comment obtenir un aperçu d'un document avec toutes les suggestions refusées (le cas échéant) en définissant le paramètre SuggestionsViewMode sur 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() )
Omettre le paramètre SuggestionsViewMode équivaut à fournir DEFAULT_FOR_CURRENT_ACCESS comme valeur de paramètre.
Suggestions de style
Les documents peuvent également contenir des suggestions de style. Il s'agit de suggestions de modifications de la mise en forme et de la présentation, et non du contenu.
Contrairement aux insertions ou suppressions de texte, elles ne décalent pas les index (bien qu'elles puissent diviser un TextRun en blocs plus petits), mais ajoutent simplement des annotations sur le changement de style suggéré.
Une de ces annotations est SuggestedTextStyle, qui se compose de deux parties :
Le
textStyle, qui décrit le style du texte après la modification suggérée, mais ne précise pas ce qui a changé.textStyleSuggestionState, qui indique comment la suggestion modifie les champs detextStyle.
Vous pouvez le voir dans l'extrait suivant de l'onglet "Document", qui inclut une modification de style suggérée :
[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] }
Dans l'exemple ci-dessus, le paragraphe se compose de trois séries de texte, qui commencent aux lignes 6, 14 et 50. Examinez l'exécution du texte au milieu :
- Ligne 16 : il existe un objet
suggestedTextStyleChanges. - Ligne 18 :
textStylespécifie différentes mises en forme. - Ligne 36 :
textStyleSuggestionStateindique que seule la partie en gras de cette spécification était la suggestion. - Ligne 42 : la mise en italique de cette série de texte fait partie du document actuel (et n'est pas affectée par la suggestion).
Seules les caractéristiques de style définies sur true dans textStyleSuggestionState font partie de la suggestion.
Créer et gérer des commentaires
Vous pouvez ajouter des commentaires et des réponses, modifier des commentaires, et supprimer des commentaires ou des réponses de manière programmatique à l'aide de la méthode documents.batchUpdate.
Lorsque vous effectuez des mises à jour groupées impliquant des commentaires ou des suggestions, vous devez surveiller les éventuels échecs partiels. Pour en savoir plus, consultez État des commentaires et des suggestions.
Insérez un commentaire.
Pour insérer un fil de commentaires, utilisez l'objet InsertCommentRequest. Vous devez fournir le contenu du texte du commentaire et un emplacement d'ancrage (tel qu'une plage) auquel le commentaire est associé.
L'exemple JSON suivant ajoute un fil de discussion de commentaires non attribué à la plage spécifiée :
{
"requests": [
{
"insertComment": {
"content": "This is a comment added via the API.",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Vous pouvez attribuer un commentaire à un utilisateur spécifique en indiquant son adresse e-mail dans le champ assigneeEmailAddress :
{
"requests": [
{
"insertComment": {
"content": "Please review this paragraph.",
"assigneeEmailAddress": "user@example.com",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Ajouter une réponse ou effectuer une action
Pour répondre à un fil de commentaires ou de suggestions, ou pour résoudre ou rouvrir un fil, utilisez AddCommentReplyRequest.
Une réponse est représentée par un objet Post.
L'objet Post contient la content de la réponse et peut éventuellement spécifier un commentAction (pour RESOLVE ou REOPEN le fil de discussion).
Voici des exemples de réponses à un fil de commentaires existant :
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
L'exemple suivant résout un fil de commentaires, ce qui ne nécessite aucun contenu :
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Modifier un post
Pour modifier le contenu textuel d'un post que vous avez créé, utilisez UpdateCommentPostRequest.
Vous devez spécifier l'ID du fil de discussion (commentId ou suggestionId), le postId du post que vous souhaitez modifier et le nouveau content en texte brut.
Notez que vous ne pouvez pas modifier le premier post d'un fil de suggestions (car il est généré par les modifications en mode suggestion).
{
"requests": [
{
"updateCommentPost": {
"commentId": "comment_thread_id",
"postId": "post_id",
"content": "This is the updated comment text."
}
}
]
}
Supprimer des commentaires et des réponses
- Supprimer un fil de commentaires : pour supprimer un fil de commentaires entier, utilisez
DeleteCommentRequest. Vous ne pouvez supprimer un fil de commentaires que si vous êtes l'auteur du post principal du fil. - Supprimer une réponse : pour supprimer une réponse spécifique, utilisez
DeleteCommentReplyRequest. Vous ne pouvez supprimer que les réponses que vous avez écrites. Vous ne pouvez pas supprimer les posts de réponse qui contiennent des actions ou des responsables.
L'exemple suivant supprime un fil de commentaires :
{
"requests": [
{
"deleteComment": {
"commentId": "comment_thread_id"
}
}
]
}
Écrire des suggestions et gérer les fils de suggestions
Vous pouvez rédiger des modifications sous forme de suggestions plutôt que de modifications directes, et accepter, refuser ou supprimer des fils de suggestions de manière programmatique.
Lorsque vous effectuez des mises à jour par lot impliquant des suggestions, vous devez surveiller les éventuels échecs partiels. Pour en savoir plus, consultez État des commentaires et des suggestions.
Créer des suggestions à l'aide du mode Suggestion
Pour appliquer les modifications en tant que suggestions, définissez le champ writeMode de l'objet WriteControl sur SUGGEST dans votre requête de mise à jour par lot. Toutes les modifications apportées à la demande sont traitées comme des suggestions.
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
Requêtes non acceptées en mode suggestion
Lorsque vous utilisez WriteMode.SUGGEST, les types de requêtes suivants ne sont pas acceptés et renvoient une erreur :
AddDocumentTabCreateNamedRangeDeleteFooterDeleteHeaderDeleteNamedRangeDeleteTabUpdateDocumentTabPropertiesUpdateTableColumnProperties
De plus, vous ne pouvez pas suggérer de modifications concernant le format du document ni les paramètres d'en-tête et de pied de page. Dans UpdateDocumentStyle, les suggestions ne sont pas acceptées pour les types de styles suivants :
documentFormatuseEvenPageHeaderFooteruseFirstPageHeaderFooter
Accepter, refuser ou supprimer des fils de suggestions
Vous pouvez gérer les fils de suggestions à l'aide des requêtes suivantes :
- Accepter la suggestion : utilisez
AcceptSuggestionRequestpour accepter la suggestion. Pour cela, vous devez disposer des droits de modification sur le document. - Refuser la suggestion : utilisez
RejectSuggestionRequestpour refuser la suggestion. Pour ce faire, vous devez être autorisé à modifier le document ou être l'auteur de la suggestion. - Supprimer la suggestion : utilisez
DeleteSuggestionRequestpour supprimer la suggestion. Vous devez être l'auteur de la suggestion.
L'exemple suivant accepte un fil de suggestions :
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
État de mise à jour des commentaires et des suggestions
Les requêtes qui nécessitent l'enregistrement de fils de commentaires ou de suggestions (comme l'insertion de commentaires, l'ajout de réponses ou la formulation de suggestions) peuvent échouer partiellement. Dans ce cas, les modifications apportées au modèle de document (comme les insertions ou les suppressions de texte) peuvent être correctement appliquées au modèle Docs, mais les commentaires ou suggestions associés peuvent ne pas être enregistrés.
Pour vérifier si les modifications apportées aux commentaires ou aux suggestions ont bien été appliquées, consultez le champ commentUpdateState dans BatchUpdateDocumentResponse.
Les états suivants sont renvoyés dans CommentUpdateState :
NO_UPDATES_REQUESTED: Aucune mise à jour de commentaires ou de suggestions n'a été demandée dans l'opération par lot.ALL_SAVED: toutes les modifications demandées pour les commentaires ou suggestions ont bien été appliquées.ALL_FAILED_UNKNOWN_REASON: toutes les modifications demandées pour les commentaires ou les suggestions n'ont pas pu être enregistrées, même si les modifications apportées au modèle Docs ont pu être validées.