Google Workspace ऐड-ऑन की मदद से, ईमेल को ज़्यादा कार्रवाई करने लायक बनाएं

1. खास जानकारी

इस कोडलैब में, Gmail के लिए Google Workspace ऐड-ऑन बनाने के लिए Google Apps Script का इस्तेमाल किया जाएगा. इससे उपयोगकर्ता, ईमेल से रसीद का डेटा सीधे Gmail में मौजूद स्प्रेडशीट में जोड़ सकेंगे. जब किसी उपयोगकर्ता को ईमेल से रसीद मिलती है, तो वह ऐड-ऑन खोलता है. ऐड-ऑन, ईमेल से खर्च की ज़रूरी जानकारी अपने-आप ले लेता है. उपयोगकर्ता, खर्च की जानकारी में बदलाव कर सकता है. इसके बाद, वह इसे Google Sheets स्प्रेडशीट में खर्च की जानकारी को लॉग करने के लिए सबमिट कर सकता है.

आपको क्या सीखने को मिलेगा

Google Apps Script का इस्तेमाल करके, Gmail के लिए Google Workspace ऐड-ऑन बनाना
Google Apps Script की मदद से ईमेल पार्स करना
Google Apps Script के ज़रिए Google Sheets के साथ इंटरैक्ट करना
Google Apps Script की Properties सेवा का इस्तेमाल करके, उपयोगकर्ता की वैल्यू सेव करना

आपको किन चीज़ों की ज़रूरत होगी

इंटरनेट और वेब ब्राउज़र का ऐक्सेस
Google खाता
Gmail में मौजूद कुछ मैसेज, जैसे कि ईमेल की रसीदें

2. सैंपल कोड पाना

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

सैंपल कोड पाने के लिए, कमांड लाइन से यह निर्देश चलाएं:

git clone https://github.com/googleworkspace/gmail-add-on-codelab.git

3. बुनियादी ऐड-ऑन बनाना

सबसे पहले, ऐड-ऑन के आसान वर्शन के लिए कोड लिखें. यह ऐड-ऑन, ईमेल के साथ-साथ खर्च का फ़ॉर्म भी दिखाता है.

सबसे पहले, एक नया Apps Script प्रोजेक्ट बनाएं और उसकी मेनिफ़ेस्ट फ़ाइल खोलें.

script.google.com पर जाएं. यहां से, Apps Script प्रोजेक्ट बनाए, मैनेज किए, और मॉनिटर किए जा सकते हैं.
नया प्रोजेक्ट बनाने के लिए, सबसे ऊपर बाईं ओर, नया प्रोजेक्ट पर क्लिक करें. नया प्रोजेक्ट, Code.gs नाम की डिफ़ॉल्ट फ़ाइल के साथ खुलता है. अभी के लिए Code.gs को छोड़ दें. आपको बाद में इसका इस्तेमाल करना होगा.
बिना टाइटल वाला प्रोजेक्ट पर क्लिक करें. अपने प्रोजेक्ट का नाम खर्च ट्रैकर डालें. इसके बाद, नाम बदलें पर क्लिक करें.
बाईं ओर, प्रोजेक्ट सेटिंग पर क्लिक करें.
"appscript.json" मेनिफ़ेस्ट फ़ाइल को एडिटर में दिखाएं" चेकबॉक्स को चुनें.
एडिटर पर क्लिक करें.
मेनिफ़ेस्ट फ़ाइल खोलने के लिए, बाईं ओर मौजूद appscript.json पर क्लिक करें.

appscript.json में, ऐड-ऑन से जुड़ा मेटाडेटा डालें. जैसे, उसका नाम और उसे किन अनुमतियों की ज़रूरत है. appsscript.json के कॉन्टेंट को इन कॉन्फ़िगरेशन सेटिंग से बदलें:

{
  "timeZone": "GMT",
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.execute"
  ],
  "gmail": {
    "name": "Expense It!",
    "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/receipt_black_24dp.png",
    "contextualTriggers": [{
      "unconditional": {
      },
      "onTriggerFunction": "getContextualAddOn"
    }],
    "primaryColor": "#41f470",
    "secondaryColor": "#94f441"
  }
}

मेनिफ़ेस्ट के contextualTriggers सेक्शन पर खास ध्यान दें. मेनिफ़ेस्ट का यह हिस्सा, उपयोगकर्ता के तय किए गए उस फ़ंक्शन की पहचान करता है जिसे ऐड-ऑन के पहली बार चालू होने पर कॉल किया जाता है. इस मामले में, यह getContextualAddOn को कॉल करता है. इससे खुले हुए ईमेल के बारे में जानकारी मिलती है और उपयोगकर्ता को दिखाने के लिए कार्ड का एक सेट मिलता है.

getContextualAddOn फ़ंक्शन बनाने के लिए, यह तरीका अपनाएं:

बाईं ओर, Code.gs पर कर्सर घुमाएं. इसके बाद, मेन्यू > नाम बदलें पर क्लिक करें.
GetContextualAddOn टाइप करें और Enter बटन दबाएं. Apps Script, आपके फ़ाइल नाम में .gs को अपने-आप जोड़ देता है. इसलिए, आपको फ़ाइल एक्सटेंशन टाइप करने की ज़रूरत नहीं होती. GetContextualAddOn.gs टाइप करने पर, Apps Script आपकी फ़ाइल का नाम GetContextualAddOn.gs.gs रखता है.
GetContextualAddOn.gs में, डिफ़ॉल्ट कोड को getContextualAddOn फ़ंक्शन से बदलें:

/**
 * Returns the contextual add-on data that should be rendered for
 * the current e-mail thread. This function satisfies the requirements of
 * an 'onTriggerFunction' and is specified in the add-on's manifest.
 *
 * @param {Object} event Event containing the message ID and other context.
 * @returns {Card[]}
 */
function getContextualAddOn(event) {
  var card = CardService.newCardBuilder();
  card.setHeader(CardService.newCardHeader().setTitle('Log Your Expense'));

  var section = CardService.newCardSection();
  section.addWidget(CardService.newTextInput()
    .setFieldName('Date')
    .setTitle('Date'));
  section.addWidget(CardService.newTextInput()
    .setFieldName('Amount')
    .setTitle('Amount'));
  section.addWidget(CardService.newTextInput()
    .setFieldName('Description')
    .setTitle('Description'));
  section.addWidget(CardService.newTextInput()
    .setFieldName('Spreadsheet URL')
    .setTitle('Spreadsheet URL'));

  card.addSection(section);

  return [card.build()];
}

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

Expense It! ऐड-ऑन को डिप्लॉय करने से पहले, आपको Google Cloud Platform (GCP) प्रोजेक्ट की ज़रूरत होगी. Apps Script प्रोजेक्ट, इसका इस्तेमाल अनुमतियों, बेहतर सेवाओं, और अन्य जानकारी को मैनेज करने के लिए करते हैं. ज़्यादा जानने के लिए, Google Cloud Platform प्रोजेक्ट पर जाएं.

अपने ऐड-ऑन को डिप्लॉय और चलाने के लिए, यह तरीका अपनाएं:

अपना GCP प्रोजेक्ट खोलें और उसका प्रोजेक्ट नंबर कॉपी करें.
अपने Apps Script प्रोजेक्ट में, बाईं ओर मौजूद प्रोजेक्ट सेटिंग पर क्लिक करें.
"Google Cloud Platform (GCP) प्रोजेक्ट" में जाकर, प्रोजेक्ट बदलें पर क्लिक करें.
अपने GCP प्रोजेक्ट का प्रोजेक्ट नंबर डालें. इसके बाद, प्रोजेक्ट सेट करें पर क्लिक करें.
डिप्लॉय करें > टेस्ट डिप्लॉयमेंट पर क्लिक करें.
पक्का करें कि डिप्लॉयमेंट का टाइप Google Workspace ऐड-ऑन हो. अगर ज़रूरी हो, तो डायलॉग बॉक्स में सबसे ऊपर, डिप्लॉयमेंट टाइप चालू करें पर क्लिक करें. इसके बाद, डिप्लॉयमेंट टाइप के तौर पर Google Workspace ऐड-ऑन चुनें.
ऐप्लिकेशन: Gmail के बगल में मौजूद, इंस्टॉल करें पर क्लिक करें.
हो गया पर क्लिक करें.

अब आपको Gmail के इनबॉक्स में ऐड-ऑन दिखेगा.

अपने कंप्यूटर पर, Gmail खोलें.
दाईं ओर मौजूद साइड पैनल में, Expense It! ऐड-ऑन दिखता है. इसे ढूंढने के लिए, आपको ज़्यादा ऐड-ऑन पर क्लिक करना पड़ सकता है.
कोई ईमेल खोलें. बेहतर होगा कि यह खर्च की जानकारी वाली रसीद हो.
ऐड-ऑन खोलने के लिए, दाईं ओर मौजूद साइड पैनल में, Expense It! पर क्लिक करें .
अपने Google खाते का ऐक्सेस Expense It! को देने के लिए, ऐक्सेस की अनुमति दें पर क्लिक करें और निर्देशों का पालन करें.

इस इमेज में, खुले हुए Gmail मैसेज के साथ एक सामान्य फ़ॉर्म दिख रहा है. फ़िलहाल, यह और कुछ नहीं करता. हालांकि, अगले सेक्शन में इसकी सुविधाओं को बेहतर बनाया जाएगा.

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

4. ईमेल मैसेज ऐक्सेस करना

ऐसा कोड जोड़ें जो ईमेल का कॉन्टेंट फ़ेच करता हो. साथ ही, कोड को थोड़ा और व्यवस्थित करने के लिए उसे मॉड्यूलर बनाएं.

फ़ाइलों के बगल में, जोड़ें > स्क्रिप्ट पर क्लिक करें और Cards नाम की फ़ाइल बनाएं. Helpers नाम की दूसरी स्क्रिप्ट फ़ाइल बनाएं. Cards.gs कार्ड बनाता है और Helpers.gs से मिले फ़ंक्शन का इस्तेमाल करके, ईमेल के कॉन्टेंट के आधार पर फ़ॉर्म में फ़ील्ड भरता है.

Cards.gs में मौजूद डिफ़ॉल्ट कोड को इस कोड से बदलें:

var FIELDNAMES = ['Date', 'Amount', 'Description', 'Spreadsheet URL'];

/**
 * Creates the main card users see with form inputs to log expenses.
 * Form can be prefilled with values.
 *
 * @param {String[]} opt_prefills Default values for each input field.
 * @param {String} opt_status Optional status displayed at top of card.
 * @returns {Card}
 */
function createExpensesCard(opt_prefills, opt_status) {
  var card = CardService.newCardBuilder();
  card.setHeader(CardService.newCardHeader().setTitle('Log Your Expense'));
  
  if (opt_status) {
    if (opt_status.indexOf('Error: ') == 0) {
      opt_status = '<font color=\'#FF0000\'>' + opt_status + '</font>';
    } else {
      opt_status = '<font color=\'#228B22\'>' + opt_status + '</font>';
    }
    var statusSection = CardService.newCardSection();
    statusSection.addWidget(CardService.newTextParagraph()
      .setText('<b>' + opt_status + '</b>'));
    card.addSection(statusSection);
  }
  
  var formSection = createFormSection(CardService.newCardSection(),
                                      FIELDNAMES, opt_prefills);
  card.addSection(formSection);
  
  return card;
}

/**
 * Creates form section to be displayed on card.
 *
 * @param {CardSection} section The card section to which form items are added.
 * @param {String[]} inputNames Names of titles for each input field.
 * @param {String[]} opt_prefills Default values for each input field.
 * @returns {CardSection}
 */
function createFormSection(section, inputNames, opt_prefills) {
  for (var i = 0; i < inputNames.length; i++) {
    var widget = CardService.newTextInput()
      .setFieldName(inputNames[i])
      .setTitle(inputNames[i]);
    if (opt_prefills && opt_prefills[i]) {
      widget.setValue(opt_prefills[i]);
    }
    section.addWidget(widget);
  }
  return section;
}

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

अब Helpers.gs में मौजूद डिफ़ॉल्ट कोड को इस कोड से बदलें:

/**
 * Finds largest dollar amount from email body.
 * Returns null if no dollar amount is found.
 *
 * @param {Message} message An email message.
 * @returns {String}
 */
function getLargestAmount(message) {
  return 'TODO';
}

/**
 * Determines date the email was received.
 *
 * @param {Message} message An email message.
 * @returns {String}
 */
function getReceivedDate(message) {
  return 'TODO';
}

/**
 * Determines expense description by joining sender name and message subject.
 *
 * @param {Message} message An email message.
 * @returns {String}
 */
function getExpenseDescription(message) {
  return 'TODO';
}

/**
 * Determines most recent spreadsheet URL.
 * Returns null if no URL was previously submitted.
 *
 * @returns {String}
 */
function getSheetUrl() {
  return 'TODO';
}

फ़ॉर्म में पहले से भरी गई वैल्यू तय करने के लिए, getContextualAddon, Helpers.gs में मौजूद फ़ंक्शन को कॉल करता है. फ़िलहाल, ये फ़ंक्शन सिर्फ़ "TODO" स्ट्रिंग दिखाएंगे. ऐसा इसलिए, क्योंकि आपको बाद में प्रीफ़िल लॉजिक लागू करना होगा.

इसके बाद, GetContextualAddon.gs में कोड अपडेट करें, ताकि यह Cards.gs और Helpers.gs में मौजूद कोड का इस्तेमाल कर सके. GetContextualAddon.gs में मौजूद कोड की जगह यह कोड डालें:

/**
 * Copyright 2017 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *   https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Returns the contextual add-on data that should be rendered for
 * the current e-mail thread. This function satisfies the requirements of
 * an 'onTriggerFunction' and is specified in the add-on's manifest.
 *
 * @param {Object} event Event containing the message ID and other context.
 * @returns {Card[]}
 */
function getContextualAddOn(event) {
  var message = getCurrentMessage(event);
  var prefills = [getReceivedDate(message),
                  getLargestAmount(message),
                  getExpenseDescription(message),
                  getSheetUrl()];
  var card = createExpensesCard(prefills);

  return [card.build()];
}

/**
 * Retrieves the current message given an action event object.
 * @param {Event} event Action event object
 * @return {Message}
 */
function getCurrentMessage(event) {
  var accessToken = event.messageMetadata.accessToken;
  var messageId = event.messageMetadata.messageId;
  GmailApp.setCurrentMessageAccessToken(accessToken);
  return GmailApp.getMessageById(messageId);
}

नए getCurrentMessage फ़ंक्शन पर ध्यान दें. यह फ़ंक्शन, Gmail से मिले इवेंट का इस्तेमाल करके, उपयोगकर्ता के फ़िलहाल खुले हुए मैसेज को पढ़ता है. इस फ़ंक्शन के काम करने के लिए, स्क्रिप्ट मेनिफ़ेस्ट में एक और स्कोप जोड़ें. इससे Gmail मैसेज को सिर्फ़ पढ़ने का ऐक्सेस मिलता है.

appscript.json में, oauthScopes को अपडेट करें, ताकि वह https://www.googleapis.com/auth/gmail.addons.current.message.readonly स्कोप का अनुरोध भी कर सके.

"oauthScopes": [
  "https://www.googleapis.com/auth/gmail.addons.execute",
   "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
],

Gmail में, अपना ऐड-ऑन चलाएं. साथ ही, Expense It! को ईमेल मैसेज देखने की अनुमति दें. फ़ॉर्म फ़ील्ड में अब "TODO" पहले से भरा हुआ है.

5. Google Sheets के साथ इंटरैक्ट करना

Expense It! ऐड-ऑन में, उपयोगकर्ता के लिए एक फ़ॉर्म होता है. इसमें खर्च की जानकारी डाली जाती है, लेकिन यह जानकारी कहीं नहीं जाती. आइए, एक ऐसा बटन जोड़ते हैं जो फ़ॉर्म के डेटा को Google शीट पर भेजता है.

बटन जोड़ने के लिए, हम ButtonSet क्लास का इस्तेमाल करेंगे. Google Sheets से इंटरफ़ेस करने के लिए, हम Google Sheets सेवा का इस्तेमाल करेंगे.

createFormSection में बदलाव करके, कार्ड के फ़ॉर्म सेक्शन के हिस्से के तौर पर "सबमिट करें" लेबल वाला बटन दिखाएं. यह तरीका अपनाएं:

CardService.newTextButton() का इस्तेमाल करके टेक्स्ट बटन बनाएं. साथ ही, CardService.TextButton.setText() का इस्तेमाल करके बटन को "सबमिट करें" के तौर पर लेबल करें.
बटन को इस तरह से डिज़ाइन करें कि उस पर क्लिक करने पर, CardService.TextButton.setOnClickAction() के ज़रिए यह submitForm कार्रवाई कॉल हो:

/**
 * Logs form inputs into a spreadsheet given by URL from form.
 * Then displays edit card.
 *
 * @param {Event} e An event object containing form inputs and parameters.
 * @returns {Card}
 */
function submitForm(e) {
  var res = e['formInput'];
  try {
    FIELDNAMES.forEach(function(fieldName) {
      if (! res[fieldName]) {
        throw 'incomplete form';
      }
    });
    var sheet = SpreadsheetApp
      .openByUrl((res['Spreadsheet URL']))
      .getActiveSheet();
    sheet.appendRow(objToArray(res, FIELDNAMES.slice(0, FIELDNAMES.length - 1)));
    return createExpensesCard(null, 'Logged expense successfully!').build();
  }
  catch (err) {
    if (err == 'Exception: Invalid argument: url') {
      err = 'Invalid URL';
      res['Spreadsheet URL'] = null;
    }
    return createExpensesCard(objToArray(res, FIELDNAMES), 'Error: ' + err).build();
  }
}

/**
 * Returns an array corresponding to the given object and desired ordering of keys.
 *
 * @param {Object} obj Object whose values will be returned as an array.
 * @param {String[]} keys An array of key names in the desired order.
 * @returns {Object[]}
 */
function objToArray(obj, keys) {
  return keys.map(function(key) {
    return obj[key];
  });
}

CardService.newButtonSet() का इस्तेमाल करके, बटन सेट विजेट बनाएं. इसके बाद, CardService.ButtonSet.addButton() का इस्तेमाल करके, बटन सेट में अपना टेक्स्ट बटन जोड़ें.
CardService.CardSection.addWidget() का इस्तेमाल करके, कार्ड के फ़ॉर्म सेक्शन में बटन सेट विजेट जोड़ें.

कोड की कुछ ही लाइनों में, हम यूआरएल की मदद से स्प्रेडशीट खोल सकते हैं. इसके बाद, उस शीट में डेटा की एक लाइन जोड़ सकते हैं. ध्यान दें कि फ़ॉर्म के इनपुट, इवेंट e के हिस्से के तौर पर फ़ंक्शन में पास किए जाते हैं. साथ ही, हम यह देखते हैं कि उपयोगकर्ता ने सभी फ़ील्ड की जानकारी दी है या नहीं. अगर कोई गड़बड़ी नहीं होती है, तो हम एक खाली खर्च कार्ड बनाते हैं. अगर हमें कोई गड़बड़ी मिलती है, तो हम भरे गए ओरिजनल कार्ड को गड़बड़ी के मैसेज के साथ वापस भेज देते हैं. objToArray हेल्पर फ़ंक्शन की मदद से, फ़ॉर्म के जवाबों को आसानी से ऐरे में बदला जा सकता है. इसके बाद, इसे स्प्रेडशीट में जोड़ा जा सकता है.

आखिर में, appsscript.json में जाकर oauthScopes सेक्शन को अपडेट करें. इसके बाद, स्कोप https://www.googleapis.com/auth/spreadsheets का अनुरोध करें. इस स्कोप की अनुमति मिलने पर, ऐड-ऑन किसी उपयोगकर्ता की Google Sheets को पढ़ सकता है और उनमें बदलाव कर सकता है.

"oauthScopes": [
  "https://www.googleapis.com/auth/gmail.addons.execute",
  "https://www.googleapis.com/auth/gmail.addons.current.message.readonly",
  "https://www.googleapis.com/auth/spreadsheets"
],

अगर आपने अब तक कोई नई स्प्रेडशीट नहीं बनाई है, तो https://docs.google.com/spreadsheets/ पर जाकर एक नई स्प्रेडशीट बनाएं.

अब ऐड-ऑन को फिर से चलाएं और फ़ॉर्म सबमिट करने की कोशिश करें. पक्का करें कि आपने स्प्रेडशीट का यूआरएल फ़ॉर्म फ़ील्ड में, डेस्टिनेशन यूआरएल का पूरा यूआरएल डाला हो.

6. Properties सेवा की मदद से वैल्यू सेव करना

अक्सर उपयोगकर्ता, एक ही स्प्रेडशीट में कई खर्चों को लॉग करते हैं. इसलिए, कार्ड में डिफ़ॉल्ट वैल्यू के तौर पर सबसे हाल ही के स्प्रेडशीट यूआरएल को ऑफ़र करना सुविधाजनक होगा. सबसे नई स्प्रेडशीट के यूआरएल के बारे में जानने के लिए, हमें उस जानकारी को हर बार सेव करना होगा, जब ऐड-ऑन का इस्तेमाल किया जाता है.

Properties service की मदद से, की-वैल्यू पेयर सेव किए जा सकते हैं. इस उदाहरण में, "SPREADSHEET_URL" एक सही कुंजी होगी. वहीं, वैल्यू के तौर पर यूआरएल का इस्तेमाल किया जाएगा. इस तरह की वैल्यू को सेव करने के लिए, आपको Cards.gs में submitForm में बदलाव करना होगा, ताकि शीट में नई लाइन जोड़ने पर स्प्रेडशीट का यूआरएल प्रॉपर्टी के तौर पर सेव हो जाए.

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

स्प्रेडशीट के यूआरएल को सेव करने के लिए, PropertiesService.getUserProperties().setProperty() का इस्तेमाल करें. Cards.gs में submitForm में यह जोड़ें:

PropertiesService.getUserProperties().setProperty('SPREADSHEET_URL', 
    res['Spreadsheet URL']);

इसके बाद, Helpers.gs में मौजूद getSheetUrl फ़ंक्शन में बदलाव करें, ताकि सेव की गई प्रॉपर्टी वापस मिल जाए. इससे उपयोगकर्ता को ऐड-ऑन का इस्तेमाल करते समय, हर बार सबसे नया यूआरएल दिखेगा. प्रॉपर्टी की वैल्यू पाने के लिए, PropertiesService.getUserProperties().getProperty() का इस्तेमाल करें.

/**
 * Determines most recent spreadsheet URL.
 * Returns null if no URL was previously submitted.
 *
 * @returns {String}
 */
function getSheetUrl() {
  return PropertiesService.getUserProperties().getProperty('SPREADSHEET_URL');
}

आखिर में, प्रॉपर्टी सेवा को ऐक्सेस करने के लिए, स्क्रिप्ट को भी अनुमति देनी होगी. अपने ऐड-ऑन को प्रॉपर्टी की जानकारी पढ़ने और लिखने की अनुमति देने के लिए, मेनिफ़ेस्ट में पहले की तरह https://www.googleapis.com/auth/script.storage स्कोप जोड़ें.

7. Gmail मैसेज को पार्स करना

उपयोगकर्ताओं का समय बचाने के लिए, ईमेल में मौजूद खर्च की जानकारी को फ़ॉर्म में पहले से भर देते हैं. हमने Helpers.gs में ऐसे फ़ंक्शन पहले से ही बनाए हैं जो यह काम करते हैं. हालांकि, अब तक हमने खर्च की तारीख, रकम, और ब्यौरे के लिए सिर्फ़ "TODO" दिखाया है.

उदाहरण के लिए, हमें ईमेल मिलने की तारीख मिल सकती है. हम इसका इस्तेमाल, खर्चे की तारीख के लिए डिफ़ॉल्ट वैल्यू के तौर पर कर सकते हैं.

/**
 * Determines date the email was received.
 *
 * @param {Message} message - The message currently open.
 * @returns {String}
 */
function getReceivedDate(message) {
  return message.getDate().toLocaleDateString();
}

बाकी दो फ़ंक्शन लागू करें:

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

अगर आपको कुछ और आइडिया चाहिए, तो GmailMessage के लिए रेफ़रंस दस्तावेज़ देखें. इसके अलावा, कोडलैब की शुरुआत में डाउनलोड किया गया समाधान कोड भी देखा जा सकता है. Helpers.gs में मौजूद सभी फ़ंक्शन के लिए, अपनी ज़रूरत के हिसाब से लागू करने के तरीके तय करने के बाद, अपने ऐड-ऑन को आज़माएं! रसीदें खोलें और उन्हें स्प्रेडशीट में लॉग करना शुरू करें!

8. कार्ड ऐक्शन की मदद से फ़ॉर्म मिटाना

अगर Expense It! किसी खुले हुए ईमेल में मौजूद खर्च की पहचान गलत तरीके से करता है और फ़ॉर्म में गलत जानकारी पहले से भर देता है, तो क्या होगा? उपयोगकर्ता फ़ॉर्म को मिटा देता है. CardAction क्लास की मदद से, हम एक ऐसा फ़ंक्शन तय कर सकते हैं जिसे ऐक्शन पर क्लिक करने पर कॉल किया जाता है. आइए, इसका इस्तेमाल करके उपयोगकर्ता को फ़ॉर्म मिटाने का आसान तरीका उपलब्ध कराएं.

createExpensesCard में इस तरह बदलाव करें कि उससे मिले कार्ड में "फ़ॉर्म मिटाएं" लेबल वाला कार्ड ऐक्शन हो. साथ ही, उस पर क्लिक करने से नीचे दिया गया clearForm फ़ंक्शन कॉल हो. इसे Cards.gs में चिपकाया जा सकता है. आपको कार्रवाई के लिए, "Status" नाम के पैरामीटर के तौर पर opt_status पास करना होगा. इससे यह पक्का किया जा सकेगा कि फ़ॉर्म खाली होने पर भी स्टेटस मैसेज बना रहे. ध्यान रखें कि कार्रवाइयों के लिए वैकल्पिक पैरामीटर, Object.<string, string> टाइप के होने चाहिए. इसलिए, अगर opt_status उपलब्ध नहीं है, तो आपको {'Status' : ''} पास करना चाहिए.

/**
 * Recreates the main card without prefilled data.
 *
 * @param {Event} e An event object containing form inputs and parameters.
 * @returns {Card}
 */
function clearForm(e) {
  return createExpensesCard(null, e['parameters']['Status']).build();
}

9. स्प्रेडशीट बनाएं

मौजूदा स्प्रेडशीट में बदलाव करने के लिए, Google Apps Script का इस्तेमाल करने के अलावा, प्रोग्राम के हिसाब से पूरी तरह से नई स्प्रेडशीट बनाई जा सकती है. हमारे ऐड-ऑन के लिए, उपयोगकर्ता को खर्चों की स्प्रेडशीट बनाने की अनुमति दें. शुरू करने के लिए, createExpensesCard से मिले कार्ड में कार्ड का यह सेक्शन जोड़ें.

var newSheetSection = CardService.newCardSection();
var sheetName = CardService.newTextInput()
  .setFieldName('Sheet Name')
  .setTitle('Sheet Name');
var createExpensesSheet = CardService.newAction()
  .setFunctionName('createExpensesSheet');
var newSheetButton = CardService.newTextButton()
  .setText('New Sheet')
  .setOnClickAction(createExpensesSheet);
newSheetSection.addWidget(sheetName);
newSheetSection.addWidget(CardService.newButtonSet().addButton(newSheetButton));
card.addSection(newSheetSection);

अब जब उपयोगकर्ता "नई शीट" बटन पर क्लिक करता है, तो ऐड-ऑन एक नई स्प्रेडशीट जनरेट करता है. इसमें हेडर वाली पंक्ति फ़्रीज़ की गई होती है, ताकि वह हमेशा दिखे. उपयोगकर्ता, फ़ॉर्म में नई स्प्रेडशीट के लिए टाइटल तय करता है. हालांकि, अगर फ़ॉर्म खाली है, तो डिफ़ॉल्ट वैल्यू शामिल करना एक अच्छा विकल्प हो सकता है. createExpensesSheet को लागू करते समय, मौजूदा कार्ड जैसा ही कार्ड दिखाएं. साथ ही, उसमें स्थिति के बारे में सही मैसेज जोड़ें. इसके अलावा, यूआरएल फ़ील्ड में नई स्प्रेडशीट का यूआरएल पहले से भर दें.

10. बधाई हो!

आपने Gmail ऐड-ऑन को डिज़ाइन और लागू किया है. यह ऐड-ऑन, ईमेल में खर्च की जानकारी ढूंढता है. साथ ही, उपयोगकर्ताओं को कुछ ही सेकंड में स्प्रेडशीट में खर्च की जानकारी लॉग करने में मदद करता है. आपने Google Apps Script का इस्तेमाल करके, कई Google API के साथ इंटरफ़ेस किया हो. साथ ही, ऐड-ऑन के कई बार इस्तेमाल होने पर भी डेटा को सेव किया हो.

बेहतर बनाने के लिए सुझाव

Expense It! को बेहतर बनाने के लिए, अपनी कल्पना का इस्तेमाल करें. हालांकि, इसे और भी ज़्यादा काम का प्रॉडक्ट बनाने के लिए, यहां कुछ सुझाव दिए गए हैं:

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