Trabalhando com S3 e armazenamento em nuvem em JavaScript (Node.js) — biblioteca @aws-sdk/client-s3

Biblioteca @aws-sdk/client-s3 para trabalhar com S3 e armazenamento em nuvem em Node.js

Os armazenamentos em nuvem tornaram-se parte essencial dos aplicativos web modernos. Eles permitem armazenar e transferir arquivos de qualquer tamanho, garantindo alta disponibilidade e escalabilidade. No ecossistema JavaScript (Node.js), uma das bibliotecas mais populares para trabalhar com armazenamentos compatíveis com S3 é a @aws-sdk/client-s3 — o SDK oficial da AWS de terceira geração.

Esta biblioteca fornece um conjunto completo de métodos para interagir com Amazon S3, bem como com qualquer armazenamento de objetos compatível com S3 (por exemplo, MinIO, DigitalOcean Spaces, Yandex Object Storage, VK Cloud). Neste artigo, abordaremos a instalação, configuração e operações principais: upload, download, exclusão e listagem de objetos.

Instalação e importação

Para começar, instale o pacote via npm:

npm install @aws-sdk/client-s3

Após a instalação, importe as classes necessárias para o seu projeto:

const { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, ListObjectsV2Command } = require('@aws-sdk/client-s3');

Configuração do cliente S3

Para conectar ao S3, você precisa criar uma instância do cliente, especificando a região, as chaves de acesso e, se necessário, o endpoint (para armazenamentos de terceiros).

const s3Client = new S3Client({  region: 'ru-central1', // região do seu armazenamento  endpoint: 'https://storage.yandexcloud.net', // para Yandex Object Storage  credentials: {    accessKeyId: 'YOUR_ACCESS_KEY',    secretAccessKey: 'YOUR_SECRET_KEY'  }});

Se você estiver usando o Amazon S3 diretamente, não é necessário especificar o endpoint — o SDK o determinará automaticamente com base na região. Para testes locais com MinIO, especifique endpoint: 'http://localhost:9000' e forcePathStyle: true.

Operações principais com S3

1. Upload de arquivo (PutObject)

Para fazer upload de um arquivo para o bucket, use o comando PutObjectCommand. Os dados podem ser passados como string, buffer ou stream.

const uploadFile = async (bucketName, key, body) => {  try {    const command = new PutObjectCommand({      Bucket: bucketName,      Key: key,      Body: body,      ContentType: 'text/plain' // opcional    });    const response = await s3Client.send(command);    console.log('Arquivo enviado:', response);  } catch (err) {    console.error('Erro no upload:', err);  }};

// Exemplo de usouploadFile('my-bucket', 'hello.txt', 'Olá, mundo!');

2. Download de arquivo (GetObject)

Para obter um objeto do armazenamento, use GetObjectCommand. Os dados são retornados como um stream, que pode ser convertido em string ou buffer.

const downloadFile = async (bucketName, key) => {  try {    const command = new GetObjectCommand({      Bucket: bucketName,      Key: key    });    const response = await s3Client.send(command);    const str = await response.Body.transformToString('utf-8');    console.log('Conteúdo do arquivo:', str);    return str;  } catch (err) {    console.error('Erro no download:', err);  }};

// Exemplo de usodownloadFile('my-bucket', 'hello.txt');

3. Exclusão de arquivo (DeleteObject)

A exclusão de um objeto é feita com o comando DeleteObjectCommand.

const deleteFile = async (bucketName, key) => {  try {    const command = new DeleteObjectCommand({      Bucket: bucketName,      Key: key    });    await s3Client.send(command);    console.log('Arquivo excluído');  } catch (err) {    console.error('Erro na exclusão:', err);  }};

deleteFile('my-bucket', 'hello.txt');

4. Listagem de objetos (ListObjectsV2)

Para listar todos os objetos em um bucket, use o