편집기 부가기능 트리거

Apps Script 트리거는 지정된 이벤트가 발생할 때마다 지정된 스크립트 함수 (트리거 함수)를 실행합니다. 특정 이벤트만 트리거를 실행할 수 있으며, 각 Google Workspace 애플리케이션은 서로 다른 이벤트 집합을 지원합니다.

트리거가 실행되면 이벤트 객체가 생성됩니다. 이 JSON 구조에는 발생한 이벤트에 대한 세부정보가 포함됩니다. 이벤트 객체 구조의 정보는 트리거 유형에 따라 다르게 구성됩니다.

이벤트 객체가 생성되면 Apps Script에서 이를 매개변수로 트리거 함수에 전달합니다. 트리거 함수는 이벤트에 응답하는 데 적절한 작업을 수행하기 위해 직접 구현해야 하는 콜백 함수입니다. 예를 들어 편집기 부가기능에서 트리거는 문서가 열릴 때 부가기능 메뉴 항목을 만드는 데 사용됩니다. 이 경우 onOpen(e) 트리거 함수를 구현하여 부가기능에 필요한 메뉴 항목을 만듭니다. 이때 이벤트 객체의 데이터를 사용할 수 있습니다.

이 페이지에서는 편집기 부가기능 프로젝트에서 트리거를 사용하는 방법에 대한 가이드라인을 제공합니다.

편집자 부가기능 트리거 유형

편집기 부가기능에서 단순 트리거 및 대부분의 설치 가능한 트리거를 포함하여 Apps Script 프로젝트에 사용할 수 있는 대부분의 일반 트리거 유형을 사용할 수 있습니다. 사용 가능한 트리거 유형의 정확한 집합은 확장되는 애플리케이션에 따라 다릅니다.

다음 표에는 편집기 부가기능에서 사용할 수 있는 간단한 트리거 및 설치 가능한 트리거 유형과 해당 이벤트 객체로 연결되는 링크가 나와 있습니다.

이벤트 이벤트 객체 간단한 트리거 설치 가능한 트리거
Open
편집기 파일이 열립니다.
Docs onOpen 이벤트 객체
Forms onOpen 이벤트 객체
Sheets onOpen 이벤트 객체
Slides onOpen 이벤트 객체
문서
Forms*
Sheets
프레젠테이션

function onOpen(e)

문서
설문지
스프레드시트
설치
부가기능이 설치됩니다.
onInstall 이벤트 객체 문서
Forms
Sheets
프레젠테이션

function onInstall(e)

수정
스프레드시트의 셀 내용이 변경되었습니다.
Sheets onEdit 이벤트 객체 스프레드시트

function onEdit(e)

스프레드시트
변경
시트의 콘텐츠가 수정되거나 서식이 지정됩니다.
Sheets onChange 이벤트 객체 스프레드시트
양식 제출
Google 양식이 제출됩니다.
Forms 양식 제출 이벤트 객체
Sheets 양식 제출 이벤트 객체
Forms
Sheets
시간 기반 (시계)
트리거가 지정된 시간 또는 간격으로 실행됩니다.
시간 기반 이벤트 객체 문서
Forms
Sheets
프레젠테이션

* Google Forms의 Open 이벤트는 사용자가 응답하기 위해 양식을 열 때 발생하는 것이 아니라, 오히려 편집자가 양식을 수정하기 위해 양식을 열 때 발생합니다.

부가 채널의 간단한 트리거

단순 트리거는 예약된 함수 이름 집합을 사용하고, 승인이 필요한 서비스를 사용할 수 없으며, 자동으로 사용 설정됩니다. 경우에 따라 단순 트리거 이벤트는 설치 가능한 트리거로 대신 처리될 수 있습니다.

다음과 같은 예약된 이름 중 하나로 함수를 구현하여 간단한 트리거를 부가기능에 추가할 수 있습니다.

  • onOpen(e)는 사용자가 문서, 스프레드시트 또는 프레젠테이션을 열 때 실행됩니다. onOpen(e)는 편집기에서 양식이 열릴 때도 실행될 수 있습니다(양식에 응답할 때는 실행되지 않음). 사용자에게 해당 파일을 수정할 수 있는 권한이 있는 경우에만 실행되며 메뉴 항목을 만드는 데 가장 자주 사용됩니다.
  • onInstall(e)는 사용자가 부가기능을 설치할 때 실행됩니다. 일반적으로 onInstall(e)onOpen(e)를 호출하는 데만 사용됩니다. 이렇게 하면 사용자가 페이지를 새로고침하지 않아도 설치 직후에 부가기능 메뉴가 표시됩니다.
  • onEdit(e)는 사용자가 스프레드시트의 셀 값을 변경하면 실행됩니다. 이 트리거는 셀 이동, 서식 또는 셀 값을 변경하지 않는 기타 변경에 대한 응답으로 실행되지 않습니다.

제한사항

부가기능의 단순 트리거에는 다른 종류의 Apps Script 프로젝트의 단순 트리거에 적용되는 것과 동일한 제한사항이 적용됩니다. 부가기능을 설계할 때 이러한 제한사항에 특히 유의하세요.

  • 파일이 읽기 전용 (보기 또는 주석 추가) 모드로 열린 경우 단순 트리거는 실행되지 않습니다. 이 동작으로 인해 부가기능 메뉴가 채워지지 않습니다.
  • 경우에 따라 편집기 부가기능이 승인 없음 모드로 onOpen(e)onEdit(e) 단순 트리거를 실행합니다. 이 모드에는 부가기능 승인 모델에 설명된 대로 몇 가지 추가적인 복잡성이 있습니다.
  • 단순 트리거는 부가기능 승인 모델에 설명된 경우를 제외하고는 서비스를 사용하거나 승인이 필요한 다른 작업을 수행할 수 없습니다.
  • 단순 트리거는 30초 이상 실행할 수 없습니다. 간단한 트리거 함수에서 실행되는 처리량을 최소화해야 합니다.
  • 단순 트리거에는 Apps Script 트리거 할당량 한도가 적용됩니다.

부가기능에서 설치 가능한 트리거

부가기능은 Apps Script Script 서비스를 사용하여 프로그래매틱 방식으로 설치 가능한 트리거를 만들고 수정할 수 있습니다. 부가기능 설치 가능 트리거는 수동으로 만들 수 없습니다. 간단한 트리거와 달리 설치 가능한 트리거는 승인이 필요한 서비스를 사용할 수 있습니다.

부가기능의 설치 가능한 트리거는 오류 발생 시 사용자에게 오류 이메일을 전송하지 않습니다. 대부분의 경우 사용자가 문제를 해결할 수 없기 때문입니다. 따라서 가능하면 사용자를 대신하여 오류를 적절하게 처리하도록 부가기능을 설계해야 합니다.

부가기능은 다음과 같은 설치 가능한 트리거를 사용할 수 있습니다.

  • 설치 가능한 열기 트리거는 사용자가 문서나 스프레드시트를 열거나 편집기에서 양식이 열릴 때 실행됩니다 (양식에 응답할 때는 실행되지 않음).
  • 설치 가능한 트리거 수정은 사용자가 스프레드시트에서 셀 값을 변경할 때 실행됩니다. 이 트리거는 셀 값을 변경하지 않는 형식 지정 또는 기타 변경사항에 대해서는 실행되지 않습니다.
  • Change 설치 가능한 트리거는 사용자가 형식 지정 수정 및 스프레드시트 자체 수정 (예: 행 추가)을 포함하여 스프레드시트를 변경할 때 실행됩니다.
  • Form-submit 설치 가능한 트리거는 Google 양식 응답이 제출될 때 실행됩니다.

  • 시간 기반 트리거(클록 트리거라고도 함)는 특정 시간에 또는 일정한 시간 간격으로 반복적으로 실행됩니다.

설치 가능한 트리거 승인

일반적으로 개발자가 추가 승인이 필요한 새 서비스를 사용하기 위해 부가기능을 업데이트하면 다음에 부가기능을 사용할 때 다시 승인하라는 메시지가 표시됩니다.

하지만 트리거를 사용하는 부가기능에는 특별한 승인 문제가 발생합니다. 트리거를 사용하여 양식 제출을 모니터링하는 부가기능을 생각해 보세요. 양식 작성자가 부가기능을 처음 사용할 때 부가기능을 승인한 다음 양식을 다시 열지 않고 몇 개월 또는 몇 년 동안 실행되도록 허용할 수 있습니다. 부가기능 개발자가 부가기능을 업데이트하여 추가 승인이 필요한 새 서비스를 사용하는 경우 양식 작성자는 양식을 다시 열지 않고 부가기능의 작동이 중지되기 때문에 재승인 대화상자가 표시되지 않습니다.

일반 Apps Script 프로젝트의 트리거와 달리 부가기능의 트리거는 재승인이 필요하더라도 계속 실행됩니다. 하지만 스크립트가 승인을 필요로 하는 코드 줄에 도달하는 경우에는 여전히 실패합니다. 이러한 상황을 방지하기 위해 개발자는 ScriptApp.getAuthorizationInfo() 메서드를 사용하여 게시된 부가기능 버전 사이에 변경된 코드 부분에 대한 액세스를 제어할 수 있습니다.

다음은 승인 문제를 방지하기 위해 트리거 함수에 사용할 때 권장되는 구조의 예입니다. 이 트리거 함수는 Google Sheets 부가기능 내의 양식 제출 이벤트에 응답하고, 재승인이 필요한 경우 부가기능 사용자에게 템플릿 HTML을 사용하여 알림 이메일을 보냅니다.

Code.gs

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

trigger/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 프로젝트에서 설치 가능한 트리거에 적용되는 것과 동일한 제한사항이 적용됩니다.

이러한 제한사항 외에도 특히 부가기능의 설치 가능한 트리거에는 몇 가지 제한사항이 적용됩니다.

  • 각 부가기능에는 사용자 및 문서별로 각 유형의 트리거가 하나만 있을 수 있습니다. 예를 들어 특정 스프레드시트에서 특정 사용자는 하나의 수정 트리거만 가질 수 있지만 사용자는 동일한 스프레드시트에 양식 제출 트리거 또는 시간 기반 트리거를 가질 수 있습니다. 동일한 스프레드시트에 대한 액세스 권한이 있는 다른 사용자는 별도의 자체 트리거 집합을 가질 수 있습니다.
  • 부가기능은 부가기능이 사용되는 파일의 트리거만 만들 수 있습니다. 즉, Google 문서 A에서 사용되는 부가기능은 Google 문서 B가 열리는 시점을 모니터링하는 트리거를 만들 수 없습니다.
  • 시간 기반 트리거는 시간당 1회 이상 실행할 수 없습니다.
  • 부가기능은 설치 가능한 트리거에서 실행되는 코드에서 예외가 발생할 때 사용자에게 자동으로 이메일을 전송하지 않습니다. 실패 사례를 확인하고 적절하게 처리하는 것은 개발자의 책임입니다.
  • 다음과 같은 상황에서 부가기능 트리거가 실행을 중지합니다.
    • 사용자가 부가기능을 제거하면
    • 문서에서 부가기능이 사용 중지된 경우 (다시 사용 설정하면 트리거가 다시 작동함)
    • 개발자가 부가기능을 게시 취소하거나 손상된 버전을 부가기능 스토어에 제출하는 경우
  • 부가기능 트리거 함수는 승인되지 않은 서비스를 사용하는 코드에 도달할 때까지 실행되며, 이 코드에서는 중지됩니다. 이는 부가기능이 게시된 경우에만 해당됩니다. 스크립트에 승인이 필요한 경우에는 일반 Apps Script 프로젝트 또는 게시되지 않은 부가기능의 동일한 트리거가 전혀 실행되지 않습니다.
  • 설치 가능한 트리거에는 Apps Script 트리거 할당량 한도가 적용됩니다.