टेक्स्ट को किसी दस्तावेज़ में मर्ज करना

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

टेंप्लेट एक तरह का दस्तावेज़ होता है. इसमें तय किया गया टेक्स्ट और डाइनैमिक कॉन्टेंट के लिए प्लेसहोल्डर होते हैं. उदाहरण के लिए, किसी कानूनी समझौते के टेंप्लेट में, कुछ टेक्स्ट पहले से मौजूद हो सकता है. साथ ही, उसमें ईमेल पाने वाले का नाम और पता डालने के लिए प्लेसहोल्डर हो सकते हैं. इसके बाद, ऐप्लिकेशन उपयोगकर्ता के हिसाब से डेटा को टेंप्लेट में मर्ज करता है, ताकि पूरा दस्तावेज़ तैयार किया जा सके.

इस तरीके के फ़ायदे कई हैं:

  • डिज़ाइनर, Google Docs का इस्तेमाल करके किसी दस्तावेज़ के डिज़ाइन को बेहतर बना सकते हैं. रेंडर किए गए लेआउट को सेट करने के लिए, यह तरीका आपके ऐप्लिकेशन में पैरामीटर को ट्यून करने से ज़्यादा आसान है.

  • कॉन्टेंट को प्रज़ेंटेशन से अलग करना, डिज़ाइन का एक जाना-माना सिद्धांत है. इसके कई फ़ायदे हैं.

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

दस्तावेज़ मर्ज करने की सुविधा कैसे काम करती है

यहां एक उदाहरण दिया गया है, जिसमें बताया गया है कि किसी दस्तावेज़ में डेटा को मर्ज करने के लिए, Docs API का इस्तेमाल कैसे किया जा सकता है:

  1. अपने दस्तावेज़ को डिज़ाइन और फ़ॉर्मैट करने के लिए, प्लेसहोल्डर वाले कॉन्टेंट का इस्तेमाल करें. टेक्स्ट फ़ॉर्मैटिंग में किए गए बदलावों को बनाए रखा जाता है.

  2. आपको जिस एलिमेंट को डालना है उसके लिए, प्लेसहोल्डर कॉन्टेंट को टैग से बदलें. ऐसी स्ट्रिंग का इस्तेमाल करें जो आम तौर पर नहीं दिखती हैं. उदाहरण के लिए, {{account-holder-name}} एक अच्छा टैग हो सकता है.

  3. अपने कोड में, Google Drive API का इस्तेमाल करके दस्तावेज़ की कॉपी बनाएं.

  4. अपने कोड में, Docs API के batchUpdate तरीके का इस्तेमाल करें. साथ ही, दस्तावेज़ का नाम और ReplaceAllTextRequest शामिल करें.

दस्तावेज़ आईडी, किसी दस्तावेज़ का रेफ़रंस देते हैं. इन्हें यूआरएल से लिया जा सकता है:

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

टेंप्लेट मैनेज करना

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

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

सेवा खाते का इस्तेमाल करके टेंप्लेट बनाने के लिए, ऐप्लिकेशन के क्रेडेंशियल का इस्तेमाल करके यह तरीका अपनाएं:

  1. Docs API में documents.create का इस्तेमाल करके कोई दस्तावेज़ बनाएं.
  2. Drive API में permissions.create का इस्तेमाल करके, दस्तावेज़ पाने वालों को इसे पढ़ने की अनुमति देने के लिए, अनुमतियां अपडेट करें.
  3. अनुमतियां अपडेट करें, ताकि टेंप्लेट बनाने वाले लोग Drive API में permissions.create का इस्तेमाल करके, टेंप्लेट में बदलाव कर सकें.
  4. ज़रूरत के मुताबिक टेंप्लेट में बदलाव करें.

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

  1. Drive API में files.copy का इस्तेमाल करके, टेंप्लेट की कॉपी बनाएं.
  2. Docs API में documents.batchUpdate का इस्तेमाल करके वैल्यू बदलें.

उदाहरण: डेटा को टेंप्लेट में मर्ज करना

यहां दिए गए कोड के सैंपल में, किसी टेंप्लेट के सभी टैब में मौजूद दो फ़ील्ड को असली वैल्यू से बदलने का तरीका बताया गया है, ताकि पूरा दस्तावेज़ जनरेट किया जा सके:

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

इस मर्ज को पूरा करने के लिए, इस कोड का इस्तेमाल करें:

Java

String customerName = "Alice";
DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy/MM/dd");
String date = formatter.format(LocalDate.now());

// Make a copy of the template document using the Drive API.
String copyTitle = "Merged Document";
File copyMetadata = new File().setName(copyTitle);
File documentCopyFile =
        driveService.files().copy(DOCUMENT_ID, copyMetadata).execute();
String documentCopyId = documentCopyFile.getId();

List requests = new ArrayList<>();
// One option for replacing all text is to specify all tab IDs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{customer-name}}")
                        .setMatchCase(true))
                .setReplaceText(customerName)
                .setTabsCriteria(new TabsCriteria()
                        .addTabIds(TAB_ID_1)
                        .addTabIds(TAB_ID_2)
                        .addTabIds(TAB_ID_3))));
// Another option is to omit TabsCriteria if you are replacing across all tabs.
requests.add(new Request()
        .setReplaceAllText(new ReplaceAllTextRequest()
                .setContainsText(new SubstringMatchCriteria()
                        .setText("{{date}}")
                        .setMatchCase(true))
                .setReplaceText(date)));

BatchUpdateDocumentRequest body = new BatchUpdateDocumentRequest();
service.documents().batchUpdate(documentCopyId, body.setRequests(requests)).execute();

Node.js

  let customerName = 'Alice';
  let date = yyyymmdd()
  let requests = [
    // One option for replacing all text is to specify all tab IDs.
    {
      replaceAllText: {
        containsText: {
          text: '{{customer-name}}',
          matchCase: true,
        },
        replaceText: customerName,
        tabsCriteria: {
          tabIds: [TAB_ID_1, TAB_ID_2, TAB_ID_3],
        },
      },
    },
    // Another option is to omit TabsCriteria if you are replacing across all tabs.
    {
      replaceAllText: {
        containsText: {
          text: '{{date}}',
          matchCase: true,
        },
        replaceText: date,
      },
    },
  ];

  // Make a copy of the template document using the Drive API.
  let copyTitle = 'Merged Document';
  driveService.files.copy({
    fileId: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
    resource: {
      name: copyTitle,
    },
  }, (err, driveResponse) => {
    if (err) return console.log('The Drive API returned an error: ' + err);
    let documentCopyId = driveResponse.data.id;

    google.options({auth: auth});
    google
        .discoverAPI(
            'https://docs.googleapis.com/$discovery/rest?version=v1&key={YOUR_API_KEY}')
        .then(function(docs) {
          docs.documents.batchUpdate(
              {
                documentId: documentCopyId,
                resource: {
                  requests,
                },
              },
              (err, {data}) => {
                if (err) return console.log('The API returned an error: ' + err);
                console.log(data);
              });
        });
  });

Python

customer_name = 'Alice'
date = datetime.datetime.now().strftime("%y/%m/%d")

# Make a copy of the template document using the Drive API.
copy_title = 'Merged Document'
body = {
    'name': copy_title
}
drive_response = drive_service.files().copy(
    fileId=DOCUMENT_ID, body=body).execute()
document_copy_id = drive_response.get('id')

requests = [
        # One option for replacing all text is to specify all tab IDs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{customer-name}}',
                'matchCase':  'true'
            },
            'replaceText': customer_name,
            'tabsCriteria': {
                'tabIds': [TAB_ID_1, TAB_ID_2, TAB_ID_3],
            },
        }},
        # Another option is to omit TabsCriteria if you are replacing across all tabs.
        {
        'replaceAllText': {
            'containsText': {
                'text': '{{date}}',
                'matchCase':  'true'
            },
            'replaceText': str(date),
        }
    }
]

result = service.documents().batchUpdate(
    documentId=document_copy_id, body={'requests': requests}).execute()

डाइनैमिक सूचियों और टेबल को मैनेज करना

स्टैंडर्ड दस्तावेज़ मर्ज करने की सुविधा, ReplaceAllTextRequest का इस्तेमाल करके एक बार इस्तेमाल किए जाने वाले प्लेसहोल्डर (जैसे कि {{customer-name}} या {{date}}) को बदलती है. हालांकि, अगर आपके डेटा में आइटम की डाइनैमिक सूची (जैसे कि इनवॉइस में लाइनें, ऑर्डर किए गए प्रॉडक्ट की सूची या डाइनैमिक टेबल) शामिल है, तो स्टैंडर्ड टेक्स्ट बदलने की सुविधा का इस्तेमाल नहीं किया जा सकता. ऐसा इसलिए, क्योंकि टेंप्लेट डिज़ाइन करते समय आइटम की संख्या के बारे में पता नहीं होता.

डाइनैमिक सूची के कॉन्टेंट को मैनेज करने के लिए, इनमें से किसी एक रणनीति का इस्तेमाल करें.

पहला विकल्प: टेंप्लेट टेबल में पंक्तियां जोड़ना

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

  1. टेंप्लेट का स्ट्रक्चर पढ़ें: टेबल ढूंढने और टेंप्लेट की लाइन का इंडेक्स पता लगाने के लिए, documents.get तरीके का इस्तेमाल करें.
  2. नई लाइनें जोड़ना: अपनी डेटा सूची में मौजूद हर आइटम के लिए (पहले आइटम को छोड़कर, जो मौजूदा टेंप्लेट लाइन का फिर से इस्तेमाल कर सकता है), InsertTableRowRequest को कॉल करें, ताकि टेंप्लेट लाइन के नीचे एक नई लाइन जोड़ी जा सके.
  3. सेल में डेटा डालना: टेंप्लेट की लाइन में मौजूद सेल में डेटा डालने के लिए, प्लेसहोल्डर की जगह पर डेटा डालें. नई बनाई गई लाइनों के लिए, InsertTextRequest का इस्तेमाल करें, ताकि हर सेल की कोऑर्डिनेट लोकेशन में उससे जुड़ा टेक्स्ट डाला जा सके.

टेबल की लाइनें डालने के तरीके के उदाहरणों के लिए, टेबल के साथ काम करना लेख पढ़ें.

दूसरा विकल्प: टैग की जगह जनरेट की गई टेबल का इस्तेमाल करना

अगर आपको प्रोग्राम के हिसाब से टेबल को शुरू से बनाना है, तो:

  1. प्लेसहोल्डर टैग जोड़ें: टेंप्लेट दस्तावेज़ में एक टैग (जैसे कि {{invoice-table}}) का इस्तेमाल करके यह मार्क करें कि सूची कहां दिखनी चाहिए.
  2. प्लेसहोल्डर ढूंढें: खोज की सुविधा का इस्तेमाल करके, टैग का स्टार्ट इंडेक्स ढूंढें.
  3. प्लेसहोल्डर मिटाना: {{invoice-table}} टेक्स्ट हटाने के लिए, DeleteContentRangeRequest का इस्तेमाल करें.
  4. टेबल डालें: उस इंडेक्स से InsertTableRequest भेजें जहां से टेबल शुरू करनी है. साथ ही, अपने डेटा सोर्स के हिसाब से पंक्तियों और कॉलम की संख्या तय करें.
  5. वैल्यू लिखना: हर टेबल सेल में क्रम से वैल्यू भरें.

प्रोग्राम के हिसाब से टेबल डालने के उदाहरणों के लिए, टेबल के साथ काम करना लेख पढ़ें.