दस्तावेज़

इस गाइड में, 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 डिस्क में दस्तावेज़ प्रबंधित करें

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

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

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

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

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

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

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

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

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

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

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