구글 시트 자동화가 수동 실행만 될 때: 트리거·권한·실행 로그 점검

구글 시트의 Apps Script가 실행 버튼을 눌렀을 때만 작동한다면, 트리거 등록 → 실행 계정과 권한 → 실행 기록 순서로 확인하세요. 수동 실행이 성공했다는 사실만으로 자동 실행 조건까지 맞다고 볼 수는 없습니다. 자동 실행이 시작되지 않았는지, 시작한 뒤 실패했는지를 먼저 나누면 확인할 범위가 줄어듭니다.

이 글은 구글 스프레드시트에 연결한 Apps Script를 기준으로 합니다. 아래 코드는 공식 문서를 바탕으로 구성한 진단용 예제이며, 실제 구글 계정에서 실행해 관측한 결과는 아닙니다. 먼저 빈 테스트 파일에서 기대 결과를 직접 대조하세요.

1. 일반 함수인지, 자동 실행되는 함수인지 확인합니다

updateSheet()라는 함수를 만들고 저장했다고 해서 셀을 편집할 때마다 호출되지는 않습니다. 어떤 사건이 함수를 실행할지 연결해야 합니다.

구분	실행하는 방법	먼저 확인할 것
수동 실행	편집기에서 함수를 선택하고 실행	이 성공 기록을 자동 실행 성공으로 착각하지 않았는지
단순 트리거	onEdit(e), onOpen(e)처럼 정해진 이름 사용	함수 이름과 이벤트가 맞는지
설치형 트리거	트리거 화면 또는 코드에서 별도 등록	등록한 함수·이벤트·계정이 맞는지

예를 들어 사람이 셀 값을 바꿀 때는 편집 이벤트, 매일 정해진 주기로 처리할 때는 시간 기반 트리거가 필요합니다. 시간 기반 실행에는 편집한 셀을 가리키는 e.range가 없으므로, 편집용 함수를 그대로 연결하면 안 됩니다. 이벤트마다 전달되는 정보는 공식 이벤트 객체 문서에서 확인할 수 있습니다.

설치형 트리거는 Apps Script 왼쪽의 트리거 → 트리거 추가에서 등록합니다. 셀 편집이 목적이라면 실행할 함수와 이벤트 소스 ‘스프레드시트에서’, 이벤트 유형 ‘수정 시’를 대조하세요. 화면 언어에 따라 항목 이름은 달라질 수 있습니다. 설치형 트리거 등록 안내

2. 단순 onEdit에서 할 수 없는 작업인지 봅니다

onEdit(e)를 사용하면 별도 등록 없이 사람의 셀 값 편집에 반응할 수 있습니다. 다만 단순 트리거에는 제한이 있습니다.

• 연결된 시트는 수정할 수 있지만, 승인이 필요한 다른 파일에 접근할 수 없습니다.
• Gmail처럼 사용자 승인이 필요한 서비스를 호출할 수 없습니다.
• 실행 시간이 30초를 넘을 수 없습니다.
• 보기·댓글 권한으로 파일을 연 경우에는 실행되지 않습니다.

따라서 같은 코드가 수동 실행에서는 메일을 보내지만 단순 onEdit에서는 실패할 수 있습니다. 승인이 필요한 작업은 설치형 트리거 사용을 검토해야 합니다. 단순 트리거에 수동으로 권한을 한 번 승인한다고 이 제한이 없어지는 것은 아닙니다. 단순 트리거의 제한

설치형으로 전환한다면 함수 이름을 handleSheetEdit처럼 바꾸고 그 함수를 등록하는 편이 구분하기 쉽습니다. 같은 기능을 하는 단순 onEdit와 설치형 편집 트리거를 함께 남기지 않았는지도 확인하세요. 하나의 편집에 처리가 중복될 수 있습니다.

3. 트리거를 만든 계정의 권한을 확인합니다

설치형 트리거는 트리거를 만든 사람의 계정으로 실행됩니다. 공유 시트를 편집한 사람이 누구인지와 별개입니다. 다른 계정으로 수동 실행한 성공 기록만 확인하면 이 차이를 놓치기 쉽습니다. 또한 내 계정에서는 다른 계정이 설치한 트리거가 보이지 않을 수 있습니다. 설치형 트리거의 실행 계정

실패 기록에 Authorization is required to perform that action이 있다면 트리거 생성 계정으로 프로젝트를 열어 승인 상태를 점검하세요. 자동 실행 중에는 권한 승인 창을 띄울 수 없습니다. 코드에 새 서비스를 추가했거나 필요한 권한을 승인하지 않았다면 추가 승인이 필요할 수 있습니다. 권한 오류 해결 안내

편집기에서 함수를 실행하면 필요한 승인 절차를 시작할 수 있습니다. 이때는 실제 메일 발송이나 데이터 삭제를 하지 않는 안전한 확인용 함수를 선택하고, 요청하는 접근 범위가 코드의 목적과 맞는지 읽어 보세요. 이벤트 객체가 필요한 처리 함수의 수동 실행 결과는 아래 6번처럼 따로 해석해야 합니다. 서비스 추가 후 재승인 안내

4. 실행 기록에서 ‘미실행’과 ‘실패’를 나눕니다

Apps Script 왼쪽의 실행 화면을 열고 방금 시험한 시각의 함수·실행 유형·상태를 봅니다. 실패를 찾을 때는 상태 필터에서 실패와 시간 초과를 선택할 수 있습니다. 편집기 위쪽의 실행 로그는 수동 시험을 바로 확인할 때 유용하고, 자동 실행 문제는 실행 목록에서 해당 기록을 찾아 확인하는 편이 좋습니다. 실행 로그와 예외 기록 안내

• 해당 시각의 기록이 없다면: 계정·프로젝트·필터가 맞는지 확인한 뒤, 등록된 이벤트와 실제 시험 동작을 다시 비교합니다.
• 실패·시간 초과라면: 오류 문구와 발생 위치를 먼저 확인합니다. 권한 오류인지, 실행 시간·호출 횟수 제한인지에 따라 대응이 달라집니다.
• 완료인데 결과가 없다면: 조건문에서 건너뛰었는지, 다른 시트나 셀에 썼는지 확인합니다. ‘완료’ 상태만으로 원하는 작업까지 수행됐다고 판단하지 않습니다.

함수 시작·건너뜀·처리 완료 지점에 console.log()를 넣으면 흐름을 찾기 쉽습니다. 고객 이름이나 셀 내용 전체를 남기기보다, 단계 이름과 필요한 최소 정보만 기록하세요.

호출 횟수나 실행 시간 제한을 만났다면 재시도를 계속 추가하기 전에 실행 빈도와 처리량부터 줄여 봅니다. 계정 종류별 할당량과 제한은 달라질 수 있으므로 오류 문구를 공식 할당량 문서와 대조하세요.

5. 사람이 편집했는지, 프로그램이 바꿨는지 구분합니다

스크립트의 setValue()나 API 요청으로 셀을 바꿔도 스프레드시트의 편집 트리거가 실행되지는 않습니다. 이 점은 설치형 편집 트리거로 바꿔도 해결되지 않습니다. 사람이 직접 값을 바꾸는 시험과 외부 프로그램이 값을 쓰는 시험을 구분하세요. 스크립트 변경과 트리거의 관계

예를 들어 ‘외부 프로그램이 A열을 갱신 → onEdit가 감지 → 요약 갱신’을 기대했다면 연결 방식을 바꿔야 합니다. 값을 쓰는 코드에서 후속 처리 함수를 직접 호출하거나, 시간 기반 트리거가 새 데이터를 주기적으로 확인하도록 구성할 수 있습니다. 두 경우 모두 처리 완료 여부를 남겨 같은 데이터를 반복 처리하지 않도록 설계하세요.

시간 기반 트리거를 쓸 때도 정각 실행을 가정하지 마세요. 공식 문서는 매일 오전 9시로 만든 트리거가 9시와 10시 사이의 시각에 배정될 수 있다고 설명합니다. 정확한 시각이 중요한 알림은 이 실행 방식이 요구사항에 맞는지부터 확인해야 합니다. 시간 기반 트리거의 실행 시각

6. onEdit는 실행 버튼 대신 실제 셀 편집으로 시험합니다

onEdit(e)의 e는 편집 이벤트가 발생할 때 전달되는 정보입니다. 편집기에서 함수를 직접 실행하면 편집 이벤트 객체가 자동으로 만들어지지 않습니다. 따라서 e.range를 읽는 코드에서 오류가 나더라도 실제 편집 트리거가 고장 났다고 바로 판단하면 안 됩니다.

아래 예제는 시험 동작을 좁혔습니다. ‘트리거테스트’ 탭의 A2 한 칸을 직접 바꿀 때 B2에 ‘편집 감지’, C2에 처리 시각을 기록합니다. B2와 C2는 덮어쓰므로 반드시 빈 테스트 시트에서 사용하세요.

1. 새 스프레드시트를 만들고 시트 탭 이름을 트리거테스트로 바꿉니다.
2. 확장 프로그램 → Apps Script에서 아래 코드를 넣고 저장합니다.
3. 이 예제에는 설치형 트리거를 추가하지 않습니다.
4. 시트로 돌아와 A2에 ‘첫 시험’을 입력하고, B2·C2를 확인합니다.
5. A2를 ‘두 번째 시험’으로 바꿔 C2의 시각이 갱신되는지 봅니다.

function onEdit(e) {
  if (!e || !e.range) {
    console.log('시험 방법: 시트의 A2 값을 직접 바꾸세요.');
    return;
  }

  const range = e.range;
  const sheet = range.getSheet();
  console.log('시작: ' + sheet.getName() + '!' + range.getA1Notation());

  if (sheet.getName() !== '트리거테스트' ||
      range.getA1Notation() !== 'A2') {
    console.log('건너뜀: 시험 대상 셀이 아닙니다.');
    return;
  }

  sheet.getRange('B2').setValue('편집 감지');
  sheet.getRange('C2').setValue(new Date())
    .setNumberFormat('yyyy-mm-dd hh:mm:ss');
  console.log('완료: B2와 C2 기록');
}

기대 결과는 다음과 같습니다. 실제로 시험한 뒤 결과를 비교하세요.

• A2 한 칸의 값을 직접 변경: B2에 ‘편집 감지’, C2에 처리 시각 표시
• A3 변경 또는 A2:A3를 한꺼번에 붙여 넣기: 대상 범위가 달라 B2·C2 기록을 건너뜀
• 편집기에서 onEdit를 직접 실행: 시험 방법만 로그에 남기고 종료
• 별도 스크립트나 API로 A2 변경: 그 변경으로 onEdit가 실행되지 않음

이 코드는 단일 셀 시험을 위한 것입니다. 여러 셀 붙여 넣기를 처리하려면 편집 범위 전체를 고려하도록 조건을 바꿔야 합니다. 이벤트의 value와 oldValue도 여러 셀 편집에서는 제공되지 않으므로 항상 있다고 가정하지 마세요. 편집 이벤트에 포함되는 값

마지막 점검표

• 자동 실행할 함수와 이벤트가 연결되어 있는가?
• 단순 트리거의 권한 제한에 걸리는 작업인가?
• 설치형 트리거를 만든 계정으로 권한과 대상 파일 접근을 확인했는가?
• 실행 기록에서 미실행·실패·조건에 따른 건너뜀을 구분했는가?
• 사람의 편집과 스크립트·API 변경을 구분했는가?
• 이벤트 처리 함수를 실제 이벤트로 시험했는가?

마감일을 색이나 상태로 표시하는 정도라면 함수와 조건부 서식으로도 해결할 수 있습니다. 구글 시트 마감일 자동 표시 예제를 먼저 확인하세요. 알림 발송까지 연결한다면 예약 알림 자동화 검증표의 중복·취소·재시도 상황도 함께 점검하는 것이 좋습니다.

공식 문서 확인일: 2026-09-30. 예제의 출력은 기대 결과이며, 실제 사용하는 계정과 시트에서 확인한 뒤 업무 파일에 적용하세요.