구글 API, 붙일 때마다 매번 새로 헤맨다

GAS(구글 앱스 스크립트)로 반복 작업을 자동화해 온 지는 꽤 됐다.

학교 구내 식당의 주간식단표 이미지를 GAS를 통해 인식하여 구글시트에 데이터를 저장한 뒤 조회하는 웹페이지를 만든 것을 시작으로 캠퍼스 시설 업무 도구, 예전 건강 블로그 CMS까지 — 필요할 때마다 구글 API를 하나씩 붙여왔다. 그런데 신기하게도 매번 처음 붙이는 사람처럼 헤맨다. 아마 매번 이번이 마지막일 거라고 생각하기 때문일 것이다.

이번 프로젝트에서 자막-가사 대조 자동화(지난 글에서 "아직 안 해본 것"으로 남겨둔 그 부분)를 준비하면서 예전에 겪었던 것과 똑같은 문제를 또 만났다.

이번 글은 사용법 튜토리얼이 아니라, 매번 똑같은 지점에서 걸려 넘어지는 이유를 정리해보는 글이다.

API 키 발급은 쉬운데, "어디에 어떻게 물리느냐"에서 매번 막힌다

키 발급 자체는 어렵지 않았다. Google AI Studio나 Cloud Console에서 몇 번 클릭하면 끝난다. 문제는 항상 그 다음이다.

GAS 스크립트에 API 키를 어디에 두느냐를 놓고 매번 같은 실수를 반복하곤 한다.

처음 만들 때는 항상 코드 안에 문자열로 바로 박아 넣는다. 당장 돌아가니까 그렇게 넘어간다. 그러다 스크립트를 다른 프로젝트에 복사하거나, 공유가 필요해지는 순간에야 "아, 이거 키 노출되면 안 되는데" 하고 뒤늦게 PropertiesService로 옮기는 작업을 한다. 이 패턴을 최소 세 번은 반복한 것 같다 — 꽃집 콘텐츠 자동화 때, 캠퍼스 도구 때, 그리고 지금.

왜 매번 처음부터 PropertiesService를 쓰지 않았을까 생각해봤는데, 결국 "일단 되는지부터 확인하고 싶다"는 마음이 앞서서다. 프로토타입 단계에서 인증 구조까지 신경 쓰기가 귀찮은 거다. 그런데 그 귀찮음이 매번 나중에 더 큰 번거로움이 되어 돌아온 것이다.

모델 이름이 계속 바뀐다는 걸 매번 잊는다

예전에 잘 돌아가던 스크립트를 다시 꺼내 쓰려다가 에러를 만난 적이 여러 번이다. 원인을 찾아보면 대부분 모델 이름 표기가 바뀌어서였다. 한동안 쓰던 이름이 어느 순간 지원 종료(deprecated)되거나, 새 버전 이름으로 넘어가 있다.

문제는 이게 "에러 메시지만 보면 바로 알 수 있는" 종류가 아니라는 거다. 인증 실패나 권한 문제처럼 보이는 메시지가 뜨는 경우도 있어서, 처음엔 키가 잘못됐나, 프로젝트 설정이 꼬였나부터 확인하게 된다. 모델 이름이 원인이라는 걸 알아차리기까지 매번 시간이 걸린다.

이번 프로젝트 자동화를 준비하면서도 예전 스크립트에서 쓰던 모델 이름을 그대로 가져다 썼다가 첫 실행에서 바로 막혔다. "예전에 됐던 코드니까 되겠지"라는 가정이 항상 틀린다는 걸 알면서도 매번 그 가정에서 시작한다.

할당량(quota) 에러는 원인 파악이 제일 애매하다

무료 등급 기준 요청 수 제한에 걸려본 적이 몇 번 있다. 그런데 이 에러가 애매한 이유는, 정확히 몇 번째 요청에서 한도를 넘었는지, 분당 제한인지 일일 제한인지가 에러 메시지만으로는 바로 와닿지 않는다는 점이다. 짧은 시간에 반복 테스트를 하다 보면 걸리는 경우가 많은데, 정작 "얼마나 쉬었다가 다시 시도해야 하는지" 감이 잘 안 잡힌다.

이번에 자막-가사 대조 자동화를 구상하면서도 이 부분이 걸렸다.

자막 파일 하나를 여러 구간으로 나눠서 여러 번 API를 호출하는 구조를 생각했는데, 반복 호출 자체가 할당량 문제를 일으킬 수 있다는 걸 뒤늦게 떠올렸다. 결국 구간을 통째로 묶어서 한 번에 요청하는 쪽으로 방향을 바꿔야 했다.

여전히 못 푼 것

• 모델 이름이 바뀌는 주기나 공지 방식을 파악해서 미리 대응하는 방법은 아직 못 찾았다. 결국 매번 "터지고 나서야 확인"하는 식이다.
• 할당량 제한을 안전하게 우회하는 재시도(retry) 로직을 GAS 안에 넣어야 하는데, 아직 구현하지 않았다. 지금은 에러가 나면 수동으로 시간 간격을 두고 다시 돌리는 수준이다.
• 자막-가사 대조 자동화 자체는 아직 실제로 완성해서 돌려본 게 아니라서, 이 글에서 다룬 문제들이 실제 운영 단계에서 또 다른 형태로 튀어나올 가능성이 크다.

제미나이가 말하는 원인 및 해결책

현상	발생 원인	해결책
API 키를 코드에 직접 하드코딩했다가 나중에야 안전한 위치로 옮김	프로토타입의 유혹(보안 우선순위 밀림) — 당장 빠른 동작 확인에 집중하다 보니 보안 구조 설계를 후순위로 미루어 동일한 재작업이 반복됨.	기본 보일러플레이트(템플릿) 활용 — PropertiesService.getScriptProperties() 구문이 기본적으로 세팅된 GAS 시작 템플릿을 만들어 두어 원천 차단.
잘 돌아가던 스크립트가 지원 종료나 명칭 변경으로 갑자기 에러 발생	외부 환경 변수(모델 명칭)의 동적 변화 — AI 모델 이름 및 엔드포인트는 주기적으로 개편되나, 이를 정적 코드로 고정해두어 변경을 즉각 인지하기 어려움.	상수화(Constants) 또는 프로퍼티 분리 — 모델명을 코드 최상단 상수 영역이나 스크립트 프로퍼티로 빼두어 변경 시 한 줄만 고쳐 바로 대응할 수 있도록 구조화.
할당량(Quota) 초과 에러 시 정확한 한도와 대기 시간을 파악하기 어려움	API 호출 구조 설계 및 제한 파악 미흡 — 단시간 세분화 반복 호출(Many Requests) 방식은 분당/일일 할당량 한도에 쉽게 도달하고 에러 원인을 모호하게 만듦.	배치(Batch) 묶음 처리 및 지연 재시도 — 데이터를 통째로 묶어 호출 횟수 자체를 최소화하고, GAS 실행 시간 제한 및 할당량 안전 확보를 위해 재시도(Retry) 로직 구현.

정리

구글 API를 "처음 붙이는 법"은 검색하면 얼마든지 나온다. 그런데 실제로 반복해서 쓰다 보면 걸리는 지점은 그 튜토리얼에 안 나오는 부분들이다 — 키를 어디에 둘지 미루다가 나중에 고치는 습관, 모델 이름이 바뀐다는 걸 매번 잊는 것, 할당량 에러의 원인을 바로 알아차리기 어려운 것. 도구를 새로 배우는 게 아니라, 같은 실수를 반복하지 않는 습관을 만드는 게 더 어려운 일 같다.