안녕하세요! 오늘은 AWS S3(Simple Storage Service)를 JavaScript로 다루는 방법에 대해 알아보겠습니다. 기존 AWS SDK v2에서 v3로 넘어오면서 많은 변화가 있었는데요. 특히, @aws-sdk/client-s3 패키지를 사용하면 S3 관련 작업을 더 효율적으로 처리할 수 있습니다.

이번 글에서는 어떻게 사용할 수 있는지와 사용 방법에 대해서 알아보겠습니다.

0️⃣ AWS SDK v3 설정 및 인증 방법

AWS S3 클라이언트를 사용하기 전에, S3에 접근할 수 있는 자격 증명을 설정해야 합니다.

1. package install

npm install @aws-sdk/client-s3

2. AWS Credentials 파일을 이용한 접근

가장 일반적인 방법으로, 로컬 환경의 ~/.aws/credentials 파일에 AWS 자격 증명을 설정합니다. AWS CLI를 통해 자격 증명을 설정했다면 이 파일이 자동으로 생성됩니다.

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY

이 방법을 사용하면 코드에서 별도의 자격 증명 설정을 할 필요가 없습니다.

import { S3Client } from "@aws-sdk/client-s3";

// 자동으로 credentials 파일을 참조하여 인증합니다.
const s3Client = new S3Client({
  region: "ap-northeast-2" // S3 버킷이 위치한 AWS 리전을 지정합니다. (예: 서울)
});

3. 코드 내에서 직접 설정하는 방법

자격 증명을 코드 내에서 직접 설정할 수도 있습니다. 이는 서버리스 환경(AWS Lambda 등)에서 유용하게 사용됩니다.

import { S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({
  region: "ap-northeast-2", // S3 버킷이 위치한 AWS 리전을 지정합니다.
  credentials: {
    accessKeyId: "YOUR_ACCESS_KEY", // AWS 계정의 액세스 키 ID
    secretAccessKey: "YOUR_SECRET_KEY", // AWS 계정의 비밀 액세스 키
  },
});

1️⃣ 파일 업로드: PutObjectCommand

S3에 파일을 업로드하는 가장 기본적인 명령입니다. 업로드할 파일의 본문, 버킷 이름, 파일 경로 및 이름을 지정합니다.

import { PutObjectCommand, S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({ region: "ap-northeast-2" });
const uploadFile = async (bucketName, key, fileBody) => {
  const command = new PutObjectCommand({
    Bucket: bucketName, // string: 파일을 업로드할 S3 버킷의 이름
    Key: key, // string: S3 버킷 내 파일의 경로와 이름 (예: 'images/profile.jpg')
    Body: fileBody, // string | Buffer | Readable | Blob 등: 업로드할 파일의 본문
    
    // 기타 옵션
    ContentType: "image/jpeg", // string: 업로드할 파일의 MIME 타입. 브라우저에서 올바르게 렌더링되도록 돕습니다.
    ACL: "public-read", // string: 객체에 대한 액세스 제어를 설정합니다. 'public-read'로 설정하면 누구나 읽을 수 있습니다.
    Metadata: { // Record<string, string> 타입의 객체
      "user-id": "12345",
      "upload-date": new Date().toISOString()
    }, // 파일과 함께 저장할 사용자 정의 메타데이터
  });

  try {
    const response = await s3Client.send(command);
    console.log("파일 업로드 성공:", response);
    return response;
  } catch (error) {
    console.error("파일 업로드 실패:", error);
    throw error;
  }
};

아래는 PutObjectCommand에 대한 파라미터 값 종류입니다.

• Bucket(string): 파일을 업로드할 S3의 버킷의 이름입니다.
• Key(string): S3 버킷 내 파일의 경로와 이름 (ex. ‘images/profile.png’)
• Body(object): 업로드할 파일의 본문 (string, Buffer, Readable, Blob)
• ContentType(string): 업로드할 파일의 MIME 타입입니다. 브라우저에서 올바르게 렌더링되도록 돕습니다. (ex. ‘image/jpeg’, ‘text/plain’, ‘application/pdf’ 등)
• ACL (Access Control List, string): 객체에 대한 액세스 권한을 제어합니다. (ex. private(기본값), public-read, authenticated-read 등)
• Metadata(Record<string, string>): 파일 내용에는 영향을 주지 않고, 파일에 대한 추가적인 정보를 key-value 형태로 저장할 수 잇는 기능입니다. 주로 애플맄이션에서 파일에 대한 추가 정보를 관리할 때 유용합니다.

2️⃣ 파일 다운로드: GetObjectCommand

S3에 저장된 파일을 다운로드합니다. GetObjectCommand를 사용하여 파일 스트림을 받아와 원하는 형식으로 변환할 수 있습니다.

import { GetObjectCommand, S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({ region: "ap-northeast-2" });
const downloadFile = async (bucketName, key) => {
  const command = new GetObjectCommand({
    Bucket: bucketName, // string: 파일을 다운로드할 S3 버킷의 이름
    Key: key, // string: 다운로드할 S3 버킷 내 파일의 경로와 이름
    
    // 기타 옵션
    IfModifiedSince: new Date("2024-01-01T00:00:00Z"), // Date 타입: 지정된 날짜 이후에 객체가 수정되었을 경우에만 다운로드합니다.
  });

  try {
    const response = await s3Client.send(command);
    // Body를 스트림으로 받아서 문자열로 변환합니다.
    const content = await response.Body.transformToString();
    console.log("파일 다운로드 성공:", content);
    return content;
  } catch (error) {
    console.error("파일 다운로드 실패:", error);
    throw error;
  }
};

아래는 GetObjectCommand에 대한 파라미터 값 종류입니다.

• Bucket(string): 파일을 업로드할 S3의 버킷의 이름입니다.
• Key(string): S3 버킷 내 파일의 경로와 이름 (ex. ‘images/profile.png’)
• IfModifiedSine(Date): 객체의 변경 여부를 확인하여 불필요한 다운로드를 방지합니다. 웹 캐시와 유사한 방식으로 동작하여 네트워크 트래픽을 절약할 수 있습니다.

3️⃣ 파일 삭제: DeleteObjectCommand

S3 버킷에서 특정 파일을 삭제합니다. DeleteObjectCommand에 버킷 이름과 키를 전달하여 사용합니다.

import { DeleteObjectCommand, S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({ region: "ap-northeast-2" });
const deleteFile = async (bucketName, key) => {
  const command = new DeleteObjectCommand({
    Bucket: bucketName, // string: 파일을 삭제할 S3 버킷의 이름
    Key: key, // string: 삭제할 S3 버킷 내 파일의 경로와 이름
    
    // 기타 옵션
    VersionId: "VERSION_ID_STRING" // string: 특정 버전의 객체를 삭제합니다. 버전 관리가 활성화된 버킷에서 사용됩니다.
  });

  try {
    const response = await s3Client.send(command);
    console.log("파일 삭제 성공:", response);
    return response;
  } catch (error) {
    console.error("파일 삭제 실패:", error);
    throw error;
  }
};

• Bucket(string): 파일을 업로드할 S3의 버킷의 이름입니다.
• Key(string): S3 버킷 내 파일의 경로와 이름 (ex. ‘images/profile.png’)
• VersionId(string): S3는 객체에 대한 버전 관리를 지원합니다. 이 옵션을 사용하면 특정 버전의 객체만 삭제할 수 있어 실수로 인한 데이터 손실을 방지합니다.

4️⃣ 파일 복사: CopyObjectCommand

기존 S3 객체를 다른 위치로 복사합니다. CopyObjectCommand에 원본 파일과 대상 파일의 정보를 전달합니다. CopySource는 버킷 이름과 파일 키를 URL 인코딩된 형태로 포함해야 합니다.

import { CopyObjectCommand, S3Client } from "@aws-sdk/client-s3";

const s3Client = new S3Client({ region: "ap-northeast-2" });
const copyFile = async (sourceBucket, sourceKey, destinationBucket, destinationKey) => {
  const command = new CopyObjectCommand({
    Bucket: destinationBucket, // string: 파일을 복사할 대상 S3 버킷의 이름
    Key: destinationKey, // string: 복사된 파일의 경로와 이름
    CopySource: `/${sourceBucket}/${sourceKey}`, // string: 원본 파일의 경로. '버킷이름/경로/파일.확장자' 형식입니다.
    
    // 기타 옵션
    ACL: "public-read", // string: 복사된 객체에 대한 액세스 제어를 설정합니다.
    MetadataDirective: "REPLACE", // string: 복사 시 메타데이터를 어떻게 처리할지 지정합니다.
    Metadata: { "new-key": "new-value" }, // Record<string, string> 타입의 객체: 복사된 객체에 적용할 새 메타데이터
  });

  try {
    const response = await s3Client.send(command);
    console.log("파일 복사 성공:", response);
    return response;
  } catch (error) {
    console.error("파일 복사 실패:", error);
    throw error;
  }
};

• Bucket(string): 파일을 업로드할 S3의 버킷의 이름입니다.
• Key(string): S3 버킷 내 파일의 경로와 이름 (ex. ‘images/profile.png’)
• ACL (Access Control List, string): 객체에 대한 액세스 권한을 제어합니다. (ex. private(기본값), public-read, authenticated-read 등)
• MetadataDirective(string): 이 옵션은 복사 시 기존 메타데이터를 유지할지, 새로 덮어쓸지 결정합니다. COPY(기본값)는 원본 객체의 메타데이터를 유지하고, REPLACE는 Metadata 옵션에 지정된 새 값으로 덮어씁니다.
• Metadata(Record<string, string>): 파일 내용에는 영향을 주지 않고, 파일에 대한 추가적인 정보를 key-value 형태로 저장할 수 잇는 기능입니다. 주로 애플맄이션에서 파일에 대한 추가 정보를 관리할 때 유용합니다.