구글 앱스 스크립트 트리거 설정, 단순 트리거와 설치형 트리거를 나누는 기준

구글 앱스 스크립트 트리거 설정은 함수 이름을 정하고 저장하는 일에서 끝나지 않습니다. 같은 자동 실행이라도 셀을 직접 수정했을 때 반응하는지, Google Forms 응답이 들어올 때 실행되는지, 정해진 시간에 실행되는지, 외부 서비스가 HTTP 요청을 보내는지에 따라 선택할 트리거와 확인할 권한이 달라집니다.

이 글은 Google Workspace 파일을 자동화하려는 1인 사업자와 소규모 팀을 위해 트리거를 고르는 순서를 정리합니다. 단순 트리거와 설치형 트리거를 기능 목록으로만 나열하지 않고, 이벤트 객체, 실행 계정, OAuth 승인, 실행 기록까지 한 흐름으로 확인합니다. Google의 단순 트리거 공식 문서, 설치형 트리거 공식 문서, 이벤트 객체 문서를 기준으로 작성했습니다.

> 먼저 확인할 점: 이 글의 예시는 테스트용 파일과 비민감한 샘플 데이터를 전제로 합니다. 실제 고객 정보, 결제, 메일 발송, 외부 API 호출을 연결할 때는 조직 정책과 OAuth 범위를 별도로 확인해야 합니다. 특정 자동화의 실행 성공이나 업무 결과를 보장하는 글은 아닙니다.

결론: 트리거보다 먼저 이벤트와 실행 계정을 정한다

구글 앱스 스크립트 트리거 설정에서 가장 흔한 실수는 `onEdit(e)`처럼 함수 이름을 먼저 작성하는 것입니다. 먼저 아래 네 가지 질문에 답하면 선택지가 빠르게 줄어듭니다.

예를 들어 상담 폼 응답을 받아 담당자에게 메일을 보내려면 단순 `onEdit`만으로는 부족할 수 있습니다. 응답이 Sheets에 들어오는 시점과 메일 서비스 권한을 함께 봐야 하므로, 설치형 form-submit 트리거와 실행 계정을 먼저 정하는 편이 안전합니다. 반대로 스프레드시트가 열릴 때 맞춤 메뉴를 추가하는 정도라면 단순 `onOpen(e)`가 더 작고 간단한 선택일 수 있습니다.

1. 구글 앱스 스크립트 트리거 설정에서 먼저 나눌 4가지

셀 입력과 API 변경은 같은 이벤트가 아니다

Sheets에서 사용자가 셀에 값을 직접 입력하면 `onEdit(e)`를 검토할 수 있습니다. 그러나 스크립트가 `Range.setValue()`로 값을 바꾸거나 외부 API가 시트를 수정했다고 해서 같은 `onEdit` 흐름이 자동으로 재생되는 것은 아닙니다. 수동 입력을 감지하는 자동화와, 다른 스크립트가 만든 행을 후처리하는 자동화는 입력 경로가 다릅니다.

따라서 테스트 케이스도 둘로 나눠야 합니다.

1. 사람이 테스트 셀에 값을 직접 입력한다. 2. 별도 함수 또는 API로 같은 셀을 변경한다. 3. 두 경우의 실행 기록과 결과 행을 각각 확인한다.

이 구분을 하지 않으면 코드는 정상인데 자동화가 멈췄다고 오해하거나, 반대로 API 입력에서도 이벤트가 발생한다고 가정해 누락을 만들 수 있습니다.

파일에 묶인 코드인지 독립 프로젝트인지 확인한다

단순 트리거는 특정 Google Sheets·Docs·Slides·Forms 파일에 묶인 구조가 전제됩니다. 여러 파일을 읽거나 다른 파일에 기록해야 한다면 인증이 필요한 서비스 접근이 생길 가능성이 높습니다. 그때는 설치형 트리거를 검토하고, 어떤 파일 ID와 어떤 운영 계정이 사용되는지 문서에 남겨야 합니다.

권한이 필요한 서비스인지 확인한다

Gmail로 메일을 보내거나 다른 파일의 Drive 데이터를 읽는 동작은 사용자 승인을 전제로 합니다. Google의 Google 서비스 권한 문서는 코드에서 사용하는 서비스에 따라 OAuth 범위를 확인하고, 새 서비스를 추가하면 추가 승인이 필요할 수 있다고 설명합니다.

권한을 줄이는 방법도 있습니다. 현재 파일에만 접근하면 되는 스크립트라면 `@OnlyCurrentDoc`를 검토할 수 있습니다. 공개 배포나 여러 사용자가 쓰는 스크립트라면 자동으로 넓은 권한을 요청하는 대신 필요한 최소 범위를 먼저 정해야 합니다.

자동 실행의 소유자를 먼저 정한다

설치형 트리거는 버튼을 누른 사람이나 파일을 연 사람의 계정이 아니라, 트리거를 만든 계정의 권한으로 실행됩니다. 개인 계정으로 설치해 놓고 팀 공용 계정이 발송한다고 생각하면, 담당자가 바뀌는 순간 메일 발신자와 Drive 접근 권한이 달라질 수 있습니다.

2. 단순 트리거와 설치형 트리거 차이

단순 트리거는 예약된 함수 이름을 사용해 파일에 바로 붙이는 방식입니다. 설치형 트리거는 편집기의 Triggers 메뉴에서 이벤트와 함수를 선택하거나 `ScriptApp.newTrigger()`로 만들고, 필요한 권한을 승인합니다.

단순 트리거가 항상 더 좋은 선택은 아닙니다. 인증이 필요한 작업을 단순 트리거에 억지로 넣으면 권한 오류가 나고, 설치형 트리거를 여러 계정이 각각 만들면 같은 이벤트가 중복 처리될 수 있습니다. 반대로 모든 셀 입력에 설치형 트리거를 붙이는 것도 관리 대상과 quota를 불필요하게 늘릴 수 있습니다.

단순 트리거를 고를 수 있는 경우

다음 조건이면 단순 트리거부터 검토할 수 있습니다.

• 특정 파일 안에서만 동작한다.
• 현재 파일의 메뉴, 표시, 셀 메모처럼 제한된 동작이면 충분하다.
• Gmail·Drive·Calendar·외부 API 승인이 필요하지 않다.
• 30초 안에 끝나고, 실행 누락을 별도 큐로 복구할 필요가 없다.

설치형 트리거가 필요한 경우

다음과 같은 요구라면 설치형 트리거 쪽이 자연스럽습니다.

• Google Forms 제출 시 응답을 정리하고 확인 메일을 보내야 한다.
• 일정한 간격으로 데이터를 모아 보고서를 만들거나 외부 API를 호출해야 한다.
• 다른 파일, Gmail, Calendar, Drive에 접근해야 한다.
• 여러 사용자가 편집하지만 발송·기록은 정한 운영 계정으로 실행해야 한다.

Google의 설치형 트리거 문서는 트리거가 생성자 계정의 권한으로 실행된다는 점과, 폼 제출·시트 변경·캘린더 변경·시간 기반 이벤트를 구분해 설명합니다. 이 문장을 읽지 않고 “파일을 연 사람이 실행한다”고 설계하면 운영 계정이 어긋납니다.

3. 이벤트 객체를 확인하는 테스트 입력표

트리거 함수에 전달되는 `e`는 단순한 옵션이 아니라, 어떤 값이 들어왔는지를 판단하는 단서입니다. 이벤트마다 필드가 다르므로 모든 함수에서 `e.value`만 출력하는 방식은 안전하지 않습니다.

Google의 이벤트 객체 공식 문서는 이벤트 유형에 따라 `range`, `values`, `namedValues`, `changeType` 등을 설명하고 설치형 이벤트에는 `triggerUid`가 들어올 수 있다고 안내합니다. 코드에 이벤트 객체가 있다고 해서 모든 필드가 모든 이벤트에 존재하는 것은 아닙니다.

수동 실행과 실제 이벤트 실행을 구분한다

편집기에서 함수를 재생 버튼으로 실행하면 실제 이벤트 객체 `e`가 전달되지 않을 수 있습니다. 그래서 함수 본문을 테스트할 때는 아래처럼 입력을 분리합니다.

“`javascript function onFormSubmit(e) { if (!e || !e.namedValues) { throw new Error(‘실제 form-submit 이벤트로 테스트하세요.’); }

const name = e.namedValues[‘이름’]?.[0] || ”; const email = e.namedValues[‘이메일’]?.[0] || ”; console.log({ name, email, triggerUid: e.triggerUid || null }); } “`

이름과 이메일 질문명이 실제 폼의 제목과 정확히 일치하는지 확인해야 합니다. 테스트용 입력을 별도로 기록하면 폼 질문을 나중에 바꿨을 때 어느 필드가 깨졌는지 찾기 쉽습니다. 고객의 실데이터를 그대로 로그에 남기지 말고, 테스트 주소와 가짜 이름을 사용합니다.

4. 설치 순서: 함수 작성보다 권한과 소유 계정이 먼저

1단계: 업무 결과를 한 문장으로 쓴다

“새 응답이 오면 메일을 보낸다”보다 “상담 폼의 테스트 응답을 Sheets에 기록하고, 운영 계정이 확인 메일을 1회 발송한다”처럼 씁니다. 이 문장에는 입력, 결과, 발신 계정, 중복 기준이 들어가야 합니다.

2단계: 트리거와 함수의 역할을 분리한다

함수는 데이터를 검증하고 처리합니다. 트리거는 언제 함수를 부를지만 결정합니다. 아래처럼 함수 이름을 업무 의미에 맞추면 나중에 시간 기반 트리거로 바꿔도 본문을 재사용하기 쉽습니다.

“`javascript function handleConsultationSubmission_(event) { const values = event.namedValues || {}; const requestId = values[‘접수번호’]?.[0] || ”;

if (!requestId) { throw new Error(‘접수번호가 없는 테스트 응답입니다.’); }

// 실제 발송이나 외부 API 호출 전, 테스트 로그만 남기는 단계로 시작합니다. console.log({ requestId, mode: ‘test’ }); }

function onFormSubmit(event) { handleConsultationSubmission_(event); } “`

처음부터 메일 발송을 연결하지 말고, 로그·기록 행·중복 방지 키를 먼저 확인합니다. 자동화가 외부에 영향을 주는 단계는 테스트 데이터로 한 번 더 검토한 뒤 켭니다.

3단계: 편집기에서 설치형 이벤트를 선택한다

Apps Script 편집기의 Triggers 화면에서 함수를 고른 뒤 이벤트 소스를 선택합니다. Forms에 직접 묶인 프로젝트의 form-submit인지, 응답이 쌓이는 Sheets에 설치하는 form-submit인지에 따라 이벤트 객체의 필드와 접근 파일이 달라질 수 있습니다. 프로젝트가 어느 파일에 묶였는지 먼저 확인합니다.

코드로 설치할 때는 다음처럼 작성할 수 있습니다.

“`javascript function createSubmitTrigger() { const spreadsheet = SpreadsheetApp.getActive(); ScriptApp.newTrigger(‘onFormSubmit’) .forSpreadsheet(spreadsheet) .onFormSubmit() .create(); } “`

같은 함수를 여러 번 실행하면 트리거가 중복 생성될 수 있으므로, 생성 전 `ScriptApp.getProjectTriggers()`로 기존 트리거를 확인하거나 설치 목록을 사람이 점검합니다. 설치형 트리거를 수정할 때는 기존 트리거를 삭제하고 새 설정으로 만드는 흐름이 필요할 수 있습니다.

4단계: 운영 계정으로 최초 승인을 끝낸다

트리거를 만드는 계정이 Gmail·Sheets·Drive 등에 접근할 권한이 있는지 확인합니다. 코드에 `GmailApp`, `DriveApp`, `CalendarApp`, `UrlFetchApp` 등을 새로 넣었다면 승인 범위가 달라질 수 있습니다. 승인 화면에서 요청된 범위를 읽고, 자동화에 불필요한 서비스를 삭제하는 편이 좋습니다.

실행 계정이 퇴사자나 개인 계정에 묶이면 자동화는 코드가 남아 있어도 운영되지 않습니다. 공용 운영 계정이 필요하다면 소유권, 파일 공유, 복구용 관리자, 발신 주소를 함께 기록합니다.

5. 시간 기반·폼 제출·웹 앱 트리거를 나누는 기준

시간 기반 트리거는 정확한 시각 알림으로 오해하지 않는다

시간 기반 트리거는 매일·매시간처럼 반복 작업을 실행하는 데 적합합니다. 다만 공식 문서에는 시간 기반 실행 시각이 지정한 시각 주변의 범위로 정해질 수 있다고 설명되어 있습니다. 정각에 고객에게 보내야 하는 안내라면 실제 발송 서비스의 예약 기능과 비교해야 합니다.

시간 기반 작업에는 중복 방지 키가 필요합니다. 예를 들어 `2026-08-05-report`라는 처리 키를 Properties Service나 시트에 남기고, 같은 날짜의 키가 있으면 다시 보내지 않도록 설계합니다. 마지막 실행 시각만 저장하면 재실행과 실패 복구를 구분하기 어렵습니다.

form-submit은 질문명·값 순서 변경을 함께 점검한다

폼 질문의 제목을 바꾸면 `e.namedValues[‘질문명’]` 조회가 실패할 수 있습니다. 질문 순서가 바뀌면 `e.values` 배열의 위치도 달라질 수 있으므로, 운영 폼을 수정하기 전에 테스트 응답을 1건 제출합니다.

기존 autopickgo의 구글폼 상담 신청 자동화 글은 접수 확인 메일과 담당자 알림이라는 업무 결과를 다룹니다. 이 글에서 그 결과를 다시 설명하지 않고, 그 흐름을 Apps Script로 만들 때 어느 계정이 trigger를 설치하고 어떤 event object를 기록할지에 집중합니다.

doGet·doPost는 웹 앱 입구다

외부 서비스에서 HTTP 요청을 받아야 한다면 `doGet(e)` 또는 `doPost(e)`를 검토합니다. Google의 Web Apps 공식 문서는 웹 앱이 `doGet` 또는 `doPost`를 포함하고 `HtmlOutput`이나 `TextOutput`을 반환해야 한다고 설명합니다. 요청의 query string은 `e.parameter`와 `e.parameters`, POST 본문은 `e.postData`에서 확인합니다.

웹 앱은 “URL을 만들면 누구나 안전하게 호출할 수 있다”는 뜻이 아닙니다. 앱을 소유자 권한으로 실행할지, 접속 사용자 권한으로 실행할지에 따라 데이터 접근 범위가 달라집니다. 소유자 OAuth 토큰을 브라우저나 외부 응답으로 보내지 않도록 하고, 외부 서비스가 보낸 요청의 인증·재전송 방지·본문 형식을 별도로 검증합니다.

6. 실행 실패와 quota를 확인하는 운영 루틴

트리거는 화면에 에러를 띄우지 않고 백그라운드에서 실패할 수 있습니다. 따라서 “폼을 제출했는데 메일이 안 왔다”는 말만으로 코드를 고치지 말고 다음 순서로 확인합니다.

1. Apps Script의 실행 기록에서 해당 시간대 실행이 `Completed`, `Failed`, `Running` 중 무엇인지 확인한다. 2. 실패한 함수와 오류 메시지에서 권한 부족, 필드 없음, 서비스 호출 초과를 구분한다. 3. 설치형 트리거 목록에서 중복 트리거와 삭제된 파일을 확인한다. 4. 실행 계정의 파일 접근·메일 발송·외부 API 권한이 아직 유효한지 확인한다. 5. 같은 샘플 입력으로 한 번만 재현하고, 재처리 키를 남긴다.

Google의 서비스 quota 문서는 계정 유형에 따라 quota와 제한이 달라질 수 있고 변경될 수 있다고 안내합니다. 현재 문서에는 사용자·스크립트별 트리거 수 제한도 제시되어 있으므로, 무한히 트리거를 생성하는 구조는 피해야 합니다. 오류가 `Service invoked too many times`라면 문법보다 호출 횟수와 실행 빈도를 먼저 봅니다.

반복 실행을 줄이는 설계

Google의 Apps Script 모범 사례는 외부 서비스 호출을 줄이고, 데이터를 한 번에 읽고 한 번에 쓰며, 필요한 경우 Cache Service를 사용하라고 권합니다. 시트의 각 행마다 `getRange`와 메일 발송을 반복하면 실행 시간과 quota를 동시에 소모합니다.

권장 순서는 다음과 같습니다.

이 원칙은 구글시트 견적서 자동 계산 글의 PDF 결과를 그대로 복제하려는 것이 아니라, Sheets를 자동화의 저장소로 쓸 때 호출량과 재실행 기준을 정하는 데 활용할 수 있습니다.

7. 소상공인 자동화에 적용하는 작은 테스트 시나리오

상담 폼 응답을 Sheets에 저장하고 운영 계정이 확인 메일을 보내는 상황을 예로 들겠습니다. 목표는 한 번에 완성하는 것이 아니라, 입력과 권한을 단계별로 검증하는 것입니다.

1단계: 테스트 폼과 테스트 주소를 만든다

실제 고객 폼을 바로 연결하지 않고 이름 `테스트 사용자`, 주소 `test@example.com`처럼 안전한 값을 사용합니다. 응답에 고유한 접수번호를 넣어 같은 입력이 다시 들어와도 중복을 식별할 수 있게 합니다.

2단계: 로그만 남기는 설치형 form-submit부터 켠다

첫 실행에서는 메일·문자·외부 API를 호출하지 않고 `e.namedValues`, 처리 키, triggerUid만 확인합니다. Sheets의 응답 행과 Apps Script 실행 기록의 시간을 비교해 이벤트가 한 번 실행됐는지 확인합니다.

3단계: 운영 계정의 권한을 승인한다

트리거를 만든 계정이 응답 시트를 읽고 결과를 기록할 수 있는지, Gmail을 사용한다면 발신 권한이 있는지 확인합니다. 개인 계정으로 승인한 뒤 운영 계정으로 실행될 것이라고 가정하지 않습니다.

4단계: 외부 효과를 한 건만 켠다

테스트 주소 한 건에만 확인 메일을 보내고, 수신 시각·제목·본문·발신 계정을 기록합니다. 같은 접수번호를 다시 넣어 중복 발송이 막히는지 확인한 뒤에야 실제 입력을 허용합니다.

예약을 다루는 자동화라면 구글 캘린더 예약 확정 메일 글처럼 업무 결과를 설명하는 콘텐츠와, 이 글의 트리거·권한 설계를 구분해 읽는 것이 좋습니다. Calendar 이벤트가 바뀌었다고 해서 알림 문구, 참석자 권한, 메일 발송이 모두 같은 권한으로 처리되는 것은 아닙니다.

메일 분류를 추가한다면 지메일 견적 문의 자동 분류 글의 사례와 실제 Apps Script 권한 범위를 따로 확인해야 합니다. 자동화 글에 있는 업무 시나리오는 연결 아이디어이지, 현재 계정의 권한이나 서비스 quota를 대신 확인해 주는 증거는 아닙니다.

발행 전 체크리스트와 자주 묻는 질문

발행 전 10문항

• 이벤트가 셀 입력, 구조 변경, 폼 제출, 시간 기반, HTTP 중 무엇인지 적었는가?
• 코드가 특정 파일에 묶였는지 독립 프로젝트인지 확인했는가?
• 단순 트리거로 접근할 수 없는 인증 서비스가 포함되어 있지 않은가?
• 설치형 트리거를 만든 계정과 실제 운영 계정을 기록했는가?
• `e`의 필드를 이벤트에 맞게 확인했는가?
• 수동 함수 실행과 실제 이벤트 실행을 구분해 테스트했는가?
• 같은 함수에 중복 설치된 트리거가 없는가?
• 재실행을 막을 입력 ID나 처리 상태가 있는가?
• 실행 기록에서 실패·중복·권한 오류를 확인했는가?
• 실제 데이터와 외부 발송을 켜기 전에 샘플 한 건으로 결과를 확인했는가?

단순 트리거로 Gmail 메일을 보낼 수 있나요?

공식 단순 트리거 제한에 따르면 인증이 필요한 서비스에는 접근할 수 없습니다. Gmail처럼 승인이 필요한 기능은 설치형 트리거와 운영 계정의 권한을 검토해야 합니다. 단순 `onEdit`에 메일 코드를 넣고 권한 팝업이 뜨기를 기다리는 방식은 적절하지 않습니다.

`onEdit(e)`가 실행되지 않는 이유는 무엇인가요?

첫째, 사람이 직접 수정한 셀인지 스크립트나 API가 바꾼 값인지 구분합니다. 둘째, 코드가 올바른 Sheets 파일에 묶였는지 확인합니다. 셋째, 함수 이름과 코드 저장 상태, 실행 기록을 확인합니다. 짧은 시간에 여러 수정이 들어오면 이벤트 처리 방식의 제한도 확인해야 합니다.

설치형 트리거를 운영 계정으로 바꾸려면 어떻게 하나요?

기존 트리거를 만든 계정과 운영 계정을 먼저 확인하고, 운영 계정으로 새 트리거를 설치한 뒤 샘플 입력으로 발신자와 접근 권한을 검증합니다. 기존 트리거를 그대로 둔 채 새 트리거를 추가하면 중복 실행이 생길 수 있으므로, 전환 시점에 기존 설치를 정리합니다.

시간 기반 트리거가 정각에 실행되지 않는 것이 오류인가요?

지정한 시각과 실제 실행 시각의 관계는 트리거 종류와 설정에 따라 다를 수 있습니다. 공식 문서의 설명과 실행 기록을 함께 확인하고, 고객에게 정각 발송이 필요한 업무라면 전용 예약 기능과 비교합니다. 트리거가 실행됐는지와 결과가 완료됐는지도 분리해서 확인해야 합니다.

웹 앱과 설치형 트리거 중 무엇을 선택하나요?

Google Workspace 파일 내부의 이벤트가 시작점이면 설치형 트리거를 먼저 검토하고, 외부 시스템이 HTTP 요청을 보내야 하면 `doGet`·`doPost` 웹 앱을 검토합니다. 웹 앱은 실행 주체와 공개 범위, 요청 인증을 별도로 설계해야 합니다. URL이 호출된 것만으로 내부 기록이나 메일 발송이 성공했다고 판단하지 말고 요청 로그와 결과 상태를 확인합니다.

마무리

구글 앱스 스크립트 트리거 설정의 핵심은 함수 이름을 외우는 것이 아니라 이벤트 계약과 권한 실행 주체를 먼저 고르는 것입니다. 셀을 직접 수정하는 작은 동작이면 단순 트리거가 충분할 수 있지만, 폼 제출·메일·다른 파일·시간 기반 처리·외부 HTTP 요청이 들어오면 설치형 트리거 또는 웹 앱의 권한 모델을 별도로 설계해야 합니다.

마지막으로 `이벤트 선택 → 파일 연결 → 권한 계정 → 이벤트 객체 → 중복 방지 → 실행 기록`의 순서로 한 건의 샘플을 검증하세요. 이 순서를 지키면 자동화가 실행되지 않는 이유를 코드 오류, 권한 문제, 잘못된 입력, quota 문제로 나누어 볼 수 있고, 수정 후에도 무엇을 다시 확인해야 하는지 남습니다.