From ae439452ee3d2b2607c5bcc45010c0a72186f163 Mon Sep 17 00:00:00 2001 From: minsung Date: Mon, 13 Apr 2026 11:52:43 +0900 Subject: [PATCH] Add Google Sheets integration guide (clasp + gws CLI) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes #2 - clasp: 설치, 인증, 기존 시트 바인딩, push/pull 워크플로우, 제한사항 - gws CLI: 설치, OAuth 설정(자동/수동), 시트 데이터 읽기/쓰기 - 세 가지 방식(clasp, gws, Sheets API) 비교표 - 현재 프로젝트 설정 정보 Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/google-sheets-guide.md | 147 ++++++++++++++++++++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 docs/google-sheets-guide.md diff --git a/docs/google-sheets-guide.md b/docs/google-sheets-guide.md new file mode 100644 index 0000000..e6099cb --- /dev/null +++ b/docs/google-sheets-guide.md @@ -0,0 +1,147 @@ +# Google Sheets 로컬 연동 가이드 + +로컬 환경에서 Google Sheets를 다루는 방법을 정리한다. + +## 1. clasp (Google Apps Script CLI) + +Apps Script 코드를 로컬에서 작성하고 Google 시트에 배포하는 도구. + +### 1.1 설치 + +```bash +npm install -g @google/clasp +``` + +### 1.2 인증 + +```bash +clasp login +``` + +- 브라우저가 열리면 Google 계정으로 인증 +- 사전 조건: https://script.google.com/home/usersettings 에서 Apps Script API **ON** + +### 1.3 기존 시트에 Apps Script 바인딩 + +```bash +# --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 워크플로우 + +```bash +# 로컬 코드 → Google 서버 업로드 +clasp push +clasp push --force # 변경 없어도 강제 업로드 + +# Google 서버 코드 → 로컬 다운로드 +clasp pull + +# 스크립트 에디터 열기 +clasp open +``` + +### 1.5 배포 (API 실행용) + +`appsscript.json`에 executionApi 추가 후: + +```json +{ + "executionApi": { + "access": "MYSELF" + } +} +``` + +```bash +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 설치 + +```bash +npm install -g @googleworkspace/cli +``` + +### 2.2 인증 + +#### 방법 A: gcloud CLI가 있는 경우 + +```bash +gws auth setup # GCP 프로젝트 + OAuth 클라이언트 자동 생성 +gws auth login -s sheets # Sheets 권한으로 로그인 +``` + +#### 방법 B: 수동 OAuth 설정 (gcloud 없는 경우) + +1. https://console.cloud.google.com 접속 +2. 프로젝트 선택 또는 생성 +3. **API 및 서비스 > 라이브러리** 에서 **Google Sheets API** 활성화 +4. **API 및 서비스 > 사용자 인증 정보 > + 사용자 인증 정보 만들기 > OAuth 클라이언트 ID** + - 애플리케이션 유형: 데스크톱 앱 + - 이름: `gws-cli` +5. JSON 다운로드 → `~/.config/gws/client_secret.json` 에 저장 +6. 로그인: + +```bash +gws auth login -s sheets +``` + +### 2.3 시트 데이터 읽기/쓰기 + +```bash +# 스프레드시트 메타데이터 조회 (시트 목록 등) +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 필요)