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

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

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

दस्तावेज़ का कॉन्टेंट फ़ेच करने के लिए, 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"
        }
       }
      }
     ]
    }
   }
  }
 ]
},

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

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

यहां दिए गए कोड के कुछ हिस्से के सैंपल में, यह दिखाया गया है कि सभी सुझावों को अस्वीकार करके, किसी दस्तावेज़ को झलक के तौर पर कैसे देखा जा सकता है. इसके लिए, SuggestionsViewMode पैरामीटर को PREVIEW_WITHOUT_SUGGESTIONS पर सेट करें.

final string SUGGEST_MODE = "PREVIEW_WITHOUT_SUGGESTIONS";
Document doc =
    service
        .documents()
        .get(DOCUMENT_ID)
        .setIncludeTabsContent(true)
        .setSuggestionsViewMode(SUGGEST_MODE)
        .execute();

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 मॉडल में बदलाव हो गए हों.