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

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

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

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

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

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

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

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

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

function onOpen(e)

 เอกสาร
แบบฟอร์ม
ชีต
ติดตั้ง
ติดตั้งส่วนเสริมแล้ว		 ออบเจ็กต์เหตุการณ์ onInstall เอกสาร
แบบฟอร์ม
ชีต
สไลด์

function onInstall(e)
แก้ไข
มีการเปลี่ยนแปลงเนื้อหาเซลล์สเปรดชีต		 ออบเจ็กต์เหตุการณ์ onEdit ของชีต ชีต

function onEdit(e)

 ชีต
การเปลี่ยนแปลง
มีการแก้ไขหรือจัดรูปแบบเนื้อหาในชีต		 ออบเจ็กต์เหตุการณ์ onChange ของชีต ชีต
Form-submit
ส่ง 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 แต่คุณไม่สามารถสร้างทริกเกอร์ที่ติดตั้งได้ของส่วนเสริมด้วยตนเอง ต่างจากทริกเกอร์แบบง่ายตรงที่ทริกเกอร์ที่ติดตั้งได้จะใช้บริการที่ต้องให้สิทธิ์ได้

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

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

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

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

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

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

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

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

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

ด้านล่างนี้คือตัวอย่างโครงสร้างที่แนะนําให้ใช้ในฟังก์ชันทริกเกอร์เพื่อหลีกเลี่ยงข้อผิดพลาดในการให้สิทธิ์ ฟังก์ชันทริกเกอร์ตัวอย่างจะตอบสนองต่อเหตุการณ์ form-submit ภายในส่วนเสริมของ 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 Script ประเภทอื่นๆ

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

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