दस्तावेज़

इस गाइड में कई तरह के कॉन्सेप्ट के बारे में बताया गया है. जैसे, 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 और एमआईएमई का सही टाइप एक्सपोर्ट करें. ज़्यादा जानकारी के लिए, 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 के कुछ तरीकों में रिस्पॉन्स के मुख्य हिस्से में, लागू किए गए अनुरोधों की जानकारी शामिल होती है. वहीं, दूसरे तरीकों में जवाब नहीं मिलता.

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

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

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

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

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

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