メインコンテンツへ移動

GCSFilesystem

Google Cloud Storage にファイルを保存します。インターフェースの詳細は、WorkspaceFilesystem インターフェースを参照してください。

インストール
インストールへの直接リンク

npm install @mastra/gcs

使用方法
使用方法への直接リンク

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

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 を使用する
Application Default Credentials を使用するへの直接リンク

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

import { GCSFilesystem } from '@mastra/gcs'

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

Application Default Credentials（ADC）は、次の順序で認証情報を自動検出します。

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

キーファイルのパスを使用する
キーファイルのパスを使用するへの直接リンク

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

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
= Auto-generated
この Filesystem インスタンスの一意な識別子。

displayName?:

string
UI に表示するわかりやすい名前。

icon?:

FilesystemIcon
UI に表示するアイコンの識別子。

description?:

string
UI に表示する Filesystem の短い説明。

readOnly?:

boolean
= false
true の場合、すべての書き込み操作を禁止します。

endpoint?:

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

プロパティ
プロパティへの直接リンク

id:

string
Filesystem インスタンスの識別子。

name:

string
Provider 名（'GCSFilesystem'）。

provider:

string
Provider 識別子（'gcs'）。

bucket:

string
GCS バケット名。

readOnly:

boolean | undefined
Filesystem が読み取り専用モードかどうか。

メソッド
メソッドへの直接リンク

GCSFilesystem は WorkspaceFilesystem インターフェースを実装し、標準の 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()
initへの直接リンク

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

await filesystem.init()

getInfo()
getinfoへの直接リンク

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

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

getMountConfig()
getmountconfigへの直接リンク

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

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

E2B Sandbox にマウントする
E2B Sandbox にマウントするへの直接リンク

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

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 リファレンスを参照してください。

On this page