Files

minsung ae439452ee Add Google Sheets integration guide (clasp + gws CLI)

Closes #2

- clasp: 설치, 인증, 기존 시트 바인딩, push/pull 워크플로우, 제한사항
- gws CLI: 설치, OAuth 설정(자동/수동), 시트 데이터 읽기/쓰기
- 세 가지 방식(clasp, gws, Sheets API) 비교표
- 현재 프로젝트 설정 정보

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-13 11:52:43 +09:00

4.4 KiB

Raw Permalink Blame History

Google Sheets 로컬 연동 가이드

로컬 환경에서 Google Sheets를 다루는 방법을 정리한다.

1. clasp (Google Apps Script CLI)

Apps Script 코드를 로컬에서 작성하고 Google 시트에 배포하는 도구.

1.1 설치

npm install -g @google/clasp

1.2 인증

clasp login

브라우저가 열리면 Google 계정으로 인증
사전 조건: https://script.google.com/home/usersettings 에서 Apps Script API ON

1.3 기존 시트에 Apps Script 바인딩

# --parentId: 기존 Google Sheet의 ID (URL에서 /d/ 뒤의 값)
# --type 옵션 없이 사용해야 기존 시트에 바인딩됨 (--type sheets는 새 시트를 생성함)
clasp create --title "프로젝트명" --parentId "SPREADSHEET_ID"

생성 결과:

.clasp.json - 프로젝트 설정 (scriptId, parentId)
appsscript.json - Apps Script 매니페스트

1.4 Push / Pull 워크플로우

# 로컬 코드 → Google 서버 업로드
clasp push
clasp push --force   # 변경 없어도 강제 업로드

# Google 서버 코드 → 로컬 다운로드
clasp pull

# 스크립트 에디터 열기
clasp open

1.5 배포 (API 실행용)

appsscript.json에 executionApi 추가 후:

{
  "executionApi": {
    "access": "MYSELF"
  }
}

clasp push
clasp deploy --description "설명"
clasp run functionName   # 원격 실행 (권한 설정 필요)

1.6 제한 사항

clasp login의 OAuth scope는 drive.file로 제한됨
clasp이 생성한 파일만 API로 접근 가능 (기존 시트 데이터 직접 읽기 불가)
clasp run은 배포 + 권한 설정이 필요하여 설정이 번거로움
시트 데이터를 읽으려면 Apps Script 함수를 push 후 시트에서 실행하고 로그를 확인해야 함

2. gws (Google Workspace CLI)

Google Workspace 전체 API를 커맨드라인에서 사용하는 도구. 시트 데이터를 직접 읽고 쓸 수 있다.

GitHub: https://github.com/googleworkspace/cli

2.1 설치

npm install -g @googleworkspace/cli

2.2 인증

방법 A: gcloud CLI가 있는 경우

gws auth setup      # GCP 프로젝트 + OAuth 클라이언트 자동 생성
gws auth login -s sheets   # Sheets 권한으로 로그인

방법 B: 수동 OAuth 설정 (gcloud 없는 경우)

https://console.cloud.google.com 접속
프로젝트 선택 또는 생성
API 및 서비스 > 라이브러리 에서 Google Sheets API 활성화
API 및 서비스 > 사용자 인증 정보 > + 사용자 인증 정보 만들기 > OAuth 클라이언트 ID
- 애플리케이션 유형: 데스크톱 앱
- 이름: gws-cli
JSON 다운로드 → ~/.config/gws/client_secret.json 에 저장
로그인:

gws auth login -s sheets

2.3 시트 데이터 읽기/쓰기

# 스프레드시트 메타데이터 조회 (시트 목록 등)
gws sheets spreadsheets get --params '{"spreadsheetId": "SPREADSHEET_ID"}'

# 특정 범위 데이터 읽기
gws sheets spreadsheets.values get --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "시트이름!A1:Z100"}'

# 데이터 쓰기
gws sheets spreadsheets.values update \
  --params '{"spreadsheetId": "SPREADSHEET_ID", "range": "시트이름!A1", "valueInputOption": "USER_ENTERED"}' \
  --json '{"values": [["값1", "값2"]]}'

2.4 장점

시트 데이터를 터미널에서 직접 읽기/쓰기 가능
JSON 출력으로 스크립트 파이프라인에 활용 용이
Google Discovery Service 기반으로 모든 Workspace API 지원

3. 방식 비교

항목	clasp	gws CLI	Sheets API (직접)
용도	Apps Script 코드 관리	시트 데이터 읽기/쓰기	프로그래밍 방식 접근
시트 데이터 직접 접근	불가 (Script 통해 간접)	가능	가능
인증 복잡도	낮음 (`clasp login`)	중간 (OAuth 설정 필요)	높음 (서비스 계정 등)
자동화	Script push/deploy	CLI 명령 조합	코드 작성 필요
추천 상황	시트에 함수/메뉴 추가	데이터 조회/수정	복잡한 자동화

4. 현재 프로젝트 설정

대상 시트: 1FFoOU20EFhOBucfC3RoX6EPUHVdxRnkA4v1-DQtXnzU
clasp 인증 계정: minsung.kim.hanmaceng@gmail.com
Script ID: 1hdzYOiAg3WSvr3lzIX4ebgFro5zunXhMxcEqmugBWB7SegK3Xn7kKR6H
gws CLI: 설치 완료 (v0.22.5), OAuth 인증 미완료 (client_secret.json 필요)

4.4 KiB Raw Permalink Blame History