In Google Docs können Mitarbeiter zusammenarbeiten, indem sie Kommentare schreiben und Vorschläge machen, die als aufgeschobene Änderungen auf Genehmigung warten.
Mit der API können Sie vorgeschlagene Änderungen inline im Dokumenttext anzeigen lassen. In der Developer Preview können Sie Kommentare und Vorschläge auch programmatisch lesen, erstellen, beantworten, aktualisieren oder löschen.
Wenn Sie die Methode documents.get verwenden, um Dokumentinhalte abzurufen, können diese nicht aufgelöste Vorschläge enthalten. Mit dem optionalen Parameter SuggestionsViewMode können Sie festlegen, wie documents.get Vorschläge darstellt. Mit diesem Parameter sind die folgenden Filterbedingungen verfügbar:
- Inhalte mit
SUGGESTIONS_INLINEabrufen, damit Text, der entweder gelöscht oder eingefügt werden soll, im Dokument angezeigt wird. - Inhalte als Vorschau mit allen akzeptierten Vorschlägen ansehen
- Inhalte als Vorschau ohne Vorschläge abrufen, wobei alle Vorschläge abgelehnt werden.
Wenn Sie SuggestionsViewMode nicht angeben, wird von der Google Docs API eine Standardeinstellung verwendet, die den Berechtigungen des aktuellen Nutzers entspricht.
Vorschläge und Indexe
Der SuggestionsViewMode ist wichtig, weil die Indexe in der Antwort je nach Vorhandensein von Vorschlägen variieren können, wie unten dargestellt.
| Inhalte mit Vorschlägen | Inhalte ohne Vorschläge |
|---|---|
{
"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"
}
}
}
]
}
}
}
]
},
|
Im obigen Beispiel wird im Absatz mit der Zeile „Text nach dem Vorschlag“ der Unterschied bei der Verwendung von SuggestionsViewMode deutlich. Wenn der Wert auf SUGGESTIONS_INLINE festgelegt ist, beginnt die startIndex der ParagraphElement bei 51 und die endIndex endet bei 81. Ohne Vorschläge liegt der Bereich für startIndex und endIndex zwischen 32 und 62.
Inhalte ohne Vorschläge erhalten
Im folgenden teilweisen Codebeispiel wird gezeigt, wie Sie ein Dokument als Vorschau abrufen, wobei alle Vorschläge abgelehnt werden (falls vorhanden). Dazu wird der Parameter SuggestionsViewMode auf PREVIEW_WITHOUT_SUGGESTIONS gesetzt.
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() )
Wenn Sie den Parameter SuggestionsViewMode weglassen, entspricht das der Angabe von DEFAULT_FOR_CURRENT_ACCESS als Parameterwert.
Stilvorschläge
Dokumente können auch Stilvorschläge enthalten. Es handelt sich um vorgeschlagene Änderungen an Formatierung und Darstellung, nicht am Inhalt.
Im Gegensatz zu Texteinfügungen oder ‑löschungen werden die Indexe dadurch nicht verschoben. Allerdings kann ein TextRun in kleinere Abschnitte unterteilt werden. Es werden lediglich Anmerkungen zur vorgeschlagenen Stiländerung hinzugefügt.
Eine solche Anmerkung ist eine SuggestedTextStyle>, die aus zwei Teilen besteht:
Die
textStylebeschreibt, wie der Text nach der vorgeschlagenen Änderung formatiert wird, gibt aber nicht an, was sich geändert hat.Die
textStyleSuggestionStategibt an, wie die Felder dertextStyledurch den Vorschlag geändert werden.
Das sehen Sie im folgenden Auszug aus einem Dokumenttab, der eine vorgeschlagene Stiländerung enthält:
[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] }
Im Beispiel oben besteht der Absatz aus drei Textläufen, die in den Zeilen 6, 14 und 50 beginnen. Sehen Sie sich den mittleren Textlauf an:
- Zeile 16: Es gibt ein
suggestedTextStyleChanges-Objekt. - Zeile 18: Mit
textStylewird die Formatierung angegeben. - Zeile 36: Das
textStyleSuggestionStategibt an, dass nur der fettgedruckte Teil dieser Spezifikation der Vorschlag war. - Zeile 42: Die kursive Formatierung dieses Textblocks ist Teil des aktuellen Dokuments und wird nicht durch den Vorschlag beeinflusst.
Nur die Stilmerkmale, die in textStyleSuggestionState auf true festgelegt sind, sind Teil des Vorschlags.
Kommentare erstellen und verwalten
Mit der Methode documents.batchUpdate können Sie programmatisch Kommentare und Antworten hinzufügen, Kommentare bearbeiten und Kommentare oder Antworten löschen.
Wenn Sie Batch-Updates mit Kommentaren oder Vorschlägen durchführen, sollten Sie auf mögliche Teilausfälle achten. Weitere Informationen finden Sie unter Status von Kommentaren und Vorschlägen.
Kommentar einfügen
Verwenden Sie das InsertCommentRequest-Objekt, um einen Kommentar-Thread einzufügen. Sie müssen den Kommentartext und eine Ankerposition (z. B. einen Bereich) angeben, an der der Kommentar angehängt wird.
Im folgenden JSON-Beispiel wird dem angegebenen Bereich ein nicht zugewiesener Kommentarthread hinzugefügt:
{
"requests": [
{
"insertComment": {
"content": "This is a comment added via the API.",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Sie können einen Kommentar einem bestimmten Nutzer zuweisen, indem Sie seine E-Mail-Adresse im Feld assigneeEmailAddress angeben:
{
"requests": [
{
"insertComment": {
"content": "Please review this paragraph.",
"assigneeEmailAddress": "user@example.com",
"range": {
"startIndex": 10,
"endIndex": 25
}
}
}
]
}
Antwort hinzufügen oder Maßnahmen ergreifen
Wenn Sie auf einen Kommentar- oder Vorschlags-Thread antworten oder einen Thread schließen oder wieder öffnen möchten, verwenden Sie AddCommentReplyRequest.
Eine Antwort wird durch ein Post-Objekt dargestellt.
Das Post-Objekt enthält die Antwort content und kann optional eine commentAction angeben (zum RESOLVE oder REOPEN des Threads).
Hier sind einige Beispielantworten auf einen vorhandenen Kommentarthread:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"content": "Replying to the comment thread."
}
}
}
]
}
Im folgenden Beispiel wird ein Kommentar-Thread geschlossen. Dazu ist kein Inhalt erforderlich:
{
"requests": [
{
"addCommentReply": {
"commentId": "comment_thread_id",
"post": {
"commentAction": "RESOLVE"
}
}
}
]
}
Beitrag bearbeiten
Wenn Sie den Textinhalt eines von Ihnen erstellten Beitrags bearbeiten möchten, verwenden Sie UpdateCommentPostRequest.
Sie müssen die Thread-ID (entweder commentId oder suggestionId), die postId des Beitrags, den Sie bearbeiten möchten, und den neuen Nur-Text-content angeben.
Sie können den ersten Beitrag eines Vorschlags-Threads nicht bearbeiten, da er durch Bearbeitungen im Vorschlagsmodus generiert wird.
{
"requests": [
{
"updateCommentPost": {
"commentId": "comment_thread_id",
"postId": "post_id",
"content": "This is the updated comment text."
}
}
]
}
Kommentare und Antworten löschen
- Kommentar-Thread löschen:Wenn Sie einen ganzen Kommentar-Thread entfernen möchten, verwenden Sie
DeleteCommentRequest. Sie können einen Kommentar-Thread nur löschen, wenn Sie der Autor des ersten Beitrags im Thread sind. - Antwort löschen:Wenn Sie eine bestimmte Antwort löschen möchten, verwenden Sie
DeleteCommentReplyRequest. Sie können nur Antworten löschen, die Sie selbst verfasst haben. Antwortbeiträge, die Aktionen oder zugewiesene Personen enthalten, können nicht gelöscht werden.
Im folgenden Beispiel wird ein Kommentar-Thread gelöscht:
{
"requests": [
{
"deleteComment": {
"commentId": "comment_thread_id"
}
}
]
}
Vorschläge schreiben und Vorschlags-Threads verwalten
Sie können Änderungen als Vorschläge anstelle von direkten Änderungen schreiben und Vorschlags-Threads programmatisch annehmen, ablehnen oder löschen.
Wenn Sie Batch-Updates mit Vorschlägen durchführen, sollten Sie auf mögliche Teilausfälle achten. Weitere Informationen finden Sie unter Status von Kommentaren und Vorschlägen.
Vorschläge im Vorschlagsmodus erstellen
Wenn Sie Änderungen als Vorschläge anwenden möchten, legen Sie das Feld writeMode des WriteControl-Objekts in Ihrer Batch-Aktualisierungsanfrage auf SUGGEST fest. Alle Aktualisierungen in der Anfrage werden als Vorschläge verarbeitet.
{
"requests": [
{
"insertText": {
"text": "suggested insertion text",
"location": {
"index": 1
}
}
}
],
"writeControl": {
"writeMode": "SUGGEST"
}
}
Nicht unterstützte Anfragen im Vorschlagsmodus
Bei der Verwendung von WriteMode.SUGGEST werden die folgenden Anfragetypen nicht unterstützt und geben einen Fehler zurück:
AddDocumentTabCreateNamedRangeDeleteFooterDeleteHeaderDeleteNamedRangeDeleteTabUpdateDocumentTabPropertiesUpdateTableColumnProperties
Außerdem können Sie keine Änderungen am Dokumentformat oder an den Einstellungen für Kopf- und Fußzeilen vorschlagen. In UpdateDocumentStyle werden Vorschläge für die folgenden Stiltypen nicht unterstützt:
documentFormatuseEvenPageHeaderFooteruseFirstPageHeaderFooter
Vorschlags-Threads annehmen, ablehnen oder löschen
Sie können Vorschlags-Threads mit den folgenden Anfragen verwalten:
- Vorschlag annehmen:Verwenden Sie
AcceptSuggestionRequest, um den Vorschlag anzunehmen. Dazu ist Bearbeitungszugriff auf das Dokument erforderlich. - Vorschlag ablehnen:Verwenden Sie
RejectSuggestionRequest, um den Vorschlag abzulehnen. Dazu benötigen Sie Bearbeitungszugriff auf das Dokument oder müssen der Autor des Vorschlags sein. - Vorschlag löschen:Verwenden Sie
DeleteSuggestionRequest, um den Vorschlag zu löschen. Dazu müssen Sie der Autor des Vorschlags sein.
Im folgenden Beispiel wird ein Vorschlags-Thread akzeptiert:
{
"requests": [
{
"acceptSuggestion": {
"suggestionId": "suggestion_thread_id"
}
}
]
}
Status von Kommentaren und Vorschlägen
Bei Anfragen, für die Kommentar- oder Vorschlags-Threads gespeichert werden müssen (z. B. beim Einfügen von Kommentaren, Hinzufügen von Antworten oder Machen von Vorschlägen), kann es zu teilweisen Fehlern kommen. In diesen Fällen werden die Änderungen am Dokumentmodell (z. B. Einfügen oder Löschen von Text) möglicherweise erfolgreich im Docs-Modell gespeichert, die zugehörigen Kommentare oder Vorschläge jedoch nicht.
Sie können prüfen, ob Kommentar- oder Vorschlagsaktualisierungen erfolgreich angewendet wurden, indem Sie das Feld commentUpdateState in BatchUpdateDocumentResponse prüfen.
Die folgenden Status werden in CommentUpdateState zurückgegeben:
NO_UPDATES_REQUESTED: Im Batchvorgang wurden keine Aktualisierungen von Kommentaren oder Vorschlägen angefordert.ALL_SAVED: Alle angeforderten Aktualisierungen von Kommentaren oder Vorschlägen wurden erfolgreich angewendet.ALL_FAILED_UNKNOWN_REASON: Alle angeforderten Aktualisierungen von Kommentaren oder Vorschlägen konnten nicht gespeichert werden, obwohl die Änderungen am Docs-Modell möglicherweise übernommen wurden.