본문으로 건너뛰기

구글 시트 API, 서비스 계정 연결 6단계와 호출 한도표

쇼핑몰 · 사내 프로그램 데이터를 시트로 보내는 구글 시트 API 연결을 프로젝트 만들기부터 첫 호출까지 6단계로 나누고, 분당 읽기 · 쓰기 한도와 넘었을 때의 처리, 여러 행을 묶어 보내는 계산 예, 앱스 스크립트와 비교한 표를 정리했습니다.

구글 시트 API, 서비스 계정 연결 6단계와 호출 한도표

구글 시트 API는 구글 클라우드 프로젝트에서 시트 API를 켜고 서비스 계정을 만든 뒤, 그 서비스 계정의 이메일 주소에 시트를 공유하면 외부 프로그램에서 읽고 쓸 수 있습니다. 클라우드 콘솔의 권한(IAM 역할)으로는 시트가 열리지 않고 시트 공유로만 열린다는 점이 처음 막히는 곳입니다. 읽기 · 쓰기 요청은 각각 프로젝트당 분당 300회, 사용자당 분당 60회로 제한되므로 한 행씩 보내지 말고 여러 행을 묶어 한 번에 보내는 것이 핵심입니다.

구글 시트 API로 무엇을 할 수 있나요

시트 밖에 있는 프로그램이 시트를 데이터 창구로 쓰게 해 줍니다. 쇼핑몰 주문을 매시간 시트에 쌓아 영업 담당이 보게 하거나, 사내 프로그램의 재고 수량을 시트로 내보내거나, 반대로 담당자가 시트에 고친 가격표를 프로그램이 읽어 가는 식입니다. 값을 읽고 쓰는 기능은 아래 다섯 가지 호출로 나뉩니다.

  • values.get / values.update: 범위 하나를 읽거나 씁니다.
  • values.batchGet / values.batchUpdate: 여러 범위를 한 번에 읽거나 씁니다.
  • values.append: 표 아래에 행을 덧붙입니다.

행을 끼워 넣거나 서식을 바꾸는 일은 시트 전체를 다루는 batchUpdate로 합니다. 구글 안내는 여러 번 읽고 쓰는 일은 batchGet · batchUpdate로 묶는 편이 효율적이라고 적고 있습니다.

서비스 계정 연결은 어떤 순서인가요

서비스 계정은 사람이 아니라 프로그램이 쓰는 계정입니다. 사람이 로그인해 허락하지 않아도 서버에서 정해진 시각에 돌릴 수 있어, 자동으로 보내고 받는 연동에 맞습니다.

단계할 일확인할 것
1. 프로젝트 만들기구글 클라우드 콘솔에서 프로젝트를 만듭니다회사 계정으로 만들어 담당자가 바뀌어도 이어 쓰기
2. API 켜기그 프로젝트에서 Google Sheets API를 사용 설정합니다API를 쓰기 전에 프로젝트에서 켜 두어야 함
3. 서비스 계정 만들기IAM 및 관리자 메뉴의 서비스 계정에서 새로 만듭니다서비스 계정 이메일 주소를 적어 둠
4. 키 만들기서비스 계정의 키 탭에서 새 키를 JSON 형식으로 만듭니다내려받은 파일이 유일한 사본이고 다시 받을 수 없음
5. 시트 공유시트 공유 창에 서비스 계정 이메일을 넣고 권한을 줍니다읽기만 하면 뷰어, 쓰면 편집자
6. 첫 호출스프레드시트 ID와 범위(예: 주문!A1:F1)로 한 번 읽고, 한 번 씁니다읽기 · 쓰기 모두 성공

4단계의 키 파일은 비밀번호와 같습니다. 구글 클라우드의 키 관리 권고는 키를 소스 코드 저장소에 올리지 말 것, 임시 폴더에 두지 말 것, 사람끼리 주고받지 말 것, 주기적으로 교체할 것을 적고, 가능하면 키 없는 더 안전한 인증 방식을 고르라고 권합니다. 키 파일은 서버의 비밀 값 보관 기능에 넣고, 교체 날짜를 운영 일정에 적어 두세요.

호출 한도에 걸리지 않으려면 어떻게 쓰나요

한도는 분 단위로 다시 채워집니다. 구글 안내에 적힌 한도와 동작은 이렇습니다.

구분한도넘으면
읽기 요청프로젝트당 분당 300회, 프로젝트 안 사용자당 분당 60회429 오류(요청이 너무 많음)
쓰기 요청프로젝트당 분당 300회, 프로젝트 안 사용자당 분당 60회429 오류
하루 요청 수분당 한도 안이면 제한 없음해당 없음
요청 하나의 처리 시간180초시간 초과 오류
요청 크기2MB 이하 권장느려지거나 다른 처리 단계의 한도에 걸릴 수 있음
시트 하나의 크기(드라이브 기준)셀 2,000만 개 또는 100MB더 넣을 수 없음

묶음 요청은 안에 하위 요청이 몇 개 들어 있든 한 번으로 셉니다. 주문 1,000건을 한 행씩 쓰면 요청이 1,000번이고, 분당 60회를 기준으로 하면 17분 가까이 걸립니다. 같은 1,000건을 append 한 번에 담으면 요청 1번입니다. 주문이 생길 때마다 바로 보내지 말고, 1분이나 5분마다 그사이 쌓인 행을 모아 보내도록 만드세요. 429 오류가 나면 구글 안내대로 기다리는 시간을 점점 늘려 가며 다시 보내는 방식(지수 백오프)을 쓰고, 1분이 지나면 다시 요청할 수 있습니다.

값을 쓰는 방식도 정해야 합니다. USER_ENTERED는 시트 화면에 직접 입력한 것처럼 해석해 날짜 · 수식 · 숫자로 바꾸고, RAW는 받은 글자를 그대로 넣습니다. 주문번호 · 전화번호처럼 글자 그대로 남아야 하는 값은 RAW로 쓰세요. 묶음으로 보낸 요청은 하나라도 잘못되면 전체가 반영되지 않으므로, 실패한 묶음을 통째로 다시 보내는 처리를 넣습니다.

앱스 스크립트와는 언제 나눠 쓰나요

시트 안에서 끝나는 일은 앱스 스크립트, 시트 밖 프로그램이 시작하는 일은 시트 API가 맞습니다. 앱스 스크립트로 시트 안 자동화를 하는 법은 구글 앱스 스크립트 사용법, 자동화 예시 5개에 정리돼 있습니다.

구분구글 시트 API앱스 스크립트
실행 위치쇼핑몰 서버 · 사내 프로그램구글 서버, 시트에 붙은 스크립트
인증서비스 계정 키 또는 사용자 동의(OAuth)스크립트를 실행하는 사람의 권한
시작 계기주문 발생 같은 외부 사건시간 트리거 · 시트 편집 · 메뉴
대표 한도분당 읽기 · 쓰기 각 300회(프로젝트), 60회(사용자)한 번 실행 6분, 트리거 총 실행 시간 하루 90분(개인 계정) · 6시간(Workspace)
맞는 일외부 데이터를 시트로 보내거나 시트 값을 외부 프로그램이 읽음시트 정리 · 메일 보내기 · 정해진 시각에 외부 API 불러오기

둘을 섞어 쓰기도 합니다. 외부 프로그램은 시트 API로 원본 행만 쌓고, 합계 · 서식 · 알림 메일은 앱스 스크립트가 맡으면 각자의 한도 안에서 돌아갑니다. 시트를 여러 사람이 함께 쓰는 규칙은 구글 스프레드시트 사용법, 공유 업무표 8단계를 참고하세요.

자주 묻는 질문

서비스 계정 없이 내 구글 계정으로 연결할 수는 없나요?

사용자가 로그인해 허락하는 OAuth 클라이언트 방식이 있습니다. 사람이 직접 쓰는 도구라면 이쪽이 자연스럽지만, 서버가 사람 없이 정해진 시각에 돌아야 하면 로그인 과정이 끼어들지 않는 서비스 계정이 맞습니다.

구글 시트를 데이터베이스 대신 써도 되나요?

주문 원본은 프로그램의 데이터베이스에 두고, 시트는 보고 · 확인용 사본으로 두는 편이 안전합니다. 시트는 크기 한도(셀 2,000만 개)와 분당 호출 한도가 있고, 여러 사람이 같은 칸을 고치면 프로그램이 쓴 값이 덮일 수 있습니다. 데이터가 적고 한 사람만 고치는 설정표라면 시트로 충분합니다.

429 오류가 계속 나면 무엇부터 보나요?

먼저 반복문 안에서 한 행씩 쓰는 코드가 있는지 봅니다. 대부분 묶음 요청으로 바꾸면 요청 수가 크게 줄어듭니다. 그래도 나면 여러 프로그램이 같은 프로젝트로 요청하고 있는지 확인하세요. 프로젝트당 분당 300회는 그 프로젝트를 쓰는 모든 프로그램이 함께 나눠 씁니다.

구글 시트 API 연동을 외부에 맡기면 비용은 무엇으로 정해지나요?

보낼 데이터 종류와 열 수, 한쪽으로만 보내는지 시트 값도 읽어 오는지, 실행 주기, 실패했을 때 다시 보내는 처리와 알림, 키를 보관하는 방식으로 정해집니다. 구글 시트 연동 개발을 맡길 때 시트에 들어갈 열 이름과 예시 행을 함께 넘기면 범위가 빨리 정해집니다.

오늘 할 일

시트로 보낼 데이터의 열 이름과 순서를 먼저 정해 시트 첫 행에 고정해 두세요.

이어서 읽기 — 인스타그램 API, 연결 6단계와 기능별 자동화 범위표

FacebookX

이 글과 맞는 서비스

이어서 읽기

블로그 전체 글 목록 →

카카오톡 상담식스원 고객센터 카카오톡 채널 (새 창)