सबसे अच्छे नतीजों के लिए सबसे सही तरीके

Google Docs API का इस्तेमाल करते समय, आपको कई सिद्धांतों का पालन करना चाहिए. इनमें शामिल हैं:

  • बेहतर तरीके से काम करने के लिए, पीछे की ओर से बदलाव करना
  • मिलकर काम करने के लिए प्लान बनाना
  • WriteControl फ़ील्ड का इस्तेमाल करके, स्थिति को एक जैसा रखें
  • टैब को ध्यान में रखना

यहां दिए गए सेक्शन में, इन सिद्धांतों के बारे में बताया गया है.

बेहतर तरीके से काम करने के लिए, पीछे की ओर से बदलाव करना

documents.batchUpdate तरीके को एक ही बार कॉल करके, अपने अनुरोधों को इंडेक्स की जगह के घटते क्रम में लगाएं. इससे, आइटम जोड़ने और मिटाने की वजह से इंडेक्स में होने वाले बदलावों का हिसाब लगाने की ज़रूरत नहीं पड़ती.

मिलकर काम करने के लिए प्लान बनाना

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

तरीके के कॉल के बीच किसी दस्तावेज़ में कैसे बदलाव किया जा सकता है.

अगर आपके इंडेक्स गलत हैं, तो इससे गड़बड़ियां हो सकती हैं. जब कई उपयोगकर्ता यूज़र इंटरफ़ेस (यूआई) का इस्तेमाल करके किसी दस्तावेज़ में बदलाव करते हैं, तो Google Docs इस बात का ध्यान रखता है कि सभी बदलावों की जानकारी पारदर्शी तरीके से उपलब्ध कराई जाए. हालांकि, एपीआई क्लाइंट के तौर पर आपके ऐप्लिकेशन को इसे मैनेज करना होगा. अगर आपको दस्तावेज़ पर मिलकर काम करने की ज़रूरत नहीं है, तो भी आपको प्रोग्राम को सुरक्षित तरीके से बनाना चाहिए. साथ ही, यह पक्का करना चाहिए कि दस्तावेज़ की स्थिति एक जैसी बनी रहे. डेटा एक जैसा है या नहीं, यह पक्का करने के लिए WriteControl सेक्शन देखें.

WriteControl की मदद से, स्थिति को एक जैसा बनाए रखना

किसी दस्तावेज़ को पढ़ने और फिर उसे अपडेट करने के दौरान, documents.batchUpdate तरीके में मौजूद WriteControl फ़ील्ड का इस्तेमाल करके, यह कंट्रोल किया जा सकता है कि एक साथ किए गए बदलावों को कैसे हैंडल किया जाए. WriteControl के पास यह तय करने का अधिकार होता है कि लिखने के अनुरोधों को कैसे पूरा किया जाए.

इसे इस्तेमाल करने का तरीका यहां दिया गया है:

  1. documents.get तरीके का इस्तेमाल करके दस्तावेज़ पाएं. साथ ही, documents संसाधन से मिले revisionId को सेव करें.
  2. अपडेट के अनुरोध लिखें.
  3. WriteControl ऑब्जेक्ट को शामिल करें. यह ऑब्जेक्ट ज़रूरी नहीं है. इसमें इन दो विकल्पों में से कोई एक विकल्प शामिल करें:
    1. requiredRevisionId फ़ील्ड को उस दस्तावेज़ के revisionId पर सेट किया जाता है जिस पर लिखने का अनुरोध लागू किया जाता है. अगर एपीआई से पढ़ने के अनुरोध के बाद दस्तावेज़ में बदलाव किया गया है, तो लिखने का अनुरोध प्रोसेस नहीं किया जाता है. साथ ही, गड़बड़ी का मैसेज दिखता है.
    2. targetRevisionId फ़ील्ड को दस्तावेज़ के revisionId पर सेट किया जाता है. इस पर लिखने का अनुरोध लागू होता है. अगर एपीआई से पढ़ने के अनुरोध के बाद दस्तावेज़ में बदलाव किया गया है, तो लिखने के अनुरोध में किए गए बदलाव, साथ मिलकर काम करने वाले लोगों के किए गए बदलावों पर लागू होते हैं. लिखने के अनुरोध के नतीजे में, लिखने के अनुरोध में किए गए बदलाव और साथ मिलकर काम करने वाले व्यक्ति के किए गए बदलाव, दोनों शामिल होते हैं. ये बदलाव, दस्तावेज़ के नए वर्शन में दिखते हैं. कॉन्टेंट को मर्ज करने की ज़िम्मेदारी Docs सर्वर की होती है.

WriteControl का इस्तेमाल करके, बैच में अनुरोध बनाने का तरीका जानने के लिए, बैच में अनुरोध भेजने का यह उदाहरण देखें.

टैब को ध्यान में रखना

किसी एक दस्तावेज़ में कई टैब हो सकते हैं. इसके लिए, आपको एपीआई अनुरोधों में खास तरीके से हैंडल करने की ज़रूरत होती है.

इन बातों का ध्यान रखें:

  1. किसी दस्तावेज़ के सभी टैब से कॉन्टेंट वापस पाने के लिए, documents.get तरीके में includeTabsContent पैरामीटर को true पर सेट करें. डिफ़ॉल्ट रूप से, टैब में मौजूद पूरा कॉन्टेंट नहीं दिखाया जाता.
  2. documents.batchUpdate तरीके में, उन टैब के आईडी तय करें जिन पर हर Request लागू करना है. हर Request में, उन टैब को तय करने का तरीका शामिल होता है जिन पर अपडेट लागू करना है. डिफ़ॉल्ट रूप से, अगर कोई टैब नहीं चुना जाता है, तो ज़्यादातर मामलों में Request को दस्तावेज़ के पहले टैब पर लागू किया जाएगा. ज़्यादा जानकारी के लिए, Request के दस्तावेज़ देखें.