sam-kd/구글워크스페이스서비스계정api추가방법.md

# Google Workspace 서비스 계정 API 추가 방법

## 개요
Google Cloud Speech-to-Text API를 사용하기 위한 서비스 계정 설정 방법입니다.
기존 서비스 계정이 있다면 새로 만들 필요 없이 권한만 추가하면 됩니다.

---

## 1. 서비스 계정 확인/생성

### 1-1. 기존 서비스 계정이 있는 경우
- Google Cloud Console 접속
- **IAM 및 관리자** > **서비스 계정** 메뉴로 이동
- 기존 서비스 계정 확인 (예: `vertex-ai-client`)
- **→ 기존 계정 사용 시 2단계로 이동**

### 1-2. 새 서비스 계정 생성이 필요한 경우
1. Google Cloud Console 접속
2. **IAM 및 관리자** > **서비스 계정** 메뉴로 이동
3. **서비스 계정 만들기** 클릭
4. 서비스 계정 정보 입력:
   - **이름**: 원하는 이름 입력 (예: `vertex-ai-client`)
   - **설명**: 용도 설명 (예: `vertex-ai`)
5. **만들고 계속하기** 클릭

---

## 2. 서비스 계정에 API 권한 부여

1. **IAM 및 관리자** > **서비스 계정** 메뉴로 이동
2. 사용할 서비스 계정 선택 (예: `vertex-ai-client`)
3. **권한** 탭 클릭
4. **역할 부여** 버튼 클릭
5. 역할 선택:
   - 검색창에 `Cloud Speech-to-Text API User` 입력
   - 해당 역할 선택
6. **저장** 클릭

**참고**: 다른 Google API를 사용하려면 해당 API의 사용자 역할도 추가해야 합니다.
- 예: `Cloud Translation API User`, `Cloud Text-to-Speech API User` 등

---

## 3. API 활성화 확인

1. Google Cloud Console 접속
2. **API 및 서비스** > **사용 설정된 API** 메뉴로 이동
3. 검색창에 `Cloud Speech-to-Text API` 입력
4. API가 활성화되어 있는지 확인
5. **활성화되지 않은 경우**:
   - **API 사용 설정** 버튼 클릭
   - 활성화 완료까지 대기

**참고**: 프로젝트에서 사용할 모든 Google API를 미리 활성화해야 합니다.

---

## 4. 서비스 계정 키 파일 다운로드

1. **IAM 및 관리자** > **서비스 계정** 메뉴로 이동
2. 사용할 서비스 계정 선택 (예: `vertex-ai-client`)
3. **키** 탭 클릭
4. **키 추가** > **새 키 만들기** 클릭
5. **JSON** 형식 선택
6. **만들기** 클릭
7. JSON 파일이 자동으로 다운로드됨

**중요**: 
- 이 키 파일은 한 번만 다운로드 가능합니다.
- 안전한 곳에 보관하고, 공개 저장소에 업로드하지 마세요.

---

## 5. 서버에 키 파일 저장

1. 다운로드한 JSON 파일을 서버의 `/apikey/` 디렉토리에 저장
2. 파일명: `google_service_account.json`
3. 전체 경로: `/apikey/google_service_account.json`

**예시**:
```
/apikey/
  ├── google_service_account.json  (서비스 계정 JSON 파일)
  └── google_api.txt               (API 키 - 선택사항, 폴백용)
```

---

## 6. 코드에서 사용 방법

### 6-1. PHP 코드 구조
현재 `voice_ai/process_meeting.php` 파일은 다음과 같이 동작합니다:

1. **서비스 계정 JSON 파일 우선 사용**
   - `/apikey/google_service_account.json` 파일 확인
   - 있으면 OAuth 2.0 토큰 생성하여 사용

2. **API 키 폴백**
   - 서비스 계정 파일이 없으면 `/apikey/google_api.txt` 사용
   - API 키 방식으로 인증

### 6-2. 인증 흐름
```
서비스 계정 JSON 파일 존재?
  ├─ YES → JWT 생성 → OAuth 2.0 토큰 요청 → Bearer 토큰으로 API 호출
  └─ NO  → API 키 파일 확인 → API 키로 API 호출
```

---

## 7. 테스트 방법

1. 브라우저에서 `voice_ai/index.php` 페이지 접속
2. **샘플 테스트** 버튼 클릭 (실제 녹음 없이 테스트)
3. **회의 종료 및 AI 분석 시작** 버튼 클릭
4. 결과 확인:
   - 성공: 회의록이 생성되고 목록에 표시됨
   - 실패: 오류 메시지 확인

---

## 8. 문제 해결

### 8-1. "OAuth 토큰 요청 실패" 오류
- **원인**: 서비스 계정 권한 부족 또는 API 미활성화
- **해결**:
  1. 서비스 계정에 "Cloud Speech-to-Text API User" 역할 확인
  2. 프로젝트에서 "Cloud Speech-to-Text API" 활성화 확인

### 8-2. "API key not valid" 오류
- **원인**: API 키가 유효하지 않거나 서비스 계정 JSON 파일이 없음
- **해결**:
  1. 서비스 계정 JSON 파일이 올바른 위치에 있는지 확인
  2. JSON 파일 형식이 올바른지 확인

### 8-3. "서비스 계정 개인 키를 읽을 수 없습니다" 오류
- **원인**: JSON 파일의 `private_key` 필드가 손상되었거나 형식 오류
- **해결**:
  1. JSON 파일을 다시 다운로드
  2. 파일이 UTF-8 인코딩인지 확인

---

## 9. 보안 주의사항

1. **키 파일 보안**
   - 서비스 계정 JSON 파일은 절대 공개 저장소에 업로드하지 마세요
   - `.gitignore`에 `/apikey/` 디렉토리 추가 권장
   - 파일 권한을 제한하세요 (예: `chmod 600`)

2. **권한 최소화 원칙**
   - 필요한 API 권한만 부여하세요
   - 불필요한 권한은 제거하세요

3. **키 파일 교체**
   - 키가 유출된 경우 즉시 키를 삭제하고 새로 생성하세요
   - Google Cloud Console에서 키 삭제 가능

---

## 10. 추가 API 사용 시

다른 Google API를 사용하려면:

1. **API 활성화**: API 및 서비스 > 사용 설정된 API에서 활성화
2. **권한 부여**: 서비스 계정에 해당 API 사용자 역할 추가
   - 예: `Cloud Translation API User`
   - 예: `Cloud Text-to-Speech API User`
3. **코드 수정**: 필요한 경우 코드에서 API 엔드포인트 변경

---

## 요약 체크리스트

- [ ] 서비스 계정 생성 또는 확인
- [ ] 서비스 계정에 "Cloud Speech-to-Text API User" 역할 부여
- [ ] 프로젝트에서 "Cloud Speech-to-Text API" 활성화
- [ ] 서비스 계정 JSON 키 파일 다운로드
- [ ] 서버에 `/apikey/google_service_account.json` 저장
- [ ] 파일 권한 설정 (보안)
- [ ] 테스트 실행 및 결과 확인

---

## 참고 자료

- [Google Cloud Speech-to-Text API 문서](https://cloud.google.com/speech-to-text/docs)
- [서비스 계정 인증 가이드](https://cloud.google.com/docs/authentication/production)
- [IAM 역할 및 권한](https://cloud.google.com/iam/docs/roles-overview)

---

**작성일**: 2024년
**프로젝트**: 5130 (voice_ai 시스템)