SamProject/sam-kd
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
sam-kd/구글워크스페이스서비스계정api추가방법.md
hskwon aca1767eb9 초기 커밋: 5130 레거시 시스템 
- URL 하드코딩 → .env APP_URL 기반 동적 URL로 변경
- DB 연결 하드코딩 → .env 기반으로 변경
- MySQL strict mode DATE 오류 수정
2025-12-10 20:14:31 +09:00

6.2 KiB
Raw Permalink Blame History

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 저장
  • 파일 권한 설정 (보안)
  • 테스트 실행 및 결과 확인

참고 자료

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