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

# S3Filesystem

Stocke des fichiers dans Amazon S3 ou dans des services de stockage compatibles S3 tels que Cloudflare R2, MinIO, DigitalOcean Spaces et Tigris. Pour plus de détails sur l'interface, consultez [l'interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

## Installation

**npm**:

```bash
npm install @mastra/s3
```

**pnpm**:

```bash
pnpm add @mastra/s3
```

**Yarn**:

```bash
yarn add @mastra/s3
```

**Bun**:

```bash
bun add @mastra/s3
```

## Utilisation

Ajoutez un `S3Filesystem` à un Workspace et attribuez-le à un Agent :

```typescript
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
})

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

### Chaîne de Providers d'identifiants AWS

Lorsqu'aucun identifiant n'est fourni, `S3Filesystem` utilise la chaîne de Providers d'identifiants par défaut du SDK AWS. Celle-ci détecte automatiquement les identifiants à partir des variables d'environnement, des fichiers de configuration `~/.aws`, des identifiants de conteneurs ECS, des profils d'instances EC2 et d'autres sources standard.

```typescript
import { S3Filesystem } from '@mastra/s3'

// SDK discovers credentials from the environment automatically
const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
})
```

Transmettez une fonction de Provider d'identifiants pour actualiser automatiquement les identifiants. Cela est utile pour les déploiements sur ECS ou Lambda, ainsi que lors de l'utilisation de SSO/AssumeRole, où les identifiants temporaires expirent et doivent être renouvelés.

Installez le package de Providers d'identifiants du SDK AWS lorsque vous appelez directement `fromNodeProviderChain()` :

**npm**:

```bash
npm install @aws-sdk/credential-providers
```

**pnpm**:

```bash
pnpm add @aws-sdk/credential-providers
```

**Yarn**:

```bash
yarn add @aws-sdk/credential-providers
```

**Bun**:

```bash
bun add @aws-sdk/credential-providers
```

```typescript
import { S3Filesystem } from '@mastra/s3'
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  credentials: fromNodeProviderChain(),
})
```

Les fonctions de Provider s'appliquent uniquement aux appels d'API de `S3Filesystem`. Lors du montage du système de fichiers dans une Sandbox E2B, la configuration de montage prend uniquement en charge les valeurs statiques `accessKeyId`, `secretAccessKey` et `sessionToken` ; l'actualisation des identifiants doit donc être gérée en dehors du montage.

### Cloudflare R2

```typescript
import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-r2-bucket',
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
})
```

### MinIO

```typescript
import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  endpoint: 'http://localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
})
```

### Tigris

```typescript
import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'auto',
  endpoint: 'https://t3.storage.dev',
  accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID,
  secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY,
  forcePathStyle: false,
})
```

Tigris utilise un adressage de type hôte virtuel ; `forcePathStyle` doit donc être défini sur `false` (la valeur par défaut est `true` lorsqu'un endpoint personnalisé est fourni). Créez les identifiants depuis le [tableau de bord Tigris](https://console.tigris.dev/). Les clés d'accès sont préfixées par `tid_` et les secrets par `tsec_`.

## Paramètres du constructeur

**bucket** (`string`): Nom du bucket S3

**region** (`string`): Région AWS (utilisez 'auto' pour R2)

**credentials** (`AwsCredentialIdentity | AwsCredentialIdentityProvider`): Identifiants AWS ou fonction de Provider d'identifiants. Accepte des identifiants statiques ou un Provider qui les actualise automatiquement (par exemple, fromNodeProviderChain() de @aws-sdk/credential-providers). Prend le pas sur accessKeyId/secretAccessKey/sessionToken. Lorsque toutes les options d'identifiants sont omises, la chaîne de Providers d'identifiants par défaut du SDK est utilisée.

**accessKeyId** (`string`): Identifiant de clé d'accès AWS. Lorsqu'il est omis avec secretAccessKey et credentials, la chaîne de Providers d'identifiants par défaut du SDK est utilisée.

**secretAccessKey** (`string`): Clé d'accès secrète AWS. Lorsqu'elle est omise avec accessKeyId et credentials, la chaîne de Providers d'identifiants par défaut du SDK est utilisée.

**sessionToken** (`string`): Token de session AWS pour les identifiants temporaires statiques. Utilisez-le avec accessKeyId/secretAccessKey uniquement lorsque vous transmettez manuellement un ensemble complet d'identifiants temporaires. Pour l'actualisation automatique des identifiants SSO, AssumeRole ou de conteneur, utilisez le paramètre Provider credentials ou la chaîne de Providers d'identifiants par défaut du SDK.

**endpoint** (`string`): URL personnalisée de l’endpoint pour un stockage compatible S3 (R2, MinIO, Tigris, etc.)

**forcePathStyle** (`boolean`): Force l'utilisation d'URL de type chemin au lieu du type hôte virtuel. Obligatoire pour certains services compatibles S3 tels que MinIO. Utilise par défaut true lorsqu'un endpoint personnalisé est fourni. (Default: `true (lorsque l'endpoint est défini)`)

**prefix** (`string`): Préfixe facultatif pour toutes les clés (agit comme un sous-répertoire)

**id** (`string`): Identifiant unique de cette instance de système de fichiers (Default: `Généré automatiquement`)

**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`): Lorsque cette option vaut true, toutes les opérations d'écriture sont bloquées (Default: `false`)

## Propriétés

**id** (`string`): Identifiant de l'instance du système de fichiers

**name** (`string`): Nom du Provider ('S3Filesystem')

**provider** (`string`): Identifiant du Provider ('s3')

**bucket** (`string`): Nom du bucket S3

**readOnly** (`boolean | undefined`): Indique si le système de fichiers est en mode lecture seule

## Méthodes

S3Filesystem implémente [l'interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem) 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.

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

### `getInfo()`

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

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

### `getMountConfig()`

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

```typescript
const config = filesystem.getMountConfig()
// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }
```

## Montage dans des Sandboxes E2B

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

```typescript
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})
```

Consultez la [référence d'E2BSandbox](https://mastra.zisheng.pro/fr/reference/workspace/e2b-sandbox) pour en savoir plus sur le montage.

## Voir aussi

- [Interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem)
- [Référence d'ArchilFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/archil-filesystem)
- [Référence de GCSFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/gcs-filesystem)
- [Référence d'AzureBlobFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/azure-blob-filesystem)
- [Référence d'E2BSandbox](https://mastra.zisheng.pro/fr/reference/workspace/e2b-sandbox)
- [Présentation de Workspace](https://mastra.zisheng.pro/fr/docs/workspace/overview)