ทริกเกอร์สำหรับส่วนเสริมเครื่องมือแก้ไข

ทริกเกอร์สคริปต์ Apps ทำให้สคริปต์ที่ระบุ (ฟังก์ชันทริกเกอร์) เพื่อเรียกใช้เมื่อใดก็ตามที่เหตุการณ์ที่ระบุ เกิดขึ้น มีเพียงบางเหตุการณ์เท่านั้นที่ทำให้ทริกเกอร์เริ่มทำงาน แอปพลิเคชัน Google Workspace รองรับชุดกิจกรรมที่หลากหลาย

เมื่อทริกเกอร์เริ่มทำงาน ระบบจะสร้างออบเจ็กต์เหตุการณ์ขึ้น โครงสร้าง JSON นี้ มีรายละเอียดเกี่ยวกับเหตุการณ์ที่เกิดขึ้น ข้อมูลในเหตุการณ์ โครงสร้างออบเจ็กต์มีการจัดระเบียบแตกต่างกันไปตามประเภททริกเกอร์

เมื่อสร้างออบเจ็กต์เหตุการณ์แล้ว Apps Script จะส่งออบเจ็กต์ดังกล่าวเป็นพารามิเตอร์ไปยัง ทริกเกอร์ฟังก์ชัน ฟังก์ชันทริกเกอร์เป็นฟังก์ชัน Callback ที่คุณต้อง ดำเนินการด้วยตนเอง ในการดำเนินการใดก็ตามที่เหมาะสมเพื่อตอบสนองต่อ กิจกรรม เช่น ในส่วนเสริมเครื่องมือแก้ไขทริกเกอร์ ใช้เพื่อสร้างรายการในเมนูส่วนเสริมเมื่อเปิดเอกสาร ในกรณีนี้ คุณ ใช้ฟังก์ชันทริกเกอร์ onOpen(e) เพื่อสร้างรายการในเมนูที่ส่วนเสริม อาจต้องใช้ข้อมูลในออบเจ็กต์เหตุการณ์

หน้าเว็บนี้มีหลักเกณฑ์ในการใช้ทริกเกอร์ใน เอดิเตอร์ โปรเจ็กต์เสริม

ประเภททริกเกอร์ส่วนเสริมเครื่องมือแก้ไข

คุณสามารถใช้ประเภททริกเกอร์ทั่วไปส่วนใหญ่ที่ใช้ได้กับโปรเจ็กต์ Apps Script ได้ ในส่วนเสริมของ Editor ซึ่งรวมถึงทริกเกอร์แบบง่าย และทริกเกอร์ที่ติดตั้งได้ส่วนใหญ่ ชุดประเภททริกเกอร์ที่ใช้ได้จะขึ้นอยู่กับแอปพลิเคชันที่ขยาย

หมายเหตุ: ขณะนี้ส่วนเสริมของ Google Workspace ใช้งานไม่ได้ ซึ่งต่างจากส่วนเสริมของ Editor ทริกเกอร์ทั่วไปของ Apps Script หรือทริกเกอร์ที่ติดตั้งได้ แต่จะใช้ทริกเกอร์แทน ออกแบบมาสำหรับส่วนเสริมของ Google Workspace โดยเฉพาะ สำหรับข้อมูลเพิ่มเติม โปรดดู ทริกเกอร์ส่วนเสริมของ Google Workspace

ตารางต่อไปนี้แสดงประเภททริกเกอร์แบบง่ายและติดตั้งได้ ส่วนเสริมเครื่องมือแก้ไขสามารถใช้และให้ลิงก์ไปยังออบเจ็กต์เหตุการณ์ที่สอดคล้องกัน

กิจกรรม	ออบเจ็กต์เหตุการณ์	ทริกเกอร์อย่างง่าย	ทริกเกอร์ที่ติดตั้งได้
เปิด ไฟล์ตัวแก้ไขเปิดขึ้น	เอกสารในออบเจ็กต์กิจกรรมที่เปิดอยู่ ออบเจ็กต์เหตุการณ์ onOpen ของฟอร์ม ออบเจ็กต์เหตุการณ์ onOpen ของชีต สไลด์เปิดออบเจ็กต์เหตุการณ์	เอกสาร แบบฟอร์ม* ชีต สไลด์ function onOpen(e)	เอกสาร ฟอร์ม ชีต
ติดตั้ง ติดตั้งส่วนเสริมแล้ว	ออบเจ็กต์เหตุการณ์ onInstall	เอกสาร ฟอร์ม ชีต สไลด์ function onInstall(e)
แก้ไข มีการเปลี่ยนแปลงเนื้อหาในเซลล์สเปรดชีต	ออบเจ็กต์เหตุการณ์ของชีต onEdit	ชีต function onEdit(e)	ชีต
เปลี่ยน มีการแก้ไขหรือจัดรูปแบบเนื้อหาในชีต	ออบเจ็กต์เหตุการณ์ onChange ของชีต		ชีต
ส่งแบบฟอร์ม ส่งแบบฟอร์มใน Google ฟอร์มแล้ว	ออบเจ็กต์เหตุการณ์การส่งแบบฟอร์มในแบบฟอร์ม ออบเจ็กต์เหตุการณ์การส่งแบบฟอร์มในชีต		ฟอร์ม ชีต
ตามเวลา (นาฬิกา) ทริกเกอร์จะเริ่มทำงานในเวลาหรือช่วงเวลาที่ระบุ	ออบเจ็กต์เหตุการณ์ที่อิงตามเวลา		เอกสาร ฟอร์ม ชีต สไลด์ 24-30

* กิจกรรมที่เปิดอยู่สำหรับ Google ฟอร์มจะไม่เกิดขึ้นเมื่อผู้ใช้เปิด ในการตอบกลับ แต่แทนที่จะเปิดแบบฟอร์มเพื่อแก้ไข

ตัวทริกเกอร์อย่างง่ายในส่วนเสริม

ทริกเกอร์ทั่วไปใช้ชุด ต้องไม่ใช้บริการที่ต้องมีการให้สิทธิ์ และ เพื่อใช้งานโดยอัตโนมัติ ในบางกรณี เหตุการณ์ทริกเกอร์แบบง่ายอาจ จะได้รับการจัดการโดยทริกเกอร์ที่ติดตั้งได้แทน

คุณสามารถเพิ่มทริกเกอร์ง่ายๆ ลงในส่วนเสริมได้ง่ายๆ โดยใช้ฟังก์ชัน ด้วยชื่อที่สงวนไว้ชื่อใดชื่อหนึ่งต่อไปนี้:

• onOpen(e) ทำงานเมื่อผู้ใช้เปิดเอกสาร สเปรดชีต หรือ งานนำเสนอ onOpen(e) ยังสามารถเรียกใช้ได้เมื่อเปิดแบบฟอร์มในเครื่องมือแก้ไข (แต่ไม่ส่งเมื่อตอบแบบฟอร์ม) จะทำงานก็ต่อเมื่อผู้ใช้มี มีสิทธิ์แก้ไขไฟล์ที่เป็นปัญหา และมักจะใช้สร้าง รายการในเมนู
• onInstall(e) จะทำงานเมื่อผู้ใช้ติดตั้งส่วนเสริม ปกติราคา onInstall(e) ใช้เพื่อเรียก onOpen(e) เพื่อให้แน่ใจว่าเมนูส่วนเสริมจะปรากฏขึ้น ทันทีหลังจากติดตั้งโดยที่ผู้ใช้ไม่ต้องรีเฟรชหน้าเว็บ
• onEdit(e) ทำงานเมื่อผู้ใช้เปลี่ยนค่าเซลล์ในสเปรดชีต ทริกเกอร์นี้ไม่เริ่มทำงานเพื่อตอบสนองต่อการย้ายเซลล์ การจัดรูปแบบ หรือ การเปลี่ยนแปลงอื่นๆ ที่ไม่ได้เปลี่ยนค่าของเซลล์

ข้อจำกัด

ทริกเกอร์ทั่วไปในส่วนเสริม ข้อจำกัดที่ควบคุม ในโปรเจ็กต์ Apps Script ประเภทอื่นๆ ให้ความสำคัญกับสิ่งเหล่านี้ ข้อจำกัดในการออกแบบส่วนเสริม:

• ทริกเกอร์ทั่วไปจะไม่ทำงานหากไฟล์ถูกเปิดแบบอ่านอย่างเดียว (ดูหรือ ความคิดเห็น) ซึ่งลักษณะการทำงานนี้จะป้องกันไม่ให้ระบบป้อนข้อมูลเมนูส่วนเสริม
• ในบางกรณี ส่วนเสริมเครื่องมือแก้ไขจะเรียกใช้ onOpen(e) และ onEdit(e) ทริกเกอร์อย่างง่ายในโหมดไม่มีการให้สิทธิ์ โหมดนี้จะนำเสนอ ข้อมูลแทรกเพิ่มเติมอื่นๆ ตามที่ระบุไว้ใน รูปแบบการให้สิทธิ์เสริม
• ทริกเกอร์ทั่วไปไม่สามารถใช้บริการ หรือรับ การดำเนินการอื่นๆ ที่ต้อง การให้สิทธิ์ ยกเว้น ที่ระบุไว้ใน รูปแบบการให้สิทธิ์ส่วนเสริม
• ทริกเกอร์แบบง่ายจะไม่ทำงานนานกว่า 30 วินาที ดำเนินการเพื่อลด ปริมาณการประมวลผลในฟังก์ชันทริกเกอร์แบบง่าย
• ทริกเกอร์ทั่วไปขึ้นอยู่กับทริกเกอร์ Apps Script ขีดจำกัดโควต้า

ทริกเกอร์ที่ติดตั้งได้ในส่วนเสริม

ส่วนเสริมสามารถ สร้างและแก้ไขทริกเกอร์ที่ติดตั้งได้แบบเป็นโปรแกรม กับบริการ Apps Script Script ส่วนเสริม สร้างทริกเกอร์ที่ติดตั้งได้ด้วยตนเองไม่ได้ ซึ่งต่างจากทริกเกอร์ทั่วไป ทริกเกอร์ที่ติดตั้งได้ใช้บริการที่ต้องการการให้สิทธิ์ได้

ทริกเกอร์ที่ติดตั้งได้ในส่วนเสริมจะไม่ส่งอีเมลแสดงข้อผิดพลาด ให้กับผู้ใช้เมื่อพบข้อผิดพลาด เนื่องจากในกรณีส่วนใหญ่ ผู้ใช้ไม่สามารถ เพื่อจัดการกับปัญหา ด้วยเหตุนี้ คุณจึงควรออกแบบส่วนเสริมเพื่อ จัดการข้อผิดพลาดในนามของผู้ใช้อย่างระมัดระวังเมื่อทำได้

ส่วนเสริมสามารถใช้ทริกเกอร์ที่ติดตั้งได้ต่อไปนี้

• ทริกเกอร์เปิดที่ติดตั้งได้จะทำงานเมื่อผู้ใช้เปิดเอกสาร สเปรดชีต หรือเมื่อเปิดแบบฟอร์มในตัวแก้ไข (แต่ไม่ส่งเมื่อตอบ กับแบบฟอร์ม)
• แก้ไขทริกเกอร์ที่ติดตั้งได้จะทำงานเมื่อผู้ใช้เปลี่ยนค่าเซลล์ใน สเปรดชีต ทริกเกอร์นี้ไม่เริ่มทำงานเพื่อตอบสนองต่อการจัดรูปแบบหรืออื่นๆ การเปลี่ยนแปลงที่ไม่เปลี่ยนค่าของเซลล์
• เปลี่ยนทริกเกอร์ที่ติดตั้งได้จะทำงานเมื่อผู้ใช้ทำการเปลี่ยนแปลงใน สเปรดชีต รวมถึงการแก้ไขการจัดรูปแบบและการแก้ไขสเปรดชีต (เช่น การเพิ่มแถว)

• ทริกเกอร์ที่ติดตั้งได้การส่งแบบฟอร์มจะทำงานเมื่อคำตอบของ Google ฟอร์มคือ ส่งแล้ว

  หมายเหตุ: ทริกเกอร์การส่งแบบฟอร์มมี 2 เวอร์ชัน เวอร์ชันสําหรับชีต (ซึ่งเก็บรวบรวมคำตอบของแบบฟอร์ม) และอีกแบบฟอร์มสำหรับ Google ฟอร์ม ออบเจ็กต์เหตุการณ์ที่ส่งไปยังฟังก์ชันทริกเกอร์การส่งแบบฟอร์มของชีต จะง่ายกว่าและแสดงผลค่าการตอบสนองในอาร์เรย์แบบง่าย ออบเจ็กต์เหตุการณ์ที่ส่งไปยังฟังก์ชันทริกเกอร์การส่งแบบฟอร์ม ให้ข้อมูลเพิ่มเติมซึ่งอยู่ใน FormResponse

• ทริกเกอร์ที่ขึ้นอยู่กับเวลา (หรือที่เรียกว่าทริกเกอร์นาฬิกา) เริ่มทำงานในเวลาที่เจาะจงหรือซ้ำๆ บน ช่วงเวลาปกติ

การให้สิทธิ์ทริกเกอร์ที่ติดตั้งได้

โดยปกติแล้ว หากนักพัฒนาซอฟต์แวร์อัปเดตส่วนเสริมเพื่อใช้บริการใหม่ที่กำหนด การให้สิทธิ์เพิ่มเติม ระบบจะแจ้งให้ผู้ใช้ให้สิทธิ์ส่วนเสริมอีกครั้ง เวลาที่ใช้ไป

อย่างไรก็ตาม ส่วนเสริมที่ใช้ทริกเกอร์ประสบปัญหาเกี่ยวกับการให้สิทธิ์แบบพิเศษ ลองนึกภาพส่วนเสริมที่ใช้ทริกเกอร์เพื่อตรวจสอบการส่งแบบฟอร์ม นั่นคือ แบบฟอร์ม อาจให้สิทธิ์ส่วนเสริมในครั้งแรกที่ใช้ จะทำงานเป็นเวลาหลายเดือนหรือหลายปีโดยไม่ต้องเปิดแบบฟอร์มอีกครั้ง กรณีที่นักพัฒนาส่วนเสริมต้องอัปเดตส่วนเสริมเพื่อใช้บริการใหม่ที่ ต้องได้รับสิทธิ์เพิ่มเติม ผู้สร้างแบบฟอร์มจะไม่เห็น กล่องโต้ตอบการให้สิทธิ์ซ้ำเนื่องจากไม่เคยเปิดแบบฟอร์มและส่วนเสริมอีกครั้ง จะหยุดทำงาน

ซึ่งจะแตกต่างจากทริกเกอร์ในโปรเจ็กต์ Apps Script ทั่วไป คือทริกเกอร์ใน ส่วนเสริมจะยังคงเริ่มทำงานได้แม้ว่าจะต้องมีการให้สิทธิ์อีกครั้ง อย่างไรก็ตาม สคริปต์ ยังคงล้มเหลวหากตกบรรทัดของโค้ดที่ต้องมีการให้สิทธิ์สคริปต์ ไม่มี เพื่อหลีกเลี่ยงสถานการณ์นี้ นักพัฒนาแอปสามารถใช้เมธอด ScriptApp.getAuthorizationInfo() เพื่อเข้าถึงส่วนต่างๆ ของโค้ด ที่มีการเปลี่ยนแปลงระหว่างเวอร์ชันที่เผยแพร่ของ ส่วนเสริม

ด้านล่างคือตัวอย่างของโครงสร้างที่แนะนำเพื่อใช้ในฟังก์ชันทริกเกอร์ เพื่อหลีกเลี่ยงข้อผิดพลาดในการให้สิทธิ์ ตัวอย่างฟังก์ชันทริกเกอร์ตอบสนองต่อ กิจกรรมการส่งแบบฟอร์มภายในส่วนเสริมของ Google ชีต และหากการให้สิทธิ์อีกครั้ง ส่งอีเมลแจ้งเตือนไปยังผู้ใช้ส่วนเสริมโดยใช้ HTML ที่เป็นเทมเพลต

Code.gs

triggers/form/Code.gs

ดูใน GitHub

/**
 * 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

ดูใน GitHub

<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 Script ประเภทอื่นๆ

นอกจากข้อจํากัดเหล่านี้แล้ว ยังมีข้อจำกัดหลายอย่างที่มีผลกับการติดตั้ง ทริกเกอร์ในส่วนเสริมโดยเฉพาะ

• ส่วนเสริมแต่ละรายการมีทริกเกอร์แต่ละประเภทได้เพียงรายการเดียวต่อผู้ใช้ต่อเอกสาร 1 รายการ เช่น ในสเปรดชีตหนึ่งๆ ผู้ใช้ที่กำหนดจะแก้ไขได้เพียงรายการเดียวเท่านั้น แม้ว่าผู้ใช้จะมีทริกเกอร์การส่งแบบฟอร์มหรือทริกเกอร์ ที่ขึ้นกับเวลาในสเปรดชีตเดียวกัน ผู้ใช้รายอื่นที่มีสิทธิ์เข้าถึง ให้สเปรดชีตเดียวกันอาจมีชุดทริกเกอร์ของตัวเองแยกต่างหาก
• ส่วนเสริมสามารถสร้างทริกเกอร์สำหรับไฟล์ที่ใช้ส่วนเสริมเท่านั้น กล่าวคือ ส่วนเสริมที่ใช้ใน Google เอกสาร ก จะสร้างทริกเกอร์เพื่อ เมื่อมีการเปิด Google เอกสาร B
• ทริกเกอร์ที่ขึ้นอยู่กับเวลาไม่สามารถทำงานบ่อยกว่า 1 ครั้งต่อชั่วโมง
• ส่วนเสริมจะไม่ส่งอีเมลถึงผู้ใช้โดยอัตโนมัติเมื่อมีการเรียกใช้โค้ดโดย ทริกเกอร์ที่ติดตั้งได้มีข้อยกเว้น นักพัฒนาแอปจะเป็นผู้ตรวจสอบ สำหรับและจัดการกรณีที่ล้มเหลวได้อย่างดี
• ทริกเกอร์ส่วนเสริมจะหยุดทำงานในสถานการณ์ต่อไปนี้
  • หากผู้ใช้ถอนการติดตั้งส่วนเสริม
  • หากปิดใช้ส่วนเสริมในเอกสาร (หากเปิดใช้อีกครั้ง ทริกเกอร์) กลับมาแสดงอีกครั้ง) หรือ
  • หากนักพัฒนาแอปยกเลิกการเผยแพร่ส่วนเสริมหรือส่งเวอร์ชันที่ใช้งานไม่ได้ไปยัง ร้านค้าส่วนเสริม
• ฟังก์ชันทริกเกอร์ส่วนเสริมจะทำงานจนกว่าจะไปถึงโค้ดที่ใช้ บริการที่ไม่ได้รับอนุญาตซึ่งจะหยุดทำงาน ซึ่งจะเป็นจริงก็ต่อเมื่อ นำส่วนเสริมไปใช้จริงแล้ว ทริกเกอร์เดียวกันในโครงการ Apps Script ปกติหรือ ส่วนเสริมที่ไม่ได้เผยแพร่จะไม่ทำงานเลยหากมีบางส่วนของสคริปต์ที่ต้องการ การกันวงเงิน
• ทริกเกอร์ที่ติดตั้งได้จะขึ้นอยู่กับทริกเกอร์ Apps Script ขีดจำกัดโควต้า