# 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 필요)