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

# GoogleDriveFilesystem

Stocke les fichiers dans un seul dossier Google Drive. Chaque répertoire correspond à un dossier Drive sous la racine configurée, et les chemins respectent la sémantique POSIX, par exemple `/notes/todo.txt`. Pour en savoir plus sur l’interface, consultez l’[interface WorkspaceFilesystem](https://mastra.zisheng.pro/fr/reference/workspace/filesystem).

## Installation

**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
```

## Utilisation

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

### Authentification

Fournissez l’une des options d’authentification suivantes :

- **`accessToken`** : token d’accès OAuth obtenu au préalable. Utilisez la portée `https://www.googleapis.com/auth/drive` afin que le token puisse voir les dossiers partagés avec l’identité authentifiée.
- **`getAccessToken`** : callback qui renvoie un token. Utile lorsque les tokens sont actualisés par un système externe.
- **`serviceAccount`** : compte de service Google. Partagez le dossier cible avec l’adresse e-mail du compte de service.

#### Compte de service

L’authentification par compte de service est l’option recommandée pour les Agents backend. Elle ne nécessite ni flux de consentement de l’utilisateur ni gestion de l’actualisation des tokens. Vous avez uniquement besoin de **deux valeurs** du fichier de clé JSON du compte de service : `client_email` et `private_key`.

##### Configurer le compte de service

1. Ouvrez la [Google Cloud Console](https://console.cloud.google.com/), puis sélectionnez ou créez un projet.
2. Accédez à **APIs & Services > Library**, recherchez **Google Drive API**, puis sélectionnez **Enable**.
3. Accédez à **APIs & Services > Credentials**, sélectionnez **Create credentials > Service account**, puis remplissez le formulaire. Le rôle peut rester vide : les permissions Drive sont accordées par le partage des dossiers, et non par les rôles IAM.
4. Ouvrez le nouveau compte de service, accédez à l’onglet **Keys**, puis sélectionnez **Add key > Create new key > JSON**. Le navigateur télécharge un fichier de clé JSON.
5. Copiez la valeur `client_email` du fichier JSON. Il s’agit de l’adresse avec laquelle vous partagez les dossiers Drive.

##### Partager le dossier Drive avec le compte de service

Le compte de service possède sa propre identité Google. Il ne peut rien voir dans Drive tant que vous ne partagez pas explicitement du contenu avec lui.

1. Ouvrez le dossier cible dans [Google Drive](https://drive.google.com/).
2. Sélectionnez **Share**.
3. Collez l’adresse `client_email` du compte de service.
4. Définissez le rôle sur **Editor** pour la lecture et l’écriture, ou sur **Viewer** pour un accès en lecture seule. Sélectionnez **Send**.
5. Copiez l’ID du dossier depuis l’URL. Il s’agit du segment qui suit `/folders/` dans `https://drive.google.com/drive/folders/<folderId>`.

> **Attention:** Les comptes de service ne peuvent pas créer de fichiers dans les dossiers standards "My Drive". Un compte de service ne possède aucun quota de stockage Drive personnel ; chaque fichier qu’il crée doit donc appartenir à une entité disposant d’un quota. Si vous partagez uniquement un dossier Drive personnel, les opérations de lecture fonctionnent, mais les écritures échouent avec une erreur de quota.
>
> Pour autoriser l’écriture, placez le dossier dans un **shared drive**, anciennement appelé Team Drive, puis ajoutez le compte de service comme membre de ce shared drive. Les shared drives fournissent le quota de stockage nécessaire aux fichiers créés par le compte de service.
>
> Les charges de travail en lecture seule sur un dossier Drive personnel ne sont pas soumises à cette restriction.

##### Configurer le système de fichiers

Copiez `client_email` et `private_key` depuis le fichier JSON dans votre environnement :

```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!,
  },
})
```

Vous ne devez **pas** copier l’intégralité du fichier JSON ni transmettre d’autres champs tels que `project_id`, `client_id`, `private_key_id` ou `token_uri`, car ils ne sont pas utilisés. Seuls `clientEmail` et `privateKey` sont requis. `privateKeyId`, `scopes` et `subject` sont facultatifs. Par défaut, `scopes` vaut `['https://www.googleapis.com/auth/drive']`, la portée nécessaire pour que le compte de service voie les dossiers partagés avec lui. La portée plus restreinte `drive.file` donne uniquement accès aux fichiers créés par l’application elle-même ; un dossier partagé avec le compte de service renverrait donc `404 Not Found`.

`GoogleDriveFilesystem` normalise automatiquement la chaîne `privateKey` avant la signature. Il supprime les guillemets qui l’entourent, y compris ceux échappés dans les valeurs encapsulées en JSON, et convertit les séquences littérales `\n` en véritables sauts de ligne. Il normalise également les fins de ligne `\r\n` et supprime toute virgule finale. La clé fonctionne quelle que soit la manière dont votre chargeur `.env` traite la valeur.

##### Résolution des problèmes

- **`404 File not found: <folderId>`** : le compte de service n’a pas accès au dossier. Vérifiez que le dossier est partagé avec l’adresse `client_email` exacte et que son ID correspond à l’URL.
- **`storageQuotaExceeded` lors de l’écriture** : le dossier se trouve dans un espace "My Drive" personnel. Déplacez-le vers un shared drive et ajoutez le compte de service comme membre.
- **`error:1E08010C:DECODER routines::unsupported`** : la valeur `privateKey` est mal formée. Vérifiez qu’elle contient l’intégralité du bloc PEM et que les sauts de ligne sont conservés (les séquences littérales `\n` conviennent).

### Mode lecture seule

Transmettez `readOnly: true` pour bloquer les opérations d’écriture (`writeFile`, `appendFile`, `deleteFile`, `copyFile`, `moveFile`, `mkdir`, `rmdir`).

```typescript
const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})
```

## Paramètres du constructeur

**folderId** (`string`): ID du dossier Google Drive qui sert de racine au Workspace. Tous les chemins sont résolus à l’intérieur de ce dossier.

**accessToken** (`string`): Token d’accès OAuth ayant accès au dossier.

**getAccessToken** (`() => string | Promise<string>`): Callback qui renvoie un nouveau token d’accès OAuth. Appelé pour chaque requête nécessitant une autorisation.

**serviceAccount** (`{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }`): Identifiants du compte de service utilisés pour générer des tokens d’accès au moyen du flux JWT OAuth 2.0.

**id** (`string`): Identifiant unique de cette instance de système de fichiers (Default: `` `google-drive:${folderId}` ``)

**readOnly** (`boolean`): Lorsque la valeur est true, toutes les opérations d’écriture sont bloquées. (Default: `false`)

**instructions** (`InstructionsOption`): Remplace les instructions par défaut renvoyées dans les descriptions des Tools.

## Propriétés

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

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

**provider** (`string`): Identifiant du Provider ('google-drive')

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

## Méthodes

GoogleDriveFilesystem 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?)` - Télécharge le contenu d’un fichier
- `writeFile(path, content, options?)` - Charge ou remplace un fichier
- `appendFile(path, content)` - Ajoute du contenu en lisant puis en rechargeant le fichier
- `deleteFile(path, options?)` - Supprime un fichier
- `copyFile(src, dest, options?)` - Copie un fichier à l’aide de l’API Drive `files.copy`
- `moveFile(src, dest, options?)` - Déplace un fichier entre des dossiers en échangeant ses parents
- `mkdir(path, options?)` - Crée un dossier
- `rmdir(path, options?)` - Supprime un dossier
- `readdir(path, options?)` - Répertorie le contenu d’un dossier (prend en charge le filtrage `recursive` et `extension`)
- `stat(path)` - Renvoie les métadonnées Drive d’un fichier ou d’un dossier
- `exists(path)` - Vérifie si un fichier ou un dossier existe

## Remarques

- Google Drive autorise plusieurs fichiers portant le même nom dans un dossier. `GoogleDriveFilesystem` résout les chemins en sélectionnant la première correspondance ; utilisez donc des noms uniques dans chaque dossier lorsque vous dépendez de la recherche par chemin.
- `writeFile` crée automatiquement les dossiers parents lorsque `recursive` n’est pas défini, ce qui est le comportement par défaut, ou vaut `true`. Définissez `recursive: false` pour exiger que le dossier parent existe déjà.
- La valeur `expectedMtime` de `WriteOptions` est respectée. Lorsque la valeur `modifiedTime` stockée diffère, l’écriture est rejetée avec `StaleFileError` afin de prendre en charge la concurrence optimiste.
- Le Provider utilise uniquement les endpoints REST de Drive (`https://www.googleapis.com/drive/v3` et `https://www.googleapis.com/upload/drive/v3`) au moyen du `fetch` intégré. Aucune dépendance supplémentaire n’est requise.