단순 트리거

트리거를 사용하면 문서 열기와 같은 특정 이벤트가 발생할 때 Apps Script에서 자동으로 함수를 실행할 수 있습니다. 간단한 트리거는 onOpen(e) 함수와 같이 Apps Script에 내장된 예약된 함수 집합으로, 사용자가 Google Docs, Sheets, Slides 또는 Forms 파일을 열 때 실행됩니다. 설치 가능한 트리거는 간단한 트리거보다 더 많은 기능을 제공하지만 사용하기 전에 활성화해야 합니다. 두 트리거 유형 모두에서 Apps Script는 트리거 함수에 이벤트가 발생한 컨텍스트에 대한 정보가 포함된 이벤트 객체를 전달합니다.

시작하기

간단한 트리거를 사용하려면 다음과 같이 예약된 함수 이름 중 하나를 사용하는 함수를 만들면 됩니다.

  • onOpen(e)는 사용자가 수정 권한이 있는 스프레드시트, 문서, 프레젠테이션 또는 양식을 열 때 실행됩니다.
  • onInstall(e)는 사용자가 Google Docs, Sheets, Slides 또는 Forms 내에서 편집자 부가기능을 설치할 때 실행됩니다.
  • onEdit(e)는 사용자가 스프레드시트의 값을 변경할 때 실행됩니다.
  • onSelectionChange(e)는 사용자가 스프레드시트에서 선택 항목을 변경할 때 실행됩니다.
  • doGet(e)는 사용자가 웹 앱을 방문하거나 프로그램이 웹 앱에 HTTP GET 요청을 보낼 때 실행됩니다.
  • doPost(e)는 프로그램이 웹 앱에 HTTP POST 요청을 전송하면 실행됩니다.

위 함수 이름의 e 매개변수는 함수에 전달되는 이벤트 객체입니다. 객체에는 트리거를 실행한 컨텍스트에 대한 정보가 포함되지만, 이 정보를 사용하는 것은 선택사항입니다.

제한사항

간단한 트리거는 사용자에게 승인을 요청하지 않고 자동으로 실행되므로 다음과 같은 몇 가지 제한사항이 적용됩니다.

  • 스크립트는 Google Sheets, Slides, Docs, Forms 파일에 결합되거나 이러한 애플리케이션 중 하나를 확장하는 부가기능이어야 합니다.
  • 읽기 전용 (보기 또는 댓글 작성) 모드로 파일을 열면 파일이 실행되지 않습니다.
  • 스크립트 실행 및 API 요청으로 인해 트리거가 실행되지 않습니다. 예를 들어 Range.setValue()를 호출하여 셀을 수정해도 스프레드시트의 onEdit 트리거가 실행되지 않습니다.
  • 승인이 필요한 서비스에는 액세스할 수 없습니다. 예를 들어 Gmail 서비스에는 승인이 필요하므로 단순한 트리거로 이메일을 보낼 수 없지만 간단한 트리거는 익명인 언어 서비스를 사용하여 문구를 번역할 수 있습니다.
  • 바인딩된 파일을 수정할 수는 있지만 승인이 필요하므로 다른 파일에는 액세스할 수 없습니다.
  • 보안 관리자는 복잡한 보안 제한사항에 따라 현재 사용자의 ID를 확인하지 못할 수도 있습니다.
  • 30초를 초과하여 실행할 수 없습니다.
  • 상황에 따라 에디터 부가기능은 onOpen(e) 및 onEdit(e) 간단한 트리거를 승인 없음 모드에서 실행하며, 이로 인해 몇 가지 추가 문제가 발생합니다. 자세한 내용은 부가기능 승인 수명 주기 가이드를 참고하세요.
  • 단순 트리거에는 Apps Script 트리거 할당량 한도가 적용됩니다.

이러한 제한은 doGet(e) 또는 doPost(e)에는 적용되지 않습니다.

onOpen(e)

onOpen(e) 트리거는 사용자가 수정 권한이 있는 스프레드시트, 문서, 프레젠테이션 또는 양식을 열 때 자동으로 실행됩니다. (양식에 응답할 때는 트리거가 실행되지 않고 양식을 수정하기 위해 양식을 열 때만 실행됩니다.) onOpen(e)는 Google Sheets, Slides, Docs 또는 Forms에 맞춤 메뉴 항목을 추가하는 데 가장 일반적으로 사용됩니다.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

사용자가 Google Docs, Sheets, Slides, Forms 내에서 편집기 부가기능을 설치하면 onInstall(e) 트리거가 자동으로 실행됩니다. 사용자가 Google Workspace Marketplace 웹사이트에서 부가기능을 설치할 때는 트리거가 실행되지 않습니다. onInstall(e)로 할 수 있는 작업에는 특정 제한사항이 있습니다. 승인에 관해 자세히 알아보세요. onInstall(e)의 가장 일반적인 용도는 단순히 onOpen(e)를 호출하여 맞춤 메뉴를 추가하는 것입니다. 부가기능이 설치되면 파일이 이미 열려 있으므로 파일을 다시 열지 않는 한 onOpen(e)가 자체적으로 실행되지 않습니다.

triggers/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

onEdit(e) 트리거는 사용자가 스프레드시트의 셀 값을 변경할 때 자동으로 실행됩니다. 대부분의 onEdit(e) 트리거는 이벤트 객체의 정보를 사용하여 적절하게 응답합니다. 예를 들어 아래의 onEdit(e) 함수는 마지막으로 수정된 시간을 기록하는 주석을 셀에 설정합니다.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

onSelectionChange(e) 트리거는 사용자가 스프레드시트에서 선택사항을 변경할 때 자동으로 실행됩니다. 이 트리거를 활성화하려면 트리거가 추가된 후 스프레드시트를 열 때마다 스프레드시트를 새로고침해야 합니다.

선택 항목이 짧은 시간 내에 여러 셀 사이를 이동하는 경우 지연 시간을 줄이기 위해 일부 선택 변경 이벤트를 건너뛸 수 있습니다. 예를 들어 2초 이내에 여러 선택이 변경되면 첫 번째와 마지막 선택이 변경될 때만 onSelectionChange(e) 트리거가 활성화됩니다.

아래 예에서 빈 셀을 선택하면 onSelectionChange(e) 함수가 셀의 배경을 빨간색으로 설정합니다.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) 및 doPost(e)

doGet(e) 트리거는 사용자가 웹 앱을 방문하거나 프로그램이 웹 앱에 HTTP GET 요청을 전송할 때 자동으로 실행됩니다. doPost(e)는 프로그램이 웹 앱에 HTTP POST 요청을 보낼 때 실행됩니다. 이러한 트리거는 웹 앱, HTML 서비스, 콘텐츠 서비스 가이드에 자세히 설명되어 있습니다. doGet(e) 및 doPost(e)에는 위에 나열된 제한사항이 적용되지 않습니다.

사용 가능한 트리거 유형

단순 트리거의 제한사항으로 인해 요구사항을 충족하지 못하는 경우 설치 가능한 트리거가 대신 작동할 수 있습니다. 아래 표에는 각 이벤트 유형에 사용할 수 있는 트리거 유형이 요약되어 있습니다. 예를 들어 Google Sheets, Slides, Forms, Docs는 모두 간단한 열기 트리거를 지원하지만 Sheets, Docs, Forms만 설치 가능한 열기 트리거를 지원합니다.

이벤트 간단한 트리거 설치 가능한 트리거
열기
스프레드시트
프레젠테이션
Forms*
Docs

function onOpen(e)
스프레드시트
Forms*
Docs
수정
스프레드시트

function onEdit(e)
스프레드시트
선택 변경
스프레드시트

function onSelectionChange(e)
설치
스프레드시트
프레젠테이션
설문지
문서

function onInstall(e)
변경
스프레드시트
양식 제출
Sheets
Forms
시간 기반 (시계)
스프레드시트
프레젠테이션
설문지
문서
독립형
가져오기
독립형

function doGet(e)
게시물
독립형

function doPost(e)

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