এডিটর অ্যাড-অনগুলির জন্য ট্রিগার

Apps স্ক্রিপ্ট ট্রিগার একটি নির্দিষ্ট স্ক্রিপ্ট ফাংশন ( ট্রিগার ফাংশন ) সঞ্চালনের কারণ যখনই একটি নির্দিষ্ট ঘটনা ঘটে। শুধুমাত্র নির্দিষ্ট কিছু ইভেন্টের কারণে ট্রিগার ফায়ার হতে পারে এবং প্রতিটি Google Workspace অ্যাপ্লিকেশন ইভেন্টের আলাদা সেট সমর্থন করে।

যখন একটি ট্রিগার ফায়ার হয়, একটি ইভেন্ট অবজেক্ট তৈরি হয়। এই JSON কাঠামোতে ঘটে যাওয়া ইভেন্টের বিবরণ রয়েছে। ইভেন্ট অবজেক্ট স্ট্রাকচারের তথ্য ট্রিগার প্রকারের উপর ভিত্তি করে ভিন্নভাবে সংগঠিত হয়।

ইভেন্ট অবজেক্ট তৈরি হয়ে গেলে, অ্যাপস স্ক্রিপ্ট এটিকে ট্রিগার ফাংশনে প্যারামিটার হিসেবে পাস করে। ট্রিগার ফাংশন হল একটি কলব্যাক ফাংশন যা আপনাকে অবশ্যই ইভেন্টে প্রতিক্রিয়া জানাতে উপযুক্ত পদক্ষেপ নিতে হবে। উদাহরণস্বরূপ, একটি এডিটর অ্যাড-অনে একটি ডকুমেন্ট খোলা হলে অ্যাড-অন মেনু আইটেম তৈরি করতে একটি ট্রিগার ব্যবহার করা হয়। এই ক্ষেত্রে, আপনি সম্ভবত ইভেন্ট অবজেক্টের ডেটা ব্যবহার করে অ্যাড-অন প্রয়োজনীয় মেনু আইটেমগুলি তৈরি করতে onOpen(e) ট্রিগার ফাংশন প্রয়োগ করেন।

এই পৃষ্ঠাটি সম্পাদক অ্যাড-অন প্রকল্পগুলিতে ট্রিগার ব্যবহার করার নির্দেশিকা প্রদান করে।

এডিটর অ্যাড-অন ট্রিগার প্রকার

আপনি এডিটর অ্যাড-অনগুলিতে অ্যাপস স্ক্রিপ্ট প্রকল্পগুলিতে উপলব্ধ বেশিরভাগ জেনেরিক ট্রিগার প্রকারগুলি ব্যবহার করতে পারেন, যার মধ্যে সহজ ট্রিগার এবং সবচেয়ে ইনস্টলযোগ্য ট্রিগারগুলি রয়েছে৷ উপলব্ধ ট্রিগার ধরনের সঠিক সেট প্রসারিত করা হচ্ছে অ্যাপ্লিকেশন উপর নির্ভর করে.

নিম্নলিখিত সারণীটি সহজ এবং ইনস্টলযোগ্য ট্রিগারগুলির প্রকারগুলি দেখায় যা সম্পাদক অ্যাড-অনগুলি ব্যবহার করতে পারে এবং সংশ্লিষ্ট ইভেন্ট অবজেক্টগুলির লিঙ্কগুলি প্রদান করে:

ঘটনা ইভেন্ট অবজেক্ট সরল ট্রিগার ইনস্টলযোগ্য ট্রিগার
খোলা
একটি সম্পাদক ফাইল খোলা হয়।		 খোলা ইভেন্ট অবজেক্টের ডক্স
ওপেন ইভেন্ট অবজেক্টে ফর্ম
খোলা ইভেন্ট অবজেক্টের উপর পত্রক
খোলা ইভেন্ট অবজেক্টের উপর স্লাইড 		ডক্স
ফর্ম*
চাদর
স্লাইড

function onOpen(e)

 ডক্স
ফর্ম
চাদর
ইনস্টল করুন
অ্যাড-অন ইনস্টল করা আছে।		 onInstall ইভেন্ট অবজেক্ট ডক্স
ফর্ম
চাদর
স্লাইড

function onInstall(e)

সম্পাদনা করুন
স্প্রেডশীট সেল বিষয়বস্তু পরিবর্তন করা হয়েছে.		 ইভেন্ট অবজেক্ট এডিট করুন চাদর

function onEdit(e)

 চাদর
পরিবর্তন
একটি শীটে বিষয়বস্তু সম্পাদনা বা বিন্যাস করা হয়।		 শীট অন ইভেন্ট অবজেক্ট পরিবর্তন করুন চাদর
ফর্ম জমা দিন
একটি Google ফর্ম জমা দেওয়া হয়।		 ফর্ম ফর্ম-জমা ইভেন্ট অবজেক্ট
পত্রক ফর্ম-জমা ইভেন্ট অবজেক্ট 		ফর্ম
চাদর
সময়-চালিত (ঘড়ি)
ট্রিগারটি একটি নির্দিষ্ট সময় বা বিরতিতে ফায়ার করে।		 সময়-চালিত ইভেন্ট অবজেক্ট ডক্স
ফর্ম
চাদর
স্লাইড

* Google ফর্মগুলির জন্য উন্মুক্ত ইভেন্টটি ঘটে না যখন কোনও ব্যবহারকারী প্রতিক্রিয়া জানাতে একটি ফর্ম খোলেন, বরং যখন একজন সম্পাদক ফর্মটি সংশোধন করার জন্য খোলেন৷

অ্যাড-অনগুলিতে সহজ ট্রিগার

সাধারণ ট্রিগারগুলি একটি সংরক্ষিত ফাংশনের নাম ব্যবহার করে, অনুমোদনের প্রয়োজন হয় এমন পরিষেবাগুলি ব্যবহার করতে পারে না এবং স্বয়ংক্রিয়ভাবে ব্যবহারের জন্য সক্ষম হয়৷ কিছু ক্ষেত্রে, একটি সাধারণ ট্রিগার ইভেন্ট পরিবর্তে একটি ইনস্টলযোগ্য ট্রিগার দ্বারা পরিচালনা করা যেতে পারে।

আপনি নিম্নলিখিত সংরক্ষিত নামগুলির মধ্যে একটির সাথে একটি ফাংশন প্রয়োগ করে একটি অ্যাড-অনে একটি সাধারণ ট্রিগার যুক্ত করতে পারেন:

  • onOpen(e) কার্যকর করে যখন একজন ব্যবহারকারী একটি নথি, স্প্রেডশীট বা উপস্থাপনা খোলে। onOpen(e) ও সম্পাদন করতে পারে যখন সম্পাদকে একটি ফর্ম খোলা হয় (কিন্তু ফর্মের প্রতিক্রিয়া দেওয়ার সময় নয়)। ব্যবহারকারীর কাছে প্রশ্নে থাকা ফাইলটি সম্পাদনা করার অনুমতি থাকলেই এটি কার্যকর হয় এবং প্রায়শই মেনু আইটেম তৈরি করতে ব্যবহৃত হয়।
  • একজন ব্যবহারকারী একটি অ্যাড-অন ইনস্টল করলে onInstall(e) কার্যকর হয়। সাধারণত onInstall(e) শুধুমাত্র onOpen(e) কল করতে ব্যবহৃত হয়; এটি নিশ্চিত করে যে ব্যবহারকারীকে পৃষ্ঠাটি রিফ্রেশ করার প্রয়োজন ছাড়াই অ্যাড-অন মেনুগুলি ইনস্টল করার সাথে সাথে উপস্থিত হবে।
  • onEdit(e) কার্যকর করে যখন একজন ব্যবহারকারী একটি স্প্রেডশীটে একটি ঘরের মান পরিবর্তন করে। এই ট্রিগারটি সেল মুভ, ফরম্যাটিং বা অন্যান্য পরিবর্তনের প্রতিক্রিয়ায় ফায়ার করে না যা সেলের মান পরিবর্তন করে না।

বিধিনিষেধ

অ্যাড-অনগুলিতে সাধারণ ট্রিগারগুলি একই বিধিনিষেধের সাপেক্ষে যা অন্যান্য ধরণের Apps স্ক্রিপ্ট প্রকল্পগুলিতে সাধারণ ট্রিগারগুলিকে নিয়ন্ত্রণ করে৷ অ্যাড-অন ডিজাইন করার সময় এই বিধিনিষেধগুলি বিশেষভাবে নোট করুন:

  • একটি ফাইল শুধুমাত্র-পঠন (দেখুন বা মন্তব্য) মোডে খোলা হলে সাধারণ ট্রিগার চালানো হয় না। এই আচরণ আপনার অ্যাড-অন মেনুগুলিকে জনবহুল হতে বাধা দেয়।
  • নির্দিষ্ট পরিস্থিতিতে, এডিটর অ্যাড-অনগুলি তাদের onOpen(e) এবং onEdit(e) সাধারণ ট্রিগারগুলিকে নো-অথরাইজেশন মোডে চালায়। এই মোডটি কিছু অতিরিক্ত জটিলতা উপস্থাপন করে যেমন অ্যাড-অন অনুমোদন মডেলে বর্ণিত হয়েছে।
  • সাধারণ ট্রিগারগুলি পরিষেবাগুলি ব্যবহার করতে পারে না বা অনুমোদনের প্রয়োজন হয় এমন অন্যান্য পদক্ষেপ নিতে পারে না, অ্যাড-অন অনুমোদনের মডেলে বর্ণিত ব্যতীত৷
  • সাধারণ ট্রিগার 30 সেকেন্ডের বেশি চলতে পারে না। একটি সাধারণ ট্রিগার ফাংশনে সম্পন্ন প্রক্রিয়াকরণের পরিমাণ কমানোর জন্য যত্ন নিন।
  • সরল ট্রিগারগুলি Apps স্ক্রিপ্ট ট্রিগার কোটা সীমা সাপেক্ষে৷

অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগার

অ্যাড-অনগুলি অ্যাপস স্ক্রিপ্ট Script পরিষেবার সাথে প্রোগ্রাম্যাটিকভাবে ইনস্টলযোগ্য ট্রিগার তৈরি এবং সংশোধন করতে পারে। অ্যাড-অন ইনস্টলযোগ্য ট্রিগার ম্যানুয়ালি তৈরি করা যাবে না। সাধারণ ট্রিগারগুলির বিপরীতে, ইনস্টলযোগ্য ট্রিগারগুলি এমন পরিষেবাগুলি ব্যবহার করতে পারে যেগুলির অনুমোদন প্রয়োজন৷

অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগারগুলি ব্যবহারকারীর কাছে ত্রুটির ইমেল পাঠায় না যখন তারা ত্রুটির সম্মুখীন হয়, যেহেতু বেশিরভাগ ক্ষেত্রে ব্যবহারকারী সমস্যাটি সমাধান করতে অক্ষম হয়। এই কারণে, যখনই সম্ভব ব্যবহারকারীর পক্ষ থেকে ত্রুটিগুলিকে সুন্দরভাবে পরিচালনা করার জন্য আপনার অ্যাড-অন ডিজাইন করা উচিত।

অ্যাড-অনগুলি নিম্নলিখিত ইনস্টলযোগ্য ট্রিগারগুলি ব্যবহার করতে পারে:

  • ওপেন ইনস্টলেবল ট্রিগারগুলি কার্যকর হয় যখন একজন ব্যবহারকারী একটি নথি, স্প্রেডশীট খোলে বা যখন সম্পাদকে একটি ফর্ম খোলা হয় (কিন্তু ফর্মটিতে প্রতিক্রিয়া জানানোর সময় নয়)।
  • যখন একজন ব্যবহারকারী একটি স্প্রেডশীটে একটি সেল মান পরিবর্তন করে তখন ইনস্টলযোগ্য ট্রিগারগুলি সম্পাদনা করুন ৷ এই ট্রিগারটি ফর্ম্যাটিং বা অন্যান্য পরিবর্তনের প্রতিক্রিয়াতে ফায়ার করে না যা ঘরের মান পরিবর্তন করে না।
  • পরিবর্তন ইনস্টলযোগ্য ট্রিগারগুলি কার্যকর হয় যখন কোনও ব্যবহারকারী স্প্রেডশীটে কোনও পরিবর্তন করে, যার মধ্যে ফর্ম্যাটিং সম্পাদনা এবং স্প্রেডশীটেই পরিবর্তনগুলি (যেমন একটি সারি যোগ করা) সহ।

  • যখন একটি Google ফর্ম প্রতিক্রিয়া জমা দেওয়া হয় তখন ফর্ম-জমা ইনস্টলযোগ্য ট্রিগারগুলি কার্যকর হয়৷

  • সময়-চালিত ট্রিগার (যাকে ঘড়ির ট্রিগারও বলা হয়) একটি নির্দিষ্ট সময়ে বা নিয়মিত সময়ের ব্যবধানে বারবার আগুন লাগে।

ইনস্টলযোগ্য ট্রিগার অনুমোদন করা হচ্ছে

সাধারণত, যদি কোনও বিকাশকারী নতুন পরিষেবাগুলি ব্যবহার করার জন্য একটি অ্যাড-অন আপডেট করে যার জন্য অতিরিক্ত অনুমোদনের প্রয়োজন হয়, ব্যবহারকারীদের পরবর্তী সময়ে অ্যাড-অনটি ব্যবহার করার সময় পুনরায় অনুমোদন করার জন্য অনুরোধ করা হয়।

যাইহোক, যে অ্যাড-অনগুলি ট্রিগার ব্যবহার করে তারা বিশেষ অনুমোদনের চ্যালেঞ্জের সম্মুখীন হয়। একটি অ্যাড-অন কল্পনা করুন যা ফর্ম জমাগুলি নিরীক্ষণ করতে একটি ট্রিগার ব্যবহার করে: একজন ফর্ম নির্মাতা অ্যাড-অনটিকে প্রথমবার ব্যবহার করার অনুমতি দিতে পারেন, তারপরে ফর্মটি পুনরায় না খুলেই কয়েক মাস বা বছরের জন্য চালানোর জন্য ছেড়ে দিতে পারেন৷ অ্যাড-অন ডেভেলপার যদি নতুন পরিষেবাগুলি ব্যবহার করার জন্য অ্যাড-অন আপডেট করে যার জন্য অতিরিক্ত অনুমোদনের প্রয়োজন হয়, ফর্ম নির্মাতা কখনই পুনরায় অনুমোদনের ডায়ালগ দেখতে পাবেন না কারণ তারা কখনও ফর্মটি পুনরায় খোলেননি এবং অ্যাড-অন কাজ করা বন্ধ করবে।

রেগুলার অ্যাপস স্ক্রিপ্ট প্রোজেক্টে ট্রিগারের বিপরীতে, অ্যাড-অনগুলিতে ট্রিগারগুলি আবারও অনুমোদনের প্রয়োজন হলেও ফায়ার হতে থাকে। যাইহোক, স্ক্রিপ্টটি এখনও ব্যর্থ হয় যদি এটি কোডের একটি লাইনে আঘাত করে যার অনুমোদনের প্রয়োজন হয় স্ক্রিপ্টের নেই। এই পরিস্থিতি এড়াতে, ডেভেলপাররা ScriptApp.getAuthorizationInfo() পদ্ধতিটি ব্যবহার করে কোডের কিছু অংশে প্রবেশ করতে পারে যা অ্যাড-অনের প্রকাশিত সংস্করণগুলির মধ্যে পরিবর্তিত হয়েছে।

অনুমোদনের সমস্যা এড়াতে ট্রিগার ফাংশনে ব্যবহার করার জন্য প্রস্তাবিত কাঠামোর একটি উদাহরণ নীচে দেওয়া হল। উদাহরণ ট্রিগার ফাংশন একটি Google পত্রক অ্যাড-অনের মধ্যে একটি ফর্ম-জমা ইভেন্টে প্রতিক্রিয়া জানায় এবং, যদি পুনরায় অনুমোদনের প্রয়োজন হয়, টেমপ্লেটেড HTML ব্যবহার করে অ্যাড-অনের ব্যবহারকারীকে একটি সতর্কতা ইমেল পাঠায়৷

Code.gs

triggers/form/Code.gs
/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.html
<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

বিধিনিষেধ

অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগারগুলি একই বিধিনিষেধের সাপেক্ষে যা অন্যান্য ধরণের Apps স্ক্রিপ্ট প্রকল্পগুলিতে ইনস্টলযোগ্য ট্রিগারগুলিকে নিয়ন্ত্রণ করে৷

এই বিধিনিষেধগুলি ছাড়াও, বিশেষত অ্যাড-অনগুলিতে ইনস্টলযোগ্য ট্রিগারগুলিতে বেশ কয়েকটি বিধিনিষেধ প্রযোজ্য:

  • প্রতিটি অ্যাড-অন প্রতি ব্যবহারকারী, প্রতি নথিতে প্রতিটি প্রকারের শুধুমাত্র একটি ট্রিগার থাকতে পারে। উদাহরণস্বরূপ, একটি প্রদত্ত স্প্রেডশীটে, একটি প্রদত্ত ব্যবহারকারীর শুধুমাত্র একটি সম্পাদনা ট্রিগার থাকতে পারে, যদিও ব্যবহারকারীর একই স্প্রেডশীটে একটি ফর্ম-জমা ট্রিগার বা একটি সময়-চালিত ট্রিগার থাকতে পারে। একই স্প্রেডশীটে অ্যাক্সেস সহ একজন ভিন্ন ব্যবহারকারীর নিজস্ব আলাদা ট্রিগার সেট থাকতে পারে।
  • অ্যাড-অনগুলি শুধুমাত্র সেই ফাইলের জন্য ট্রিগার তৈরি করতে পারে যেখানে অ্যাড-অন ব্যবহার করা হয়। অর্থাৎ, Google Doc A-তে ব্যবহৃত একটি অ্যাড-অন যখন Google Doc B খোলা হয় তখন মনিটর করার জন্য একটি ট্রিগার তৈরি করতে পারে না।
  • সময়-চালিত ট্রিগার প্রতি ঘন্টায় একবারের বেশি ঘন ঘন চলতে পারে না।
  • অ্যাড-অনগুলি স্বয়ংক্রিয়ভাবে ব্যবহারকারীকে একটি ইমেল পাঠায় না যখন একটি ইনস্টলযোগ্য ট্রিগার দ্বারা চালিত কোড একটি ব্যতিক্রম থ্রো করে। এটি বিকাশকারীর উপর নির্ভর করে যে ব্যর্থতার ঘটনাগুলি ভালভাবে পরীক্ষা করা এবং পরিচালনা করা।
  • অ্যাড-অন ট্রিগারগুলি নিম্নলিখিত যেকোনো পরিস্থিতিতে ফায়ারিং বন্ধ করে:
    • অ্যাড-অন ব্যবহারকারী দ্বারা আনইনস্টল করা হলে,
    • যদি অ্যাড-অনটি একটি নথিতে নিষ্ক্রিয় করা থাকে (যদি এটি পুনরায় সক্ষম করা হয়, ট্রিগারটি আবার কার্যকর হয়), অথবা
    • যদি বিকাশকারী অ্যাড-অন প্রকাশ না করে বা অ্যাড-অন স্টোরে একটি ভাঙা সংস্করণ জমা দেয়।
  • অ্যাড-অন ট্রিগার ফাংশনগুলি কার্যকর হয় যতক্ষণ না তারা একটি অননুমোদিত পরিষেবা ব্যবহার করে এমন কোডে পৌঁছায়, যেখানে তারা থামে। অ্যাড-অন প্রকাশিত হলেই এটি সত্য; একটি নিয়মিত অ্যাপস স্ক্রিপ্ট প্রকল্পে একই ট্রিগার বা একটি অপ্রকাশিত অ্যাড-অন স্ক্রিপ্টের কোনো অংশের অনুমোদনের প্রয়োজন হলে তা মোটেও কার্যকর হয় না।
  • ইনস্টলযোগ্য ট্রিগারগুলি Apps স্ক্রিপ্ট ট্রিগার কোটা সীমা সাপেক্ষে৷