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

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 को दस्तावेज़ के पहले टैब पर लागू किया जाएगा. ज़्यादा जानकारी के लिए, Requests दस्तावेज़ देखें.