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

इस गाइड में, 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. प्लेसहोल्डर मिटाना: DeleteContentRangeRequest का इस्तेमाल करके {{invoice-table}} टेक्स्ट हटाएं.
  4. टेबल जोड़ना: उस शुरुआती इंडेक्स पर InsertTableRequest भेजें. इसमें अपने डेटा सोर्स के आधार पर, लाइनों और कॉलम की संख्या तय करें.
  5. वैल्यू लिखना: हर टेबल सेल को क्रम से पॉप्युलेट करें.

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