टिप्पणियों और सुझावों का इस्तेमाल करना

Google Docs में, साथ मिलकर काम करने वाले लोग टिप्पणियां लिखकर और सुझाव देकर सहयोग कर सकते हैं. ये सुझाव, बदलाव के तौर पर सेव हो जाते हैं और मंज़ूरी मिलने के बाद ही लागू होते हैं.

दस्तावेज़ के टेक्स्ट में, सुझाए गए बदलावों को इनलाइन देखने के लिए, एपीआई का इस्तेमाल किया जा सकता है. डेवलपर के लिए झलक में, टिप्पणियों और सुझावों की थ्रेड को प्रोग्राम के ज़रिए पढ़ा, बनाया, जवाब दिया, अपडेट किया या मिटाया जा सकता है.

`documents.get` तरीके का इस्तेमाल करके, दस्तावेज़ का कॉन्टेंट फ़ेच करने पर, कॉन्टेंट में ऐसे सुझाव शामिल हो सकते हैं जिन पर अब तक कोई कार्रवाई नहीं की गई है.documents.get में सुझाव किस तरह दिखें, यह कंट्रोल करने के लिए, documents.get पैरामीटर का इस्तेमाल करें. यह पैरामीटर ज़रूरी नहीं है. SuggestionsViewMode इस पैरामीटर के साथ, फ़िल्टर करने की ये शर्तें उपलब्ध हैं:

  • SUGGESTIONS_INLINE के साथ कॉन्टेंट पाएं, ताकि दस्तावेज़ में ऐसा टेक्स्ट दिखे जिसे मिटाया या जोड़ा जाना है.
  • सभी सुझाव स्वीकार किए जाने के बाद, कॉन्टेंट को झलक के तौर पर पाएं.
  • सभी सुझाव अस्वीकार किए जाने के बाद, कॉन्टेंट को झलक के तौर पर पाएं. इसमें सुझाव शामिल नहीं होते.

अगर SuggestionsViewMode की वैल्यू नहीं दी जाती है, तो Google Docs API, डिफ़ॉल्ट सेटिंग का इस्तेमाल करता है. यह सेटिंग, मौजूदा उपयोगकर्ता के अधिकारों के हिसाब से होती है.

दस्तावेज़ फ़ेच करते समय, टिप्पणियां शामिल की जाएं या नहीं, यह कंट्रोल करने के लिए, ज़रूरी नहीं commentsViewMode पैरामीटर का इस्तेमाल करें. अगर commentsViewMode को COMMENTS_VIEW_MODE_INCLUDED पर सेट किया जाता है, तो includeTabsContent को भी true पर सेट करना होगा. इसके अलावा, अगर फ़ील्ड मास्क का इस्तेमाल किया जाता है, जो tabs फ़ील्ड (या किसी सब-फ़ील्ड) को रेफ़र करता है, तो एपीआई, अनुरोध को इस तरह से प्रोसेस करता है जैसे कि includeTabsContent को true पर सेट किया गया हो.

सुझाव और इंडेक्स

SuggestionsViewMode ज़रूरी है. इसकी एक वजह यह है कि रिस्पॉन्स में मौजूद इंडेक्स, सुझावों के आधार पर अलग-अलग हो सकते हैं. जैसा कि यहां दिए गए उदाहरण में दिखाया गया है.

सुझावों के साथ कॉन्टेंट बिना सुझावों के कॉन्टेंट 
{
 "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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

ऊपर दिए गए रिस्पॉन्स में, "Text following the suggestion" लाइन वाले पैराग्राफ़ में, SuggestionsViewMode का इस्तेमाल करने पर दिखने वाले अंतर को दिखाया गया है. वैल्यू को SUGGESTIONS_INLINE पर सेट करने पर, startIndex का ParagraphElement 51 से शुरू होता है और endIndex 81 पर खत्म होता है. सुझावों के बिना, startIndex और endIndex की रेंज 32–62 होती है.

बिना सुझावों के कॉन्टेंट पाना

कोड सैंपल के इस हिस्से में, SuggestionsViewMode पैरामीटर को 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()
)

SuggestionsViewMode पैरामीटर को शामिल न करने का मतलब है कि पैरामीटर वैल्यू के तौर पर DEFAULT_FOR_CURRENT_ACCESS दिया गया है.

स्टाइल से जुड़े सुझाव

दस्तावेज़ों में स्टाइल से जुड़े सुझाव भी हो सकते हैं. ये सुझाव, कॉन्टेंट में बदलाव के बजाय, फ़ॉर्मैटिंग और प्रज़ेंटेशन में बदलाव के लिए होते हैं.

टेक्स्ट जोड़ने या मिटाने के उलट, इनसे इंडेक्स ऑफ़सेट नहीं होते. हालांकि, इनसे TextRun को छोटे-छोटे हिस्सों में बांटा जा सकता है. साथ ही, सुझाए गए स्टाइल में बदलाव के बारे में एनोटेशन जोड़े जा सकते हैं.

ऐसा ही एक एनोटेशन SuggestedTextStyle, है, जो दो हिस्सों से मिलकर बना होता है:

  • textStyle, जिसमें बताया जाता है कि सुझाए गए बदलाव के बाद, टेक्स्ट की स्टाइल कैसी होगी. हालांकि, इसमें यह नहीं बताया जाता कि क्या बदला है.

  • textStyleSuggestionState, जिसमें बताया जाता है कि सुझाव से textStyle के फ़ील्ड में कैसे बदलाव होता है.

इसे दस्तावेज़ के टैब के इस एक्सट्रैक्ट में देखा जा सकता है. इसमें स्टाइल में बदलाव का एक सुझाव शामिल है:

[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] }

ऊपर दिए गए सैंपल में, पैराग्राफ़ में तीन टेक्स्ट रन शामिल हैं. ये लाइन 6, 14, और 50 से शुरू होते हैं. बीच वाले टेक्स्ट रन की जांच करें:

  • लाइन 16: इसमें suggestedTextStyleChanges ऑब्जेक्ट है.
  • लाइन 18: textStyle में अलग-अलग फ़ॉर्मैटिंग के बारे में बताया गया है.
  • लाइन 36: textStyleSuggestionState से पता चलता है कि इस जानकारी में सिर्फ़ बोल्ड वाला हिस्सा, सुझाव के तौर पर दिया गया था.
  • लाइन 42: इस टेक्स्ट रन की इटैलिक स्टाइल, मौजूदा दस्तावेज़ का हिस्सा है. इस पर सुझाव का कोई असर नहीं पड़ा है.

textStyleSuggestionState में, स्टाइल की सिर्फ़ वे सुविधाएं सुझाव का हिस्सा होती हैं जिन्हें true पर सेट किया गया है.

टिप्पणियां बनाना और मैनेज करना

`documents.batchUpdate` तरीके का इस्तेमाल करके, टिप्पणियां और जवाब प्रोग्राम के ज़रिए जोड़े जा सकते हैं. साथ ही, टिप्पणियों में बदलाव किया जा सकता है और टिप्पणियां या जवाब मिटाए जा सकते हैं .

टिप्पणियों या सुझावों से जुड़े बैच अपडेट करते समय, आपको आंशिक तौर पर होने वाली गड़बड़ियों पर नज़र रखनी चाहिए. ज़्यादा जानकारी के लिए, टिप्पणी और सुझाव के अपडेट की स्थिति देखें.

कोई टिप्पणी जोड़ना

टिप्पणी की थ्रेड जोड़ने के लिए, InsertCommentRequest ऑब्जेक्ट का इस्तेमाल करें. आपको टिप्पणी के टेक्स्ट का कॉन्टेंट और ऐंकर की जगह (जैसे, कोई रेंज) देनी होगी, जहां टिप्पणी अटैच की गई है.

JSON के इस उदाहरण में, तय की गई रेंज में, बिना असाइन की गई टिप्पणी की थ्रेड जोड़ी गई है:

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

assigneeEmailAddress फ़ील्ड में, उपयोगकर्ता का ईमेल देकर, किसी टिप्पणी को किसी खास उपयोगकर्ता को असाइन किया जा सकता है:

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

कोई जवाब जोड़ना या कार्रवाई करना

किसी टिप्पणी या सुझाव की थ्रेड का जवाब देने या किसी थ्रेड को हल करने या फिर से खोलने के लिए, AddCommentReplyRequest का इस्तेमाल करें.

किसी जवाब को Post ऑब्जेक्ट के तौर पर दिखाया जाता है. Post ऑब्जेक्ट में, जवाब का content शामिल होता है. साथ ही, इसमें commentAction (थ्रेड को RESOLVE या REOPEN करने के लिए) भी तय किया जा सकता है. यह ज़रूरी नहीं है.

Post ऑब्जेक्ट में, नया assigneeEmail तय करके, टिप्पणी की थ्रेड को फिर से असाइन भी किया जा सकता है.

यहां दिए गए सैंपल में, मौजूदा टिप्पणी की थ्रेड का जवाब दिया गया है:

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

यहां दिए गए सैंपल में, टिप्पणी की थ्रेड को हल किया गया है. इसके लिए, कॉन्टेंट की ज़रूरत नहीं होती:

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

JSON के इस सैंपल में, टिप्पणी की थ्रेड को फिर से असाइन करने का तरीका दिखाया गया है:

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

किसी पोस्ट में बदलाव करना

अपनी लिखी किसी पोस्ट के टेक्स्ट कॉन्टेंट में बदलाव करने के लिए, UpdateCommentPostRequest का इस्तेमाल करें. आपको थ्रेड आईडी (commentId या suggestionId), उस पोस्ट का postId जिसमें बदलाव करना है, और नया सादा टेक्स्ट content तय करना होगा.

ध्यान दें कि सुझाव की थ्रेड की हेड पोस्ट में बदलाव नहीं किया जा सकता. ऐसा इसलिए, क्योंकि ये पोस्ट, सुझाव मोड में किए गए बदलावों से जनरेट होती हैं.

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

टिप्पणियां और जवाब मिटाना

  • टिप्पणी की थ्रेड मिटाना: टिप्पणी की पूरी थ्रेड हटाने के लिए, DeleteCommentRequest का इस्तेमाल करें. टिप्पणी की थ्रेड को सिर्फ़ तब मिटाया जा सकता है, जब आप थ्रेड की हेड पोस्ट के लेखक हों.
  • कोई जवाब मिटाना: किसी खास जवाब वाली पोस्ट को मिटाने के लिए, DeleteCommentReplyRequest का इस्तेमाल करें. सिर्फ़ वे जवाब मिटाए जा सकते हैं जिन्हें आपने लिखा है. जवाब वाली उन पोस्ट को नहीं मिटाया जा सकता जिनमें कार्रवाइयां या असाइन किए गए लोग शामिल हैं.

यहां दिए गए सैंपल में, टिप्पणी की थ्रेड मिटाई गई है:

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

सुझाव लिखना और सुझावों की थ्रेड मैनेज करना

सीधे बदलाव करने के बजाय, बदलावों को सुझाव के तौर पर लिखा जा सकता है. साथ ही, सुझावों की थ्रेड को प्रोग्राम के ज़रिए स्वीकार, अस्वीकार या मिटाया जा सकता है.

सुझावों से जुड़े बैच अपडेट करते समय, आपको आंशिक तौर पर होने वाली गड़बड़ियों पर नज़र रखनी चाहिए. ज़्यादा जानकारी के लिए, टिप्पणी और सुझाव के अपडेट की स्थिति देखें.

सुझाव मोड का इस्तेमाल करके सुझाव बनाना

बदलावों को सुझाव के तौर पर लागू करने के लिए, बैच अपडेट के अनुरोध में, WriteControl ऑब्जेक्ट के writeMode फ़ील्ड को SUGGEST पर सेट करें. अनुरोध में मौजूद सभी अपडेट, सुझाव के तौर पर प्रोसेस किए जाते हैं.

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

सुझाव मोड में, इन अनुरोधों को प्रोसेस नहीं किया जा सकता

WriteMode.SUGGEST का इस्तेमाल करने पर, इन अनुरोधों को प्रोसेस नहीं किया जा सकता. साथ ही, इनके लिए गड़बड़ी का मैसेज दिखेगा:

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

इसके अलावा, दस्तावेज़ के फ़ॉर्मैट या हेडर और फ़ुटर की सेटिंग में बदलाव के लिए सुझाव नहीं दिए जा सकते. UpdateDocumentStyle में, स्टाइल के इन टाइप के लिए सुझाव नहीं दिए जा सकते:

  • documentFormat
  • useEvenPageHeaderFooter
  • useFirstPageHeaderFooter

सुझावों की थ्रेड स्वीकार, अस्वीकार या मिटाना

सुझावों की थ्रेड को इन अनुरोधों का इस्तेमाल करके मैनेज किया जा सकता है:

  • सुझाव स्वीकार करना: सुझाव स्वीकार करने के लिए, AcceptSuggestionRequest का इस्तेमाल करें. इसके लिए, दस्तावेज़ में बदलाव करने का ऐक्सेस होना ज़रूरी है.
  • सुझाव अस्वीकार करना: सुझाव अस्वीकार करने के लिए, RejectSuggestionRequest का इस्तेमाल करें. इसके लिए, दस्तावेज़ में बदलाव करने का ऐक्सेस होना ज़रूरी है. साथ ही, यह भी ज़रूरी है कि आप सुझाव के लेखक हों.
  • सुझाव मिटाना: सुझाव मिटाने के लिए, DeleteSuggestionRequest का इस्तेमाल करें. इसके लिए, यह ज़रूरी है कि आप सुझाव के लेखक हों.

यहां दिए गए सैंपल में, सुझाव की थ्रेड स्वीकार की गई है:

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

टिप्पणी और सुझाव के अपडेट की स्थिति

ऐसे अनुरोधों में आंशिक तौर पर गड़बड़ियां हो सकती हैं जिनमें टिप्पणी या सुझाव की थ्रेड सेव करनी होती हैं. जैसे, टिप्पणियां जोड़ना, जवाब जोड़ना या सुझाव देना. इन मामलों में, दस्तावेज़ मॉडल में बदलाव (जैसे, टेक्स्ट जोड़ना या मिटाना) Docs मॉडल में सेव हो सकते हैं. हालांकि, इनसे जुड़ी टिप्पणियां या सुझाव सेव नहीं हो पाते.

यह देखने के लिए कि टिप्पणी या सुझाव के अपडेट सेव हुए हैं या नहीं, commentUpdateState फ़ील्ड की जांच करें.BatchUpdateDocumentResponse

CommentUpdateState में ये स्थितियां दिखती हैं:

  • NO_UPDATES_REQUESTED: बैच ऑपरेशन में, टिप्पणी या सुझाव के अपडेट का कोई अनुरोध नहीं किया गया.
  • ALL_SAVED: टिप्पणी या सुझाव के सभी अनुरोध किए गए अपडेट, सेव हो गए हैं.
  • ALL_FAILED_UNKNOWN_REASON: टिप्पणी या सुझाव के सभी अनुरोध किए गए अपडेट, सेव नहीं हो पाए. भले ही, Docs मॉडल में बदलाव सेव हो गए हों.