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

# GCSFilesystem

Google Cloud Storage にファイルを保存します。インターフェースの詳細は、[WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)を参照してください。

## インストール

**npm**:

```bash
npm install @mastra/gcs
```

**pnpm**:

```bash
pnpm add @mastra/gcs
```

**Yarn**:

```bash
yarn add @mastra/gcs
```

**Bun**:

```bash
bun add @mastra/gcs
```

## 使用方法

Workspace に `GCSFilesystem` を追加して Agent に割り当てます。

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'

const workspace = new Workspace({
  filesystem: new GCSFilesystem({
    bucket: 'my-gcs-bucket',
    projectId: 'my-project-id',
    credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})
```

### Application Default Credentials を使用する

Google Cloud 上で実行する場合や `gcloud` CLI が設定済みの場合は、認証情報を省略できます。

```typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  // Uses Application Default Credentials automatically
})
```

[Application Default Credentials（ADC）](https://cloud.google.com/docs/authentication/application-default-credentials)は、次の順序で認証情報を自動検出します。

1. 環境変数 `GOOGLE_APPLICATION_CREDENTIALS`（サービスアカウントキーファイルへのパス）
2. GCP（Compute Engine、Cloud Run、GKE など）で実行する場合のデフォルトサービスアカウント
3. `gcloud auth application-default login` で取得したユーザー認証情報（ローカル開発向け）

### キーファイルのパスを使用する

サービスアカウントキーファイルへのパスを渡すこともできます。

```typescript
import { GCSFilesystem } from '@mastra/gcs'

const filesystem = new GCSFilesystem({
  bucket: 'my-gcs-bucket',
  projectId: 'my-project-id',
  credentials: '/path/to/service-account-key.json',
})
```

## コンストラクターパラメーター

**bucket** (`string`): GCS バケット名。

**projectId** (`string`): GCS プロジェクト ID。サービスアカウント認証情報を使用する場合は必須です。

**credentials** (`object | string`): サービスアカウントキーの JSON オブジェクトまたはキーファイルへのパス。未指定の場合は Application Default Credentials を使用します。

**prefix** (`string`): すべてのキーに付加する任意のプレフィックス（サブディレクトリとして機能します）。

**id** (`string`): この Filesystem インスタンスの一意な識別子。 (Default: `Auto-generated`)

**displayName** (`string`): UI に表示するわかりやすい名前。

**icon** (`FilesystemIcon`): UI に表示するアイコンの識別子。

**description** (`string`): UI に表示する Filesystem の短い説明。

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

**endpoint** (`string`): カスタム API エンドポイント URL。エミュレーターを使用するローカル開発向けです。

## プロパティ

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

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

**provider** (`string`): Provider 識別子（'gcs'）。

**bucket** (`string`): GCS バケット名。

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

## メソッド

GCSFilesystem は [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?)` - ファイルをコピーします
- `moveFile(src, dest, options?)` - ファイルを移動または名前変更します
- `mkdir(path, options?)` - ディレクトリを作成します
- `rmdir(path, options?)` - ディレクトリを削除します
- `readdir(path, options?)` - ディレクトリの内容を一覧表示します
- `exists(path)` - パスが存在するか確認します
- `stat(path)` - ファイルまたはディレクトリのメタデータを取得します

### `init()`

Filesystem を初期化し、バケットへのアクセスと認証情報を検証します。

```typescript
await filesystem.init()
```

### `getInfo()`

この Filesystem インスタンスのメタデータを返します。

```typescript
const info = filesystem.getInfo()
// { id: '...', name: 'GCSFilesystem', provider: 'gcs', status: 'ready' }
```

### `getMountConfig()`

この種類の Filesystem のマウントに対応する Sandbox 向けに、マウント設定を返します。

```typescript
const config = filesystem.getMountConfig()
// { type: 'gcs', bucket: 'my-bucket', ... }
```

## E2B Sandbox にマウントする

GCSFilesystem を E2B Sandbox にマウントすると、バケットへローカルディレクトリとしてアクセスできます。

```typescript
import { Workspace } from '@mastra/core/workspace'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new GCSFilesystem({
      bucket: 'my-gcs-bucket',
      projectId: 'my-project-id',
      credentials: JSON.parse(process.env.GCS_SERVICE_ACCOUNT_KEY),
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

マウントの詳細は、[E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)を参照してください。

## 関連項目

- [WorkspaceFilesystem インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/filesystem)
- [ArchilFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/archil-filesystem)
- [S3Filesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/s3-filesystem)
- [AzureBlobFilesystem リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/azure-blob-filesystem)
- [E2BSandbox リファレンス](https://mastra.zisheng.pro/ja/reference/workspace/e2b-sandbox)
- [Workspace の概要](https://mastra.zisheng.pro/ja/docs/workspace/overview)