Google Sheets
개요
Google Sheets 연동은 API가 호출될 때마다 그 결과를 본인의 Google Drive 스프레드시트에 한 행씩 자동으로 기록해주는 기능이에요. 매월 새 시트 파일이 자동으로 만들어지고, 새 필드가 추가되면 헤더도 자동으로 늘어납니다.
코딩 없이 매출/주문/문의 같은 데이터를 시트로 모아 보고 싶을 때 가장 편한 길이에요. 시트는 본인 Drive에 저장되므로 평소 쓰던 그대로 공유, 필터, 차트, 피벗 테이블을 자유롭게 사용할 수 있습니다.
소유자 전용 기능입니다. 협업자에게는 Google Sheets 카드가 보이지 않아요.
진입 경로
- 상단 메뉴 APIs → 원하는 엔드포인트 이름 클릭해서 엔드포인트 상세로 이동
- 페이지 안의 Google Sheets 카드에서 시작
처음 연동할 때 Google 계정이 아직 연결되어 있지 않으면, 카드 안내에 따라 먼저 외부 연동 설정으로 이동해서 Google 계정을 연결해주세요.
Free 플랜에서도 사용할 수 있어요. 부담 없이 테스트해보세요.
Drive에 무엇이 만들어지나요
연동을 시작하면 본인 Google Drive 최상위에 3Min API 폴더가 자동으로 만들어지고, 그 안에 다음 구조로 파일이 정리됩니다.
3Min API/
├── user-signup/ ← 엔드포인트별 폴더
│ ├── sandbox_user-signup_2026-04 ← 월별 시트 (샌드박스)
│ ├── sandbox_user-signup_2026-05
│ └── production_user-signup_2026-05 ← 월별 시트 (프로덕션)
└── order-create/
└── production_order-create_2026-05
- 폴더 이름: 엔드포인트 이름 (특수문자는 자동으로 정리됩니다)
- 파일 이름:
{환경}_{엔드포인트}_{YYYY-MM}(UTC 기준 월) - 새 달이 시작되면 다음 호출 시점에 새 파일이 자동으로 생성됩니다
권한 범위
3Min API는 Google에 drive.file 권한 한 가지만 요청합니다. 이 권한은 3Min API가 직접 만든 파일에만 접근할 수 있는 좁은 권한이에요. 본인의 다른 Drive 자료(다른 시트, 문서, 공유 폴더)에는 접근하지 못하니 안심하셔도 됩니다.
시트 컬럼 구성
각 시트의 첫 행(헤더)은 두 종류의 컬럼으로 구성됩니다.
메타 컬럼 (요청에 대한 시스템 정보)
| 컬럼 | 의미 |
|---|---|
record_id |
호출 한 건을 가리키는 고유 ID (3Min API 로그/아카이브와 연결) |
created_at |
호출이 들어온 시각 (UTC) |
config_version |
호출 당시 사용된 엔드포인트 스키마 버전 |
operation |
create / read / update / delete |
status |
처리 결과 |
collaboration_key |
어떤 협업 키로 호출됐는지 |
페이로드 컬럼 (요청에 담긴 비즈니스 데이터)
페이로드의 각 필드는 payload_ 접두어가 붙어 별도 컬럼으로 들어갑니다. 예: payload_email, payload_amount, payload_address_city. 메타 컬럼과 섞이지 않도록 출처를 명시하는 거예요.
새 필드가 들어오면 시트 오른쪽에 새 컬럼이 자동으로 추가됩니다. 기존 행의 새 컬럼 자리는 빈 칸으로 남습니다.
연동 방법
1단계 — Google Sheets 카드에서 연동 시작
엔드포인트 상세의 Google Sheets 카드에서 `연동 시작` 버튼을 누릅니다.
2단계 — Google 동의 화면
Google 화면에서 3Min API가 요청하는 권한이 drive.file 한 가지뿐임을 확인하고 동의를 눌러주세요. 계정에 따라 권한별 체크박스가 함께 보일 수 있는데, 그땐 모든 체크박스를 켠 상태로 동의해야 시트 기록이 정상 작동합니다.
3단계 — 연동 완료, 첫 행 기록 확인
연동이 완료되면 카드에 연동됨 배지와 시트 파일명이 표시됩니다.
`시트 열기`— 새 탭에서 Drive의 시트 파일을 엽니다`테스트 전송`— 샘플 행 한 줄을 시트에 기록해 동작을 확인할 수 있어요. 개발 도구나 코드 없이 바로 결과를 볼 수 있는 가장 빠른 방법입니다`연동 해제`— 이 엔드포인트의 자동 기록을 멈춥니다 (Drive의 기존 파일은 그대로 남습니다)
이제 이 엔드포인트로 API가 호출될 때마다 시트의 마지막 행에 자동으로 기록됩니다.
알아두면 좋은 점
처리 속도
- 시트 기록은 순차적으로 처리됩니다. API 호출 자체는 즉시 응답하지만, 시트에 행이 보이기까지 보통 수 초 이내입니다.
- 호출이 한꺼번에 몰리면 큐에 쌓여 차례로 처리되며, 평소보다 늦게 시트에 반영될 수 있어요.
- 일시적인 한도 초과(429)나 일시 장애가 발생하면 약 5분간 자동으로 재시도합니다. 그 사이에 행 순서가 호출 순서와 살짝 달라질 수 있는데, 정확한 순서가 필요하면 시트에서
created_at컬럼으로 정렬해서 보세요.
실패해도 데이터는 안전합니다
자동 재시도 후에도 시트 기록이 끝까지 실패하면 시트에만 행이 빠지고, 원본 데이터는 로그와 아카이브에 그대로 보존됩니다. 시트 기록 실패는 엔드포인트의 시스템 알림에 등록한 Discord / Slack / Telegram 채널로 통지돼요(이메일은 발송되지 않습니다).
재인증이 필요한 경우
다음 상황에서는 시트 기록이 멈추고 재인증 알림(google_reauth_required)이 발송됩니다.
- 본인이 Google 계정 설정에서
3Min API앱 연결을 해제한 경우 - Google이 토큰을 만료시킨 경우 (장기간 미사용 등)
- 권한 체크가 풀려
drive.file이 빠진 경우
알림을 받으면 외부 연동 설정에서 다시 연결해주세요. 재연결 후에는 기존 시트 파일이 그대로 다시 사용됩니다.
환경별로 따로 동작합니다
샌드박스와 프로덕션의 Google Sheets 연동은 완전히 독립적이에요. 같은 엔드포인트라도 환경 탭마다 별도로 연동/해제할 수 있고, 시트 파일도 환경별로 따로 만들어집니다.
프로덕션 배포 후에도 샌드박스의 Google Sheets 연동이 자동으로 따라가지 않습니다. 프로덕션 환경 탭의 Google Sheets 카드에서 다시 한 번 `연동 시작` 을 눌러주세요.
연동 해제
해제 방법은 두 가지가 있습니다.
엔드포인트별 해제
엔드포인트 상세의 Google Sheets 카드에서 `연동 해제`. 해당 엔드포인트의 시트 자동 기록만 멈춥니다. 다른 엔드포인트의 Google Sheets 연동은 그대로 유지돼요.
전체 해제 (Google 계정 연결 자체 끊기)
상단 메뉴 설정 → 외부 연동 → Google Drive & Sheets → 페이지 하단 위험 영역의 `전체 연결 해제`. 모든 엔드포인트의 Google Sheets 연동이 한 번에 멈추고, 3Min API의 OAuth 인증도 해제됩니다. 다시 쓰려면 처음부터 연결해야 해요.
해제 후 데이터
두 방식 모두 Drive에 만들어진 기존 시트 파일은 그대로 남습니다. 필요 없으면 직접 Drive에서 삭제하시면 돼요. 다음에 다시 연동하면 새 파일이 자동으로 만들어지고, 이전 파일은 자동으로 삭제되지 않습니다.
자주 막히는 부분
프로덕션으로 배포했는데 시트에 기록이 안 돼요
샌드박스의 Google Sheets 연동은 프로덕션으로 자동 이전되지 않습니다. 엔드포인트 상세에서 프로덕션 탭으로 전환한 뒤, Google Sheets 카드에서 별도로
`연동 시작`을 눌러주세요. 이전에 만들어진 샌드박스 시트와 별개로production_*파일이 새로 생성됩니다.연동했는데 시트 파일이 안 보여요
Drive 최상위의
3Min API폴더를 먼저 확인해보세요. 첫 호출이 들어와야 그 달의 시트 파일이 만들어집니다.`테스트 전송`으로 즉시 만들어볼 수 있어요. 그래도 안 보이면 외부 연동 설정에서 권한이 부족하다는 안내(노란 배지)가 떠 있는지 확인해주세요.헤더에 갑자기 새 컬럼이 늘었어요
엔드포인트에 새 필드가 추가되면 시트 헤더가 자동으로 확장됩니다(이전 행의 새 컬럼 자리는 빈 칸). 의도한 동작이에요. 헤더를 직접 지우거나 순서를 바꾸지는 마세요. 다음 행 기록 시 컬럼 매핑이 어긋날 수 있습니다.
시트 파일을 옮기거나 이름을 바꿔도 되나요?
네, 안전해요. 3Min API는 파일 ID로 추적하기 때문에 파일을 다른 폴더로 옮기거나 이름을 바꿔도 계속 같은 파일에 행이 추가됩니다. 다만 휴지통으로 보내거나 영구 삭제하면 다음 호출 시점에 새 파일이 자동으로 만들어지고, 삭제된 파일은 복구되지 않아요.
3Min API폴더를 통째로 지웠어요다음 호출이 들어오면 새 폴더와 새 시트가 자동으로 만들어집니다. 다만 삭제된 기존 시트는 복구되지 않으니, 보존하고 싶은 데이터는 미리 아카이브에서 내려받아 두는 걸 권장합니다.
시트 기록 실패 알림이 너무 자주 와요
시트 기록 실패 알림은 엔드포인트 상세 > 알림에서 Discord/Slack/Telegram 채널을 등록해 두면 받게 되는 메시지예요. 그 알림이 평소보다 잦아진 거라면 다음 상황을 확인해 보세요.
3Min API는 끝까지 자동 재시도하고, 필요하면 Google에 한도 상향도 신청해 처리량을 계속 늘려가고 있어요. 그럼에도 알림이 잦다면, Google이 정한 시트 쓰기 한도(보통 사용자당 분당 60건 수준)를 넘어서는 호출이 들어오고 있다는 뜻입니다. 이 한도는 3Min API가 정한 것이 아니라 Google 측 정책이라 개별 사용자 단위로 더 풀어드리기는 어려워요.
사실 이건 사업이 잘 되고 있다는 좋은 신호예요. Google 시트는 가벼운 기록과 빠른 시각화에는 훌륭하지만, 분당 수십 건 이상을 꾸준히 넘기는 트래픽에서는 시트 자체가 본래 그 용도로 만들어지지 않았습니다. 다음 단계를 검토해볼 시점이에요.