편집기 부가기능 트리거

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

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

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

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

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

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

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

이벤트	이벤트 객체	간단한 트리거	설치 가능한 트리거
열기 편집기 파일이 열립니다.	Docs onOpen 이벤트 객체 Forms onOpen 이벤트 객체 Sheets onOpen 이벤트 객체 Slides onOpen 이벤트 객체	Docs Forms* Sheets Slides function onOpen(e)	Docs Forms Sheets
설치 부가기능이 설치됩니다.	onInstall 이벤트 객체	Docs Forms Sheets Slides function onInstall(e)
수정 스프레드시트 셀 콘텐츠가 변경됩니다.	Sheets onEdit 이벤트 객체	Sheets function onEdit(e)	Sheets
변경 시트의 콘텐츠가 수정되거나 서식이 지정됩니다.	Sheets onChange 이벤트 객체		Sheets
Form-submit Google 양식이 제출되었습니다.	Forms 양식 제출 이벤트 객체 Sheets 양식 제출 이벤트 객체		Forms Sheets
시간 기반 (시계) 지정된 시간 또는 간격에 트리거가 실행됩니다.	시간 기반 이벤트 객체		Docs Forms Sheets Slides

* Google Forms의 열기 이벤트는 사용자가 응답하기 위해 양식을 열 때가 아니라 수정 권한이 있는 사용자가 양식을 열 때 발생합니다.

부가기능의 간단한 트리거

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

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

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

제한사항

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

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

부가기능의 설치 가능한 트리거

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

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

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

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

• 설치 가능한 트리거인 Form-submit은 Google Forms 응답이 제출될 때 실행됩니다.

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

설치 가능한 트리거 승인

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

하지만 트리거를 사용하는 부가기능에는 특별한 승인 문제가 있습니다. 트리거를 사용하여 양식 제출을 모니터링하는 부가기능을 예로 들어 보겠습니다. 양식 작성자가 부가기능을 처음 사용할 때 승인한 후 양식을 다시 열지 않고 몇 개월 또는 몇 년 동안 실행하도록 놔둘 수 있습니다. 부가기능 개발자가 추가 승인이 필요한 새 서비스를 사용하도록 부가기능을 업데이트하면 양식 작성자가 양식을 다시 열지 않았으므로 재승인 대화상자가 표시되지 않고 부가기능이 작동하지 않게 됩니다.

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

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

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

<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가 열릴 때 모니터링할 트리거를 만들 수 없습니다.
• 시간 기반 트리거는 시간당 한 번 이상 실행할 수 없습니다.
• 설치 가능한 트리거에 의해 실행되는 코드에서 예외가 발생하면 부가기능이 사용자에게 자동으로 이메일을 보내지 않습니다. 개발자가 실패 사례를 확인하고 적절하게 처리해야 합니다.
• 다음과 같은 경우 부가기능 트리거가 실행되지 않습니다.
  • 사용자가 부가기능을 제거한 경우
  • 문서에서 부가기능이 사용 중지된 경우 (다시 사용 설정하면 트리거가 다시 작동함)
  • 개발자가 부가기능을 게시 취소하거나 부가기능 스토어에 손상된 버전을 제출하는 경우
• 부가기능 트리거 함수는 승인되지 않은 서비스를 사용하는 코드에 도달할 때까지 실행되며, 이 시점에서 중지됩니다. 이는 부가기능이 게시된 경우에만 해당합니다. 일반 Apps Script 프로젝트 또는 게시되지 않은 부가기능의 동일한 트리거는 스크립트의 일부에 승인이 필요한 경우 전혀 실행되지 않습니다.
• 설치 가능한 트리거에는 Apps Script 트리거 할당량 제한이 적용됩니다.