편집자 부가기능 트리거

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

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

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

이 페이지에서는 편집자 살펴보겠습니다

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

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

참고: 편집자 부가기능과 달리 Google Workspace 부가기능은 현재 일반 Apps Script 단순 트리거 또는 설치 가능한 트리거. 대신 이러한 유형의 트리거와 Google Workspace 부가기능을 위해 특별히 설계된 도구입니다 자세한 내용은 Google Workspace 부가기능 트리거

다음 표는 일반적인 트리거로 이뤄진 간단한 트리거와 설치 가능한 트리거의 편집기 부가기능에서 사용할 수 있으며 해당 이벤트 객체에 대한 링크를 제공합니다.

이벤트	이벤트 객체	단순 트리거	설치 가능한 트리거
열기 편집기 파일이 열립니다.	<ph type="x-smartling-placeholder"></ph> Docs onOpen 이벤트 객체 <ph type="x-smartling-placeholder"></ph> Forms onOpen 이벤트 객체 Sheets onOpen 이벤트 객체 Slides onOpen 이벤트 객체	문서 <ph type="x-smartling-placeholder"></ph> 양식* 스프레드시트 슬라이드 function onOpen(e)	문서 <ph type="x-smartling-placeholder"></ph> 양식 스프레드시트
설치 부가기능이 설치되었습니다.	<ph type="x-smartling-placeholder"></ph> onInstall 이벤트 객체	문서 <ph type="x-smartling-placeholder"></ph> 양식 스프레드시트 슬라이드 function onInstall(e)
수정 스프레드시트 셀 내용이 변경되었습니다.	<ph type="x-smartling-placeholder"></ph> Sheets onEdit 이벤트 객체	스프레드시트 function onEdit(e)	스프레드시트
변경 시트의 콘텐츠를 수정하거나 서식을 지정합니다.	<ph type="x-smartling-placeholder"></ph> Sheets onChange 이벤트 객체		스프레드시트
양식 제출 Google 양식이 제출되었습니다.	<ph type="x-smartling-placeholder"></ph> 양식 양식 제출 이벤트 객체 <ph type="x-smartling-placeholder"></ph> Sheets 양식 제출 이벤트 객체		양식 <ph type="x-smartling-placeholder"></ph> 스프레드시트
시간 기준 (시계) 트리거는 지정된 시간 또는 간격으로 실행됩니다.	<ph type="x-smartling-placeholder"></ph> 시간 기반 이벤트 객체		문서 <ph type="x-smartling-placeholder"></ph> 양식 스프레드시트 슬라이드

* 사용자가 응답하기가 아니라 편집자가 양식을 열어 수정할 때 응답해야 합니다.

부가기능의 간단한 트리거

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

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

• 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 양식 응답이 있습니다.

  참고: 양식 제출 트리거에는 두 가지 버전이 있습니다. 하나는 Sheets용입니다. (양식 응답이 수집되는 위치) 및 Google Forms에 대한 응답입니다. 이 Sheets 양식 제출 트리거 함수에 전달된 이벤트 객체 가 더 간단하며 간단한 배열로 응답 값을 반환합니다. 이 Forms 양식 제출 트리거 함수에 전달된 이벤트 객체 자세한 내용은 FormResponse 객체

• 시간 기반 트리거 특정 시간에 또는 주기적으로 반복 실행되는 정규 시간 간격입니다.

설치 가능한 트리거 승인

일반적으로 개발자가 부가기능이 필요한 새 서비스를 사용하기 위해 부가기능을 업데이트하는 경우 추가 승인을 받으면 다음 단계에서 부가기능을 재승인하라는 메시지가 표시됩니다. 시간을 절약할 수 있습니다.

그러나 트리거를 사용하는 부가기능에는 특별한 승인 문제가 발생합니다. 트리거를 사용하여 양식 제출을 모니터링하는 크리에이터가 해당 부가기능을 처음 사용할 때 승인할 수 있으며, 승인은 양식을 다시 열지 않고도 몇 개월 또는 몇 년 동안 실행할 수 있습니다. 부가기능 개발자가 추가 승인이 필요한 경우 양식 작성자에게 사용자가 양식을 다시 연 적이 없기 때문에 재승인 대화상자가 표시되며 작동이 멈출 것입니다

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

다음은 트리거 함수에서 사용하도록 권장하는 구조의 예입니다. 피해야 할 실수를 피할 수 있습니다. 예시 트리거 함수는 Google Sheets 부가기능 내 양식 제출 이벤트 및 재승인이 필요한 경우 부가기능 사용자에게 템플릿 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 프로젝트에서 설치 가능한 트리거를 제어하는

이러한 제한사항 외에도 설치 가능한 SDK에는 몇 가지 제한사항이 특히 다음과 같은 트리거가 있습니다.

• 각 부가기능에는 사용자 및 문서별로 유형별 트리거가 하나만 있을 수 있습니다. 예를 들어 특정 스프레드시트에서 특정 사용자는 하나의 수정 권한만 가질 수 있습니다. 사용자에게 양식 제출 트리거나 시간 기반 트리거를 생성하는 것입니다. 액세스 권한이 있는 다른 사용자 자체적인 별도의 트리거 집합을 가질 수 있습니다.
• 부가기능은 부가기능이 사용된 파일에 대한 트리거만 만들 수 있습니다. 즉, Google 문서 A에서 사용되는 부가기능은 Google 문서 B가 열릴 때 모니터링됩니다.
• 시간 기반 트리거는 시간당 한 번을 초과하여 실행할 수 없습니다.
• 부가기능에서 코드를 실행할 때 사용자에게 이메일을 자동으로 전송하지는 않습니다. 설치 가능한 트리거에서 예외가 발생합니다. 개발자가 확인해야 합니다. 실패 사례를 매끄럽게 처리할 수 있습니다
• 부가기능 트리거는 다음과 같은 상황에서 실행 중지됩니다. <ph type="x-smartling-placeholder">
  </ph>
  • 사용자가 부가기능을 제거한 경우
  • 문서에서 부가기능이 사용 중지된 경우 (다시 사용 설정하면 해당 부가기능이 다시 운영될 수 있음)
  • 개발자가 부가기능의 게시를 취소하거나 오류가 있는 버전을 추가할 수 있습니다.
• 부가기능 트리거 함수는 자동으로 중지될 수 있습니다. 이는 부가기능이 게시되면 일반 Apps Script 프로젝트에서 동일한 트리거 또는 게시되지 않은 부가기능은 스크립트의 일부분에 있습니다.
• 설치 가능한 트리거에는 Apps Script 트리거가 적용됨 할당량 한도를 관리할 수 있습니다.