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

# GoogleDriveFilesystem

単一の Google Drive フォルダーにファイルを保存します。各ディレクトリは設定されたルート配下の Drive フォルダーに対応し、パスには POSIX の規則（例：`/notes/todo.txt`）を使用します。インターフェースの詳細は、[WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/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` の**2つの値**だけです。

##### サービスアカウントを設定する

1. [Google Cloud Console](https://console.cloud.google.com/) を開き、プロジェクトを選択または作成します。
2. **APIs とサービス > ライブラリ**に移動し、**Google Drive API** を検索して**有効にする**を選択します。
3. **APIs とサービス > 認証情報**に移動し、**認証情報を作成 > サービス アカウント**を選択してフォームを入力します。ロールは空欄で構いません。Drive の権限は IAM ロールではなく、フォルダーの共有によって付与されます。
4. 新しいサービスアカウントを開き、**キー**タブで**鍵を追加 > 新しい鍵を作成 > JSON**を選択します。ブラウザーに JSON キーファイルがダウンロードされます。
5. JSON ファイルから `client_email` の値をコピーします。Drive フォルダーはこのアドレスと共有します。

##### Drive フォルダーをサービスアカウントと共有する

サービスアカウントは独立した Google ID です。明示的に共有するまで、Drive 内の内容には一切アクセスできません。

1. [Google Drive](https://drive.google.com/) で対象フォルダーを開きます。
2. **共有**を選択します。
3. サービスアカウントの `client_email` アドレスを貼り付けます。
4. 読み書きする場合は**編集者**、読み取り専用の場合は**閲覧者**にロールを設定し、**送信**を選択します。
5. URL からフォルダー ID をコピーします。`https://drive.google.com/drive/folders/<folderId>` の `/folders/` より後の部分です。

> **警告:** サービスアカウントは、通常の「マイドライブ」フォルダーにファイルを作成できません。サービスアカウントには個人用 Drive の保存容量がないため、作成するファイルは保存容量を持つ主体が所有する必要があります。個人用 Drive フォルダーを共有しただけの場合、読み取り操作は動作しますが、書き込みは容量エラーで失敗します。
>
> 書き込みアクセスには、フォルダーを**共有ドライブ**（旧 Team Drive）内に配置し、その共有ドライブのメンバーとしてサービスアカウントを追加します。共有ドライブは、サービスアカウントが作成するファイルに必要な保存容量を提供します。
>
> 個人用 Drive フォルダーに対する読み取り専用のワークロードには、この制限はありません。

##### Filesystem を設定する

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`): この Filesystem インスタンスの一意な識別子。 (Default: `` `google-drive:${folderId}` ``)

**readOnly** (`boolean`): true の場合、すべての書き込み操作を禁止します。 (Default: `false`)

**instructions** (`InstructionsOption`): Tool の説明へ返すデフォルトの指示を上書きします。

## プロパティ

**id** (`string`): Filesystem インスタンスの識別子。

**name** (`string`): Provider 名（'GoogleDriveFilesystem'）。

**provider** (`string`): Provider 識別子（'google-drive'）。

**readOnly** (`boolean | undefined`): Filesystem が読み取り専用モードかどうか。

## メソッド

GoogleDriveFilesystem は [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を実装し、標準の Filesystem メソッドをすべて提供します。

- `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`）のみを使用します。追加の依存関係は不要です。