दस्तावेज़

इस गाइड में, Google Docs API बनाने के मुख्य तरीकों, दस्तावेज़ को ऐक्सेस करने के तरीके, और दस्तावेज़ बनाते समय वर्कफ़्लो के बारे में जानकारी दी गई है.

एपीआई के तरीके

documents संसाधन में Docs API को शुरू करने के तरीके बताए गए हैं. इन तरीकों से, आपको Docs दस्तावेज़ बनाने, पढ़ने, और उन्हें अपडेट करने में मदद मिलेगी:

  • दस्तावेज़ बनाने के लिए, documents.create तरीके का इस्तेमाल करें.
  • किसी दस्तावेज़ का कॉन्टेंट वापस पाने के लिए, documents.get तरीके का इस्तेमाल करें.
  • किसी दस्तावेज़ पर अपडेट के सेट को अपने-आप लागू करने के लिए, documents.batchUpdate तरीके का इस्तेमाल करें.

टारगेट दस्तावेज़ तय करने के लिए, documents.get और documents.batchUpdate तरीके को पैरामीटर के तौर पर documentId की ज़रूरत होती है. documents.create वाला तरीका, बनाए गए दस्तावेज़ का ऐसा इंस्टेंस दिखाता है जिससे documentId को पढ़ा जा सकता है. Docs API के अनुरोधों और जवाब देने के तरीकों के बारे में ज़्यादा जानने के लिए, अनुरोध और रिस्पॉन्स देखें.

दस्तावेज़ आईडी

documentId, दस्तावेज़ का यूनीक आइडेंटिफ़ायर होता है और इसे दस्तावेज़ के यूआरएल से लिया जा सकता है. यह एक विशेष स्ट्रिंग होती है, जिसमें अक्षर, अंक और कुछ विशेष वर्ण होते हैं. दस्तावेज़ का नाम बदलने पर भी, दस्तावेज़ का आईडी एक जैसा रहता है.

https://docs.google.com/document/d/DOCUMENT_ID/edit

नीचे दिए गए रेगुलर एक्सप्रेशन का इस्तेमाल करके, Google Docs के यूआरएल से documentId को एक्सट्रैक्ट किया जा सकता है:

/document/d/([a-zA-Z0-9-_]+)

अगर आपको Google Drive API के बारे में पता है, तो files संसाधन में documentId, id से जुड़ा है.

Google डिस्क में दस्तावेज़ प्रबंधित करें

दस्तावेज़ फ़ाइलों को Google डिस्क में संग्रहित किया जाता है, जो हमारी क्लाउड-आधारित मेमोरी सेवा है. Docs API के अपने अलग तरीके हैं. हालांकि, उपयोगकर्ता की Docs फ़ाइलों से इंटरैक्ट करने के लिए, Google Drive API का इस्तेमाल करना अक्सर ज़रूरी होता है. उदाहरण के लिए, Docs फ़ाइलें कॉपी करने के लिए, Drive API के files.copy तरीके का इस्तेमाल करें. ज़्यादा जानकारी के लिए, मौजूदा दस्तावेज़ कॉपी करना देखें.

डिफ़ॉल्ट रूप से, Docs API का इस्तेमाल करते समय एक नया दस्तावेज़, Drive पर उपयोगकर्ता के रूट फ़ोल्डर में सेव हो जाता है. फ़ाइल को Drive फ़ोल्डर में सेव करने के विकल्प हैं. ज़्यादा जानकारी के लिए, Google Drive फ़ोल्डर के साथ काम करना देखें.

Docs फ़ाइलों के साथ काम करना

किसी उपयोगकर्ता की 'मेरी ड्राइव' से दस्तावेज़ को वापस लाने के लिए, अक्सर यह ज़रूरी होता है कि फ़ाइल का आईडी फिर से पाने के लिए, पहले Drive के files.list तरीके का इस्तेमाल किया जाए. बिना किसी पैरामीटर के मेथड को कॉल करने पर, लोगों के लिए सभी फ़ाइलों और फ़ोल्डर की सूची दिखती है. इनमें आईडी भी शामिल हैं.

दस्तावेज़ के MIME टाइप से डेटा टाइप और फ़ॉर्मैट के बारे में पता चलता है. Docs के लिए MIME टाइप फ़ॉर्मैट application/vnd.google-apps.document है. MIME टाइप की सूची के लिए, Google Workspace और Google Drive पर काम करने वाले MIME टाइप देखें.

'मेरी ड्राइव' में मौजूद सिर्फ़ Docs फ़ाइलों को MIME टाइप में खोजने के लिए, यह क्वेरी स्ट्रिंग फ़िल्टर जोड़ें:

q: mimeType = 'application/vnd.google-apps.document'

क्वेरी स्ट्रिंग के फ़िल्टर के बारे में ज़्यादा जानकारी के लिए, फ़ाइलें और फ़ोल्डर खोजें देखें.

documentId के बारे में जानने के बाद, तय किए गए दस्तावेज़ का पूरा इंस्टेंस वापस पाने के लिए, documents.get तरीके का इस्तेमाल करें. ज़्यादा जानकारी के लिए, अनुरोध और जवाब देखें.

Google Workspace के दस्तावेज़ का बाइट कॉन्टेंट एक्सपोर्ट करने के लिए, Drive के files.export तरीके का इस्तेमाल करें. साथ ही, फ़ाइल को एक्सपोर्ट करने के लिए, documentId का इस्तेमाल करें और सही MIME टाइप एक्सपोर्ट करें. ज़्यादा जानकारी के लिए, Google Workspace दस्तावेज़ का कॉन्टेंट एक्सपोर्ट करें लेख पढ़ें.

Get और List तरीकों की तुलना करें

नीचे दी गई टेबल में, Drive और Docs दोनों तरीकों के बीच के अंतर और हर एक के साथ मिलने वाले डेटा के बारे में बताया गया है:

ऑपरेटर ब्यौरा इस्तेमाल का तरीका
drive.files.get आईडी के हिसाब से फ़ाइल का मेटाडेटा इकट्ठा करता है. यह files संसाधन का इंस्टेंस दिखाता है. किसी खास फ़ाइल के लिए मेटाडेटा पाना.
drive.files.list उपयोगकर्ता की फ़ाइलें ऐक्सेस करता है. फ़ाइलों की सूची दिखाता है. अगर आपको यह पता नहीं है कि किस फ़ाइल में बदलाव करना है, तो उपयोगकर्ताओं की फ़ाइलों की सूची पाएं.
docs.documents.get बताए गए दस्तावेज़ का सबसे नया वर्शन डाउनलोड करता है. इसमें सभी फ़ॉर्मैटिंग और टेक्स्ट शामिल हैं. यह documents संसाधन का इंस्टेंस दिखाता है. किसी खास दस्तावेज़ के आईडी के लिए दस्तावेज़ पाएं.

दस्तावेज़ बनाने का वर्कफ़्लो

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

नया दस्तावेज़ बनाने और उसे अपने-आप भरने के लिए वर्कफ़्लो.
पहली इमेज. नया दस्तावेज़ बनाने और भरने के लिए वर्कफ़्लो.

पहली इमेज में, documents संसाधन के साथ इंटरैक्ट करने वाले उपयोगकर्ता के पास जानकारी का यह फ़्लो है:

  1. कोई ऐप्लिकेशन, वेब सर्वर पर documents.create तरीके को कॉल करता है.
  2. वेब सर्वर एक एचटीटीपी रिस्पॉन्स भेजता है, जिसमें documents रिसॉर्स के तौर पर बनाए गए दस्तावेज़ का एक इंस्टेंस शामिल होता है.
  3. इसके अलावा, दस्तावेज़ में डेटा अपने-आप भरने के लिए, बदलाव करने के अनुरोधों का एक सेट अपने-आप पूरा करने के लिए, ऐप्लिकेशन documents.batchUpdate तरीके को कॉल करता है.
  4. वेब सर्वर एक एचटीटीपी रिस्पॉन्स भेजता है. documents.batchUpdate के कुछ तरीकों में, रिस्पॉन्स का मुख्य हिस्सा लागू किए गए अनुरोधों के बारे में जानकारी देता है, जबकि कुछ के लिए कोई जवाब नहीं दिखता.

दस्तावेज़ अपडेट करने का वर्कफ़्लो

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

वर्कफ़्लो को अपडेट करना है.
दूसरी इमेज. दस्तावेज़ को अपडेट करने के लिए वर्कफ़्लो.

इमेज 2 में, documents संसाधन के साथ इंटरैक्ट करने वाले उपयोगकर्ता के पास जानकारी का यह फ़्लो है:

  1. कोई ऐप्लिकेशन, वेब सर्वर पर documents.get तरीके को कॉल करता है. साथ ही, फ़ाइल ढूंढने के लिए documentId मौजूद होता है.
  2. वेब सर्वर एक एचटीटीपी रिस्पॉन्स भेजता है, जिसमें documents रिसॉर्स के तौर पर बताए गए दस्तावेज़ का एक इंस्टेंस शामिल होता है. दिखाए गए JSON में, दस्तावेज़ का कॉन्टेंट, फ़ॉर्मैटिंग, और अन्य सुविधाएं शामिल होती हैं.
  3. ऐप्लिकेशन, JSON को पार्स करता है, ताकि उपयोगकर्ता यह तय कर सके कि किस कॉन्टेंट या फ़ॉर्मैट को अपडेट करना है.
  4. यह ऐप्लिकेशन, documents.batchUpdate वाले तरीके को कॉल करता है, ताकि दस्तावेज़ को अपडेट करने के लिए, बदलाव करने के अनुरोधों का सेट अपने-आप लागू हो जाए.
  5. वेब सर्वर एक एचटीटीपी रिस्पॉन्स भेजता है. documents.batchUpdate के कुछ तरीकों में, रिस्पॉन्स का मुख्य हिस्सा लागू किए गए अनुरोधों के बारे में जानकारी देता है, जबकि कुछ के लिए कोई जवाब नहीं दिखता.

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