दस्तावेज़

इस गाइड में, 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 के बारे में जानकारी है, तो documentId, files संसाधन में id के बराबर होता है.

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

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

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

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

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

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

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

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