메인 콘텐츠로 건너뛰기
Service account 인증은 서버 간에 Google Sheets에 접근할 때 가장 적합합니다. 사용자 조작이 필요 없고, 애플리케이션 자체가 스프레드시트를 조작합니다. 자동화 작업이나 백그라운드 잡에 적합합니다.

​
적용 상황

  • 서버 간 접근 — 사용자 조작 없이 앱이 Sheets에 접근
  • 자동화 시스템 — 백그라운드 잡, cron 작업, 자동 리포트
  • 고정 스프레드시트 — 특정 스프레드시트를 제어
  • 프로덕션 환경 — 사용자 동의 플로우 없이 안정적으로 동작

​
사전 요구 사항

  • Google Cloud Console 프로젝트
  • Google Sheets API와 Google Drive API 활성화
  • 프로젝트 관리자 권한

​
설정

1

Google Cloud 프로젝트 생성

  1. Google Cloud Console에 접속합니다.
  2. 새 프로젝트를 생성하거나 기존 프로젝트를 선택합니다.
  3. 프로젝트 ID를 메모해 둡니다.
2

필요한 API 활성화

  1. APIs & Services > Library로 이동합니다.
  2. 다음 API를 검색 및 활성화합니다:
    • Google Sheets API
    • Google Drive API
3

Service account 생성

  1. APIs & Services > Credentials로 이동합니다.
  2. Create Credentials > Service Account를 클릭합니다.
  3. Service account 세부 정보를 입력합니다:
    • Service account name: 설명적인 이름 (예: “Laravel Sheets App”)
    • Service account ID: 자동 생성
    • Description: 선택 사항
  4. Create and Continue를 클릭합니다.
  5. 선택 항목 두 섹션은 모두 건너뛰고 Done을 클릭합니다.
4

Service account 키 생성

  1. Credentials 페이지에서 생성한 Service account를 클릭합니다.
  2. Keys 탭으로 이동합니다.
  3. Add Key > Create new key를 클릭합니다.
  4. 키 형식으로 JSON을 선택합니다.
  5. Create를 클릭합니다.
  6. JSON 파일이 자동으로 다운로드됩니다.
5

JSON 파일 저장

  1. 다운로드한 JSON 파일을 storage/app/으로 옮깁니다.
  2. google-service-account.json으로 이름을 변경합니다.
  3. 중요: .gitignore에 추가해 버전 관리에서 제외합니다.
# .gitignore에 추가
storage/app/google-service-account.json
6

.env 파일 설정

.env에 다음을 추가합니다:
GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
7

config/google.php에서 스코프 설정

'scopes' => [
    \Google\Service\Sheets::SPREADSHEETS,
    \Google\Service\Drive::DRIVE,
],
8

스프레드시트 공유

각 Google Sheets 스프레드시트에 대해:
  1. Google Sheets에서 엽니다.
  2. 공유 버튼을 클릭합니다.
  3. JSON 파일의 client_email 필드를 복사합니다.
  4. 이 이메일 주소에 공유합니다 (예: [email protected]).
  5. 권한을 선택합니다:
    • 뷰어 — 읽기 전용
    • 편집자 — 읽기/쓰기
    • 소유자 — 전체 액세스 (권장하지 않음)

​
사용 방법

설정이 완료되면 Service account가 자동으로 사용됩니다. 액세스 토큰 설정은 필요 없습니다. 
use Revolution\Google\Sheets\Facades\Sheets;

// Service account가 자동으로 사용됨
$values = Sheets::spreadsheet('your-spreadsheet-id')
    ->sheet('Sheet1')
    ->all();

// 스프레드시트 이름으로 참조 (Drive API 접근 필요)
$values = Sheets::spreadsheetByTitle('My Spreadsheet')
    ->sheet('Sheet1')
    ->all();

​
보안 모범 사례

​
1. Service account 권한 제한

  • 필요한 스프레드시트만 공유합니다.
  • 소유자가 아닌 편집자를 사용합니다.
  • 정기적으로 접근 권한을 감사합니다.

​
2. 키의 안전한 보관

  • Service account 키는 버전 관리에 포함하지 않습니다.
  • .gitignore로 확실히 제외합니다.
  • 프로덕션 환경에서는 web root 외부의 안전한 위치에 저장합니다.
  • 정기적으로 키를 로테이션합니다.

​
3. 프로덕션 환경 배포

추가 보안 대책:
  • JSON 키를 web root 외부의 안전한 위치에 저장합니다.
  • 환경별로 다른 Service account를 사용합니다 (개발·스테이징·프로덕션).
  • Google Cloud Console에서 이러한 계정의 사용 현황을 모니터링합니다.
  • 의심스러운 활동을 로그 기록·알림합니다.

​
환경 변수 레퍼런스

변수설명예시
GOOGLE_SERVICE_ENABLEDService account 인증 활성화true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATIONJSON 파일 경로storage/app/google-service-account.json

​
고급 설정

​
JSON 문자열을 환경 변수에 저장

JSON 파일을 별도의 파일로 저장하는 대신, JSON 문자열을 환경 변수로 저장할 수 있습니다. GitHub Actions 같은 CI/CD 환경에 적합합니다. Step 1: .env에 JSON 문자열 추가 
GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION='{"type": "service_account", "project_id": "your-project-id", ...}'
Step 2: config/google.php에서 JSON 문자열 디코드 
// config/google.php
'service' => [
    'enable' => env('GOOGLE_SERVICE_ENABLED', false),
    'file' => json_decode(env('GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION', ''), true),
],
이 방법을 사용하면 파일을 별도로 저장할 필요 없이 CI/CD 파이프라인의 환경 변수만으로 완전히 관리할 수 있습니다.

​
트러블슈팅

​
자주 발생하는 에러

「caller does not have permission」에러
  • 스프레드시트가 Service account 이메일 주소로 공유되어 있는지 확인하세요.
  • 쓰기 작업의 경우 권한이 편집자 이상인지 확인하세요.
「File not found」에러
  • JSON 파일 경로가 올바른지 확인하세요.
  • 파일이 존재하고 웹 서버가 읽을 수 있는지 확인하세요.
「API not enabled」에러
  • Google Cloud Console에서 Google Sheets API와 Google Drive API가 활성화되어 있는지 확인하세요.
  • API 활성화 후 몇 분 정도 기다리세요.
「Invalid credentials」에러
  • JSON 키 파일이 유효하며 손상되지 않았는지 확인하세요.
  • Service account가 삭제되거나 비활성화되지 않았는지 확인하세요.
  • 프로젝트 ID가 Google Cloud 프로젝트와 일치하는지 확인하세요.

​
설정 테스트

Service account 설정을 확인하는 테스트 라우트: 
// routes/web.php
Route::get('/test-sheets', function () {
    try {
        $sheets = Sheets::spreadsheetList();
        return response()->json([
            'status' => 'success',
            'message' => 'Service account 인증이 정상 동작합니다',
            'spreadsheet_count' => count($sheets)
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'status' => 'error',
            'message' => $e->getMessage()
        ]);
    }
});
이 테스트 라우트에 접속해 Service account 인증이 올바르게 설정되어 있는지 확인합니다.
마지막 수정일 2026년 7월 13일

관련 항목

Google Sheets API for LaravelOAuth 2.0 인증 - Google Sheets API for LaravelLaravel Socialite (소셜 인증)커스텀 인증 가드 구현Laravel Sanctum (API 토큰 인증)