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

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/documentId/edit

उदाहरण

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

इस मर्ज को पूरा करने के लिए, यहां दिए गए कोड का इस्तेमाल किया जा सकता है.

Java

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

List<Request> 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(documentId, 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,
      },
    },
  ];

  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: '1yBx6HSnu_gbV2sk1nChJOFo_g3AizBhr-PpkyKAwcTg',
              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")

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_id, body={'requests': requests}).execute()

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

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

टेंप्लेट से दस्तावेज़ों के इंस्टेंस बनाते समय, हमेशा एंड-यूज़र क्रेडेंशियल का इस्तेमाल करें. इससे उपयोगकर्ताओं को, जनरेट किए गए दस्तावेज़ का पूरा कंट्रोल मिलता है. साथ ही, 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 का इस्तेमाल करके वैल्यू बदलें.