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

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

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

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

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

ประเภททริกเกอร์ของส่วนเสริมของเอดิเตอร์

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

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

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

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

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

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

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

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

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

ข้อจำกัด

ทริกเกอร์แบบง่ายในส่วนเสริมจะอยู่ภายใต้ข้อจำกัดเดียวกันกับที่ควบคุมทริกเกอร์แบบง่ายในโปรเจ็กต์ Apps Script ประเภทอื่นๆ โปรดคํานึงถึงข้อจํากัดเหล่านี้เป็นพิเศษเมื่อออกแบบส่วนเสริม

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

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

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

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

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

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

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

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

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

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

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

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

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

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