> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# Google드라이브파일 시스템

단일 Google 드라이브 폴더에 파일을 저장합니다. 각 디렉터리는 구성된 루트 아래의 Drive 폴더에 매핑되며 경로는 POSIX 의미 체계를 사용합니다(예:`/notes/todo.txt`). 인터페이스에 대한 자세한 내용은 다음을 참조하세요.[Workspace파일 시스템 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/filesystem).

## 설치

**npm**:

```bash
npm install @mastra/google-drive
```

**pnpm**:

```bash
pnpm add @mastra/google-drive
```

**Yarn**:

```bash
yarn add @mastra/google-drive
```

**Bun**:

```bash
bun add @mastra/google-drive
```

## 용법

Workspace에 `GoogleDriveFilesystem`을 추가하고 Agent에 할당합니다:

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const workspace = new Workspace({
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
  }),
})

const agent = new Agent({
  id: 'drive-agent',
  name: 'Drive Agent',
  model: 'openai/gpt-5-mini',
  workspace,
})
```

### 입증

다음 인증 옵션 중 하나를 제공하십시오.

- **`accessToken`**: 미리 획득한 OAuth 액세스 토큰입니다. 인증된 ID와 공유된 폴더를 토큰이 볼 수 있도록 `https://www.googleapis.com/auth/drive` 범위를 사용합니다.
- **`getAccessToken`**: 토큰을 반환하는 콜백입니다. 토큰을 외부에서 새로 고칠 때 유용합니다.
- **`serviceAccount`**: Google 서비스 계정입니다. 서비스 계정 이메일과 대상 폴더를 공유합니다.

#### 서비스 계정

서비스 계정 인증은 백엔드 Agent에 권장되는 옵션입니다. 사용자 동의 흐름과 토큰 새로 고침 처리가 필요하지 않습니다. 서비스 계정 JSON 키 파일에서 **두 값**, 즉 `client_email`과 `private_key`만 있으면 됩니다.

##### 서비스 계정 설정

1. [Google Cloud Console](https://console.cloud.google.com/)을 열고 프로젝트를 선택하거나 생성합니다.
2. **APIs & Services > Library**로 이동하여 **Google Drive API**를 검색한 다음 **Enable**을 선택합니다.
3. **APIs & Services > Credentials**로 이동하여 **Create credentials > Service account**를 선택하고 양식을 작성합니다. Drive 권한은 IAM 역할이 아니라 폴더 공유를 통해 부여되므로 역할은 비워 두어도 됩니다.
4. 새 서비스 계정을 열고 **Keys** 탭에서 **Add key > Create new key > JSON**을 선택합니다. 브라우저에서 JSON 키 파일을 다운로드합니다.
5. JSON 파일에서 `client_email` 값을 복사합니다. 이 주소와 Drive 폴더를 공유합니다.

##### 서비스 계정과 드라이브 폴더 공유

서비스 계정은 자체 Google ID입니다. 명시적으로 공유하기 전까지는 드라이브에서 아무 것도 볼 수 없습니다.

1. [Google Drive](https://drive.google.com/)에서 대상 폴더를 엽니다.
2. **Share**를 선택합니다.
3. 서비스 계정의 `client_email` 주소를 붙여넣습니다.
4. 역할을 **Editor**(읽기 및 쓰기용) 또는 **Viewer**(읽기 전용 액세스용)로 설정합니다. **Send**를 선택합니다.
5. URL에서 폴더 ID를 복사합니다. `https://drive.google.com/drive/folders/<folderId>`에서 `/folders/` 다음 부분입니다.

> **경고:** 서비스 계정은 표준 '내 드라이브' 폴더에 파일을 만들 수 없습니다. 서비스 계정에는 개인 드라이브 스토리지 할당량이 없으므로 서비스 계정이 생성하는 모든 파일은 할당량 보유 주체가 소유해야 합니다. 개인 드라이브 폴더만 공유하는 경우 읽기 작업은 작동하지만 할당량 오류로 인해 쓰기가 실패합니다.
>
> 쓰기 액세스가 필요하면 폴더를 **shared drive**(이전 명칭: Team Drive)로 이동하고 서비스 계정을 해당 공유 드라이브의 구성원으로 추가합니다. 공유 드라이브는 서비스 계정이 생성한 파일에 필요한 저장용량 할당량을 제공합니다. 개인 드라이브 폴더에 대한 읽기 전용 작업에는 이러한 제한이 없습니다.

##### 파일 시스템 구성

JSON 파일의 `client_email`과 `private_key`를 환경에 복사합니다:

```bash
GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
# Wrap the value in quotes — the key contains newlines that must be preserved.
GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"
```

```typescript
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const filesystem = new GoogleDriveFilesystem({
  folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
  serviceAccount: {
    clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
    privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
  },
})
```

전체 JSON 파일을 복사하거나 `project_id`, `client_id`, `private_key_id`, `token_uri` 같은 다른 필드를 전달할 필요는 **없습니다**. 이러한 필드는 사용되지 않습니다. `clientEmail`과 `privateKey`만 필수입니다. `privateKeyId`, `scopes`, `subject`는 선택 사항입니다. `scopes`의 기본값은 `['https://www.googleapis.com/auth/drive']`이며, 서비스 계정이 자신과 공유된 폴더를 보는 데 필요한 범위입니다. 더 제한적인 `drive.file` 범위는 애플리케이션이 직접 생성한 파일에만 액세스를 허용하므로 서비스 계정과 공유된 폴더에서는 `404 Not Found`가 반환됩니다. `GoogleDriveFilesystem`은 서명하기 전에 `privateKey` 문자열을 자동으로 정규화합니다. JSON으로 래핑된 값에서 이스케이프된 따옴표를 포함해 바깥쪽 따옴표를 제거하고, 리터럴 `\n` 시퀀스를 실제 줄바꿈으로 변환합니다. 또한 `\r\n` 줄 끝을 정규화하고 후행 쉼표를 제거합니다. 따라서 `.env` 로더가 값을 처리하는 방식과 관계없이 키가 작동합니다.

##### 문제 해결

- **`404 File not found: <folderId>`**: 서비스 계정에 폴더 액세스 권한이 없습니다. 폴더가 올바른 `client_email` 주소와 공유되었으며 폴더 ID가 URL과 일치하는지 확인하세요.
- **쓰기 시 `storageQuotaExceeded`**: 해당 폴더가 개인 "내 드라이브"에 있습니다. 폴더를 공유 드라이브로 이동하고 서비스 계정을 구성원으로 추가하세요.
- **`error:1E08010C:DECODER routines::unsupported`**: `privateKey` 값의 형식이 잘못되었습니다. 값에 전체 PEM 블록이 포함되어 있고 줄바꿈이 유지되는지 확인하세요(리터럴 `\n`도 사용할 수 있음).

### 읽기 전용 모드

쓰기 작업(`writeFile`, `appendFile`, `deleteFile`, `copyFile`, `moveFile`, `mkdir`, `rmdir`)을 차단하려면 `readOnly: true`를 전달합니다.

```typescript
const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})
```

## 생성자 매개변수

**folderId** (`string`): Workspace 루트 역할을 하는 Google Drive 폴더의 ID입니다. 모든 경로는 이 폴더 내부에서 해석됩니다.

**accessToken** (`string`): 폴더에 액세스할 수 있는 OAuth 액세스 토큰입니다.

**getAccessToken** (`() => string | Promise<string>`): 새 OAuth 액세스 토큰을 반환하는 콜백입니다. 인증이 필요한 모든 요청에서 호출됩니다.

**serviceAccount** (`{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }`): OAuth 2.0 JWT 흐름을 통해 액세스 토큰을 발급하는 데 사용되는 서비스 계정 자격 증명입니다.

**id** (`string`): 이 파일 시스템 인스턴스의 고유 식별자 (Default: `` `google-drive:${folderId}` ``)

**readOnly** (`boolean`): true이면 모든 쓰기 작업이 차단됩니다. (Default: `false`)

**instructions** (`InstructionsOption`): Tool 설명에 반환되는 기본 지침을 재정의합니다.

## 속성

**id** (`string`): 파일 시스템 인스턴스 식별자

**name** (`string`): Provider 이름('GoogleDriveFilesystem')

**provider** (`string`): Provider 식별자('google-drive')

**readOnly** (`boolean | undefined`): 파일 시스템이 읽기 전용 모드인지 여부

## 행동 양식

GoogleDriveFilesystem은 다음을 구현합니다.[WorkspaceFilesystem interface](https://mastra.zisheng.pro/ko/reference/workspace/filesystem), providing all standard filesystem methods:

- `readFile(path, options?)` - 파일 콘텐츠 다운로드
- `writeFile(path, content, options?)` - 파일 업로드 또는 덮어쓰기
- `appendFile(path, content)` - 파일을 읽고 다시 업로드하여 콘텐츠 추가
- `deleteFile(path, options?)` - 파일 삭제
- `copyFile(src, dest, options?)` - Drive `files.copy` API를 사용하여 파일 복사
- `moveFile(src, dest, options?)` - 상위 폴더를 변경하여 폴더 간에 파일 이동
- `mkdir(path, options?)` - 폴더 생성
- `rmdir(path, options?)` - 폴더 제거
- `readdir(path, options?)` - 폴더 콘텐츠 목록 조회(`recursive` 및 `extension` 필터링 지원)
- `stat(path)` - 파일 또는 폴더의 Drive 메타데이터 반환
- `exists(path)` - 파일 또는 폴더가 존재하는지 확인

## 메모

- Google Drive에서는 폴더에 이름이 같은 여러 파일을 둘 수 있습니다. `GoogleDriveFilesystem`은 첫 번째로 일치하는 항목을 선택하여 경로를 해석하므로 경로 기반 조회를 사용할 때는 각 폴더 내에서 이름을 고유하게 유지하세요.
- `writeFile`은 `recursive`가 설정되지 않았거나(기본값) `true`인 경우 상위 폴더를 자동으로 생성합니다. 상위 폴더가 이미 존재하도록 요구하려면 `recursive: false`를 설정합니다.
- `WriteOptions`의 `expectedMtime`이 적용됩니다. 저장된 `modifiedTime`이 다르면 낙관적 동시성을 지원하기 위해 `StaleFileError`와 함께 쓰기가 거부됩니다.
- 이 Provider는 내장 `fetch`를 통해 Drive REST 엔드포인트(`https://www.googleapis.com/drive/v3` 및 `https://www.googleapis.com/upload/drive/v3`)를 사용합니다. 추가 종속성은 필요하지 않습니다.