GCSFilesystem

Stocke des fichiers dans Google Cloud Storage. Pour plus de détails sur l'interface, consultez l'interface WorkspaceFilesystem.

Installation

npm

npm install @mastra/gcs

pnpm

pnpm add @mastra/gcs

Yarn

yarn add @mastra/gcs

Bun

bun add @mastra/gcs

Utilisation

Ajoutez un GCSFilesystem à un Workspace et attribuez-le à un 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,
})

Utilisation des Application Default Credentials

Si votre application s'exécute sur Google Cloud ou si la CLI gcloud est configurée, vous pouvez omettre les identifiants :

import { GCSFilesystem } from '@mastra/gcs'

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

Les Application Default Credentials (ADC) détectent automatiquement les identifiants dans l'ordre suivant :

1. Variable d'environnement GOOGLE_APPLICATION_CREDENTIALS (chemin vers un fichier de clé de compte de service)
2. Compte de service par défaut lors de l'exécution sur GCP (Compute Engine, Cloud Run, GKE, etc.)
3. Identifiants utilisateur provenant de gcloud auth application-default login (pour le développement local)

Utilisation du chemin d'un fichier de clé

Vous pouvez également fournir le chemin d'un fichier de clé de compte de service :

import { GCSFilesystem } from '@mastra/gcs'

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

Paramètres du constructeur

bucket:

string

Nom du bucket GCS

projectId?:

string

Identifiant du projet GCS. Obligatoire lors de l'utilisation d'identifiants de compte de service.

credentials?:

object | string

Objet JSON contenant la clé du compte de service ou chemin vers le fichier de clé. S'il n'est pas fourni, les Application Default Credentials sont utilisées.

prefix?:

string

Préfixe facultatif pour toutes les clés (agit comme un sous-répertoire)

id?:

string

= Généré automatiquement

Identifiant unique de cette instance de système de fichiers

displayName?:

string

Nom d'affichage lisible dans l'interface utilisateur

icon?:

FilesystemIcon

Identifiant de l'icône dans l'interface utilisateur

description?:

string

Courte description de ce système de fichiers dans l'interface utilisateur

readOnly?:

boolean

= false

Lorsque cette option vaut true, toutes les opérations d'écriture sont bloquées

endpoint?:

string

URL personnalisée du point de terminaison de l'API. Utilisée pour le développement local avec des émulateurs.

Propriétés

id:

string

Identifiant de l'instance du système de fichiers

name:

string

Nom du Provider ('GCSFilesystem')

provider:

string

Identifiant du Provider ('gcs')

bucket:

string

Nom du bucket GCS

readOnly:

boolean | undefined

Indique si le système de fichiers est en mode lecture seule

Méthodes

GCSFilesystem implémente l'interface WorkspaceFilesystem et fournit toutes les méthodes standard d'un système de fichiers :

• readFile(path, options?) - Lit le contenu d'un fichier
• writeFile(path, content, options?) - Écrit du contenu dans un fichier
• appendFile(path, content) - Ajoute du contenu à un fichier
• deleteFile(path, options?) - Supprime un fichier
• copyFile(src, dest, options?) - Copie un fichier
• moveFile(src, dest, options?) - Déplace ou renomme un fichier
• mkdir(path, options?) - Crée un répertoire
• rmdir(path, options?) - Supprime un répertoire
• readdir(path, options?) - Répertorie le contenu d'un répertoire
• exists(path) - Vérifie si un chemin existe
• stat(path) - Récupère les métadonnées d'un fichier ou d'un répertoire

init()

Initialise le système de fichiers. Vérifie l'accès au bucket et les identifiants.

await filesystem.init()

getInfo()

Renvoie les métadonnées de cette instance de système de fichiers.

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

getMountConfig()

Renvoie la configuration de montage pour les Sandboxes prenant en charge le montage de ce type de système de fichiers.

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

Montage dans des Sandboxes E2B

GCSFilesystem peut être monté dans des Sandboxes E2B afin de rendre le bucket accessible comme un répertoire local :

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' }),
})

Consultez la référence d'E2BSandbox pour en savoir plus sur le montage.

Voir aussi

• Interface WorkspaceFilesystem
• Référence d'ArchilFilesystem
• Référence de S3Filesystem
• Référence d'AzureBlobFilesystem
• Référence d'E2BSandbox
• Présentation de Workspace