Travailler avec S3 et les stockages cloud en Node.js : la bibliothèque @aws-sdk/client-s3

Travailler avec S3 et les stockages cloud en JavaScript (Node.js)

S3 (Simple Storage Service) est le standard de facto pour les stockages d'objets dans le cloud. Que vous utilisiez Amazon S3, Yandex Object Storage, Mail.ru Cloud Storage ou une solution locale comme MinIO, l'API reste unifiée. Dans cet article, nous allons voir comment se connecter aux stockages compatibles S3 depuis Node.js à l'aide du SDK officiel AWS v3.

Qu'est-ce que S3 et pourquoi en avez-vous besoin ?

S3 permet de stocker un nombre illimité de fichiers (objets) dans des « buckets ». Chaque objet possède une clé unique (chemin) et des métadonnées. Les principaux cas d'utilisation sont :

\n
• Stockage de fichiers utilisateur (avatars, documents)
\n
• Sauvegardes de bases de données et de journaux
\n
• Fichiers statiques pour les applications web (images, CSS, JS)
\n
• Stockage de fichiers multimédias (vidéos, audio)
\n

Installation et configuration d'AWS SDK v3

À partir de la version 3, le SDK AWS est devenu modulaire. Pour travailler avec S3, il suffit d'installer un seul paquet :

npm install @aws-sdk/client-s3

Vous aurez également besoin de variables d'environnement avec les clés d'accès. Il est préférable de les stocker dans un fichier .env :

AWS_ACCESS_KEY_ID=your_access_key\nAWS_SECRET_ACCESS_KEY=your_secret_key\nAWS_REGION=ru-central1\nS3_ENDPOINT=https://storage.yandexcloud.net\nS3_BUCKET=my-bucket

Connexion à un stockage compatible S3

Créons un client S3 avec un endpoint personnalisé (pour Yandex Object Storage, MinIO et autres) :

const { S3Client } = require('@aws-sdk/client-s3');\nrequire('dotenv').config();\n\nconst s3Client = new S3Client({\n  region: process.env.AWS_REGION,\n  endpoint: process.env.S3_ENDPOINT,\n  credentials: {\n    accessKeyId: process.env.AWS_ACCESS_KEY_ID,\n    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,\n  },\n  forcePathStyle: true, // important pour MinIO et certains stockages compatibles S3\n});\n\nmodule.exports = s3Client;

Opérations principales avec S3

1. Téléchargement d'un fichier (PutObject)

Téléchargeons un fichier à partir d'un buffer ou d'un flux :

const { PutObjectCommand } = require('@aws-sdk/client-s3');\nconst fs = require('fs');\n\nasync function uploadFile(filePath, key) {\n  const fileContent = fs.readFileSync(filePath);\n  \n  const command = new PutObjectCommand({\n    Bucket: process.env.S3_BUCKET,\n    Key: key,\n    Body: fileContent,\n    ContentType: 'image/png', // spécifiez le bon type MIME\n  });\n\n  try {\n    const response = await s3Client.send(command);\n    console.log('Fichier téléchargé :', response.$metadata.httpStatusCode);\n    return `https://storage.yandexcloud.net/${process.env.S3_BUCKET}/${key}`;\n  } catch (err) {\n    console.error('Erreur de téléchargement :', err);\n  }\n}

2. Téléchargement d'un fichier (GetObject)

Récupérons un objet et sauvegardons-le localement :

const { GetObjectCommand } = require('@aws-sdk/client-s3');\nconst fs = require('fs');\nconst stream = require('stream');\nconst { promisify } = require('util');\nconst pipeline = promisify(stream.pipeline);\n\nasync function downloadFile(key, destinationPath) {\n  const command = new GetObjectCommand({\n    Bucket: process.env.S3_BUCKET,\n    Key: key,\n  });\n\n  try {\n    const response = await s3Client.send(command);\n    const writeStream = fs.createWriteStream(destinationPath);\n    await pipeline(response.Body, writeStream);\n    console.log('Fichier téléchargé :', destinationPath);\n  } catch (err) {\n    console.error('Erreur de téléchargement :', err);\n  }\n}

3. Obtention de la liste des objets (ListObjectsV2)

Utile pour afficher les fichiers dans le bucket :

const { ListObjectsV2Command } = require('@aws-sdk/client-s3');\n\nasync function listFiles(prefix = '') {\n  const command = new ListObjectsV2Command({\n    Bucket: process.env.S3_BUCKET,\n    Prefix: prefix,\n    MaxKeys: 100,\n  });\n\n  try {\n    const response = await s3