> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Service account 인증 - Google Sheets API for Laravel

> Google Sheets API의 Service account 인증을 설정합니다. 서버 간 통신에 적합합니다.

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

## 적용 상황

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

## 사전 요구 사항

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

## 설정

<Steps>
  <Step title="Google Cloud 프로젝트 생성">
    1. [Google Cloud Console](https://console.cloud.google.com/)에 접속합니다.
    2. 새 프로젝트를 생성하거나 기존 프로젝트를 선택합니다.
    3. 프로젝트 ID를 메모해 둡니다.
  </Step>

  <Step title="필요한 API 활성화">
    1. **APIs & Services** > **Library**로 이동합니다.
    2. 다음 API를 검색 및 활성화합니다:
       * **Google Sheets API**
       * **Google Drive API**
  </Step>

  <Step title="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**을 클릭합니다.
  </Step>

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

  <Step title="JSON 파일 저장">
    1. 다운로드한 JSON 파일을 `storage/app/`으로 옮깁니다.
    2. `google-service-account.json`으로 이름을 변경합니다.
    3. **중요**: `.gitignore`에 추가해 버전 관리에서 제외합니다.

    ```bash theme={null}
    # .gitignore에 추가
    storage/app/google-service-account.json
    ```
  </Step>

  <Step title=".env 파일 설정">
    `.env`에 다음을 추가합니다:

    ```env theme={null}
    GOOGLE_SERVICE_ENABLED=true
    GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION=storage/app/google-service-account.json
    ```
  </Step>

  <Step title="config/google.php에서 스코프 설정">
    ```php theme={null}
    'scopes' => [
        \Google\Service\Sheets::SPREADSHEETS,
        \Google\Service\Drive::DRIVE,
    ],
    ```
  </Step>

  <Step title="스프레드시트 공유">
    각 Google Sheets 스프레드시트에 대해:

    1. Google Sheets에서 엽니다.
    2. **공유** 버튼을 클릭합니다.
    3. JSON 파일의 `client_email` 필드를 복사합니다.
    4. 이 이메일 주소에 공유합니다 (예: `your-service-account@your-project-id.iam.gserviceaccount.com`).
    5. 권한을 선택합니다:
       * **뷰어** — 읽기 전용
       * **편집자** — 읽기/쓰기
       * **소유자** — 전체 액세스 (권장하지 않음)
  </Step>
</Steps>

## 사용 방법

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

```php theme={null}
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_ENABLED`               | Service account 인증 활성화 | `true`                                    |
| `GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION` | JSON 파일 경로             | `storage/app/google-service-account.json` |

## 고급 설정

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

JSON 파일을 별도의 파일로 저장하는 대신, JSON 문자열을 환경 변수로 저장할 수 있습니다. GitHub Actions 같은 CI/CD 환경에 적합합니다.

**Step 1: `.env`에 JSON 문자열 추가**

```env theme={null}
GOOGLE_SERVICE_ENABLED=true
GOOGLE_SERVICE_ACCOUNT_JSON_LOCATION='{"type": "service_account", "project_id": "your-project-id", ...}'
```

**Step 2: `config/google.php`에서 JSON 문자열 디코드**

```php theme={null}
// 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 설정을 확인하는 테스트 라우트:

```php theme={null}
// 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 인증이 올바르게 설정되어 있는지 확인합니다.


## Related topics

- [Google Sheets API for Laravel](/ko/packages/laravel-google-sheets/index.md)
- [OAuth 2.0 인증 - Google Sheets API for Laravel](/ko/packages/laravel-google-sheets/oauth.md)
- [Laravel Socialite (소셜 인증)](/ko/socialite.md)
- [커스텀 인증 가드 구현](/ko/advanced/custom-auth-guard.md)
- [Laravel Sanctum (API 토큰 인증)](/ko/sanctum.md)