트리거를 사용하면 문서 열기와 같은 특정 이벤트가 발생할 때 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)
는 사용자가 웹 앱을 방문하거나 프로그램이 웹 앱에 HTTPGET
요청을 보낼 때 실행됩니다.doPost(e)
는 프로그램이 웹 앱에 HTTPPOST
요청을 전송하면 실행됩니다.
위 함수 이름의 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에 맞춤 메뉴 항목을 추가하는 데 가장 일반적으로 사용됩니다.
onInstall(e)
사용자가 Google Docs, Sheets, Slides, Forms 내에서 편집기 부가기능을 설치하면 onInstall(e)
트리거가 자동으로 실행됩니다. 사용자가 Google Workspace Marketplace 웹사이트에서 부가기능을 설치할 때는 트리거가 실행되지 않습니다. onInstall(e)
로 할 수 있는 작업에는 특정 제한사항이 있습니다. 승인에 관해 자세히 알아보세요.
onInstall(e)
의 가장 일반적인 용도는 단순히 onOpen(e)
를 호출하여 맞춤 메뉴를 추가하는 것입니다. 부가기능이 설치되면 파일이 이미 열려 있으므로 파일을 다시 열지 않는 한 onOpen(e)
가 자체적으로 실행되지 않습니다.
onEdit(e)
onEdit(e)
트리거는 사용자가 스프레드시트의 셀 값을 변경할 때 자동으로 실행됩니다. 대부분의 onEdit(e)
트리거는 이벤트 객체의 정보를 사용하여 적절하게 응답합니다.
예를 들어 아래의 onEdit(e)
함수는 마지막으로 수정된 시간을 기록하는 주석을 셀에 설정합니다.
onSelectionChange(e)
onSelectionChange(e)
트리거는 사용자가 스프레드시트에서 선택사항을 변경할 때 자동으로 실행됩니다. 이 트리거를 활성화하려면 트리거가 추가된 후 스프레드시트를 열 때마다 스프레드시트를 새로고침해야 합니다.
선택 항목이 짧은 시간 내에 여러 셀 사이를 이동하는 경우 지연 시간을 줄이기 위해 일부 선택 변경 이벤트를 건너뛸 수 있습니다. 예를 들어 2초 이내에 여러 선택이 변경되면 첫 번째와 마지막 선택이 변경될 때만 onSelectionChange(e)
트리거가 활성화됩니다.
아래 예에서 빈 셀을 선택하면 onSelectionChange(e)
함수가 셀의 배경을 빨간색으로 설정합니다.
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만 설치 가능한 열기 트리거를 지원합니다.
이벤트 | 간단한 트리거 | 설치 가능한 트리거 |
---|---|---|
열기 |
|
|
수정 |
|
|
선택 변경 |
|
|
설치 |
|
|
변경 |
|
|
양식 제출 |
|
|
시간 기반 (시계) |
|
|
가져오기 |
|
|
게시물 |
|
* Google Forms의 open 이벤트는 사용자가 응답하기 위해 양식을 열 때가 아니라 편집자가 양식을 수정하기 위해 양식을 열 때 발생합니다.