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

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

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

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

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

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

दस्तावेज़ फ़ेच करते समय टिप्पणियां शामिल की जाएं या नहीं, यह कंट्रोल करने के लिए, वैकल्पिक commentsViewMode पैरामीटर का इस्तेमाल करें. टिप्पणियां सिर्फ़ तब दिखती हैं, जब सुझाव इनलाइन दिखते हैं. commentsViewMode को सेट करते समय, आपको suggestionsViewMode को भी इस तरह कॉन्फ़िगर करना होगा:

  • अगर commentsViewMode को COMMENTS_VIEW_MODE_INCLUDED पर सेट किया गया है, तो suggestionsViewMode को SUGGESTIONS_INLINE पर सेट करना ज़रूरी है.
  • अगर commentsViewMode को COMMENTS_VIEW_MODE_DEFAULT_FOR_CURRENT_ACCESS पर सेट किया गया है, तो suggestionsViewMode को SUGGESTIONS_INLINE या DEFAULT_FOR_CURRENT_ACCESS पर सेट करना ज़रूरी है.

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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

ऊपर दिए गए जवाब में, "सुझाव के बाद का टेक्स्ट" वाली लाइन वाले पैराग्राफ़ में, SuggestionsViewMode का इस्तेमाल करने पर दिखने वाला अंतर दिखाया गया है. SUGGESTIONS_INLINE पर सेट की गई वैल्यू के साथ, ParagraphElement का startIndex 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 मॉडल में सेव हो सकते हैं. हालांकि, इससे जुड़ी टिप्पणियां या सुझाव सेव नहीं हो सकते.

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

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

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