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

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

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

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

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

 

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

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

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

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

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

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

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

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

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

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

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

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

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

제미나이가 말하는 대응방안

1. 보안을 미루게 만드는 '프로토타입의 유혹' (PropertiesService) 어차피 겪을 고생이라면, 아예 'GAS 프로젝트 템플릿(Boilerplate)' 하나를 미리 만들어두는 것도 방법입니다. 스크립트를 새로 팔 때마다 빈 파일에서 시작하는 게 아니라, 애초에 PropertiesService.getScriptProperties().getProperty('API_KEY') 구조가 기본으로 세팅된 뼈대 파일에서 출발하면 이 귀찮은 전환 과정을 원천 차단할 수 있습니다. 2. 살아있는 생물 같은 '모델 이름의 변화 모델 명칭이나 엔드포인트처럼 외부 환경에 의해 변동될 수 있는 값들은 코드 중간중간에 박아두기보다, 아예 상수(Constants) 영역이나 스크립트 프로퍼티 쪽으로 빼두는 것이 유리합니다. 나중에 모델명이 바뀌었을 때 코드 전역을 뒤지며 수정할 필요 없이 설정값 한 줄만 싹 고치면 되니까요. 3. 모호한 '할당량(Quota) 에러'와 아키텍처의 타협 자막-가사 대조 자동화처럼 대량의 텍스트를 다룰 때 '조각내서 여러 번 호출(Many small requests)'하는 방식보다, '한 번에 묶어서 대량으로 처리(Batch/Bulk request)'하는 구조로 설계를 선회하신 것은 아주 현명한 판단입니다. API 호출 횟수 자체를 줄이는 것이 할당량 방어뿐만 아니라 전체적인 속도(Execution Time) 면에서도 훨씬 유리하니까요. (GAS는 단일 실행 시간 제한도 넉넉하지 않기 때문에 묶음 처리가 안전합니다.)

 

여전히 못 푼 것

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

정리

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