디렉터리 버킷의 객체 이름 바꾸기

디렉터리 버킷의 객체 이름 바꾸기 (Renaming objects in directory buckets)

RenameObject 작업을 사용하면 S3 Express One Zone 스토리지 클래스를 사용하는 디렉터리 버킷의 기존 객체 이름을 데이터 이동 없이 원자적으로(atomically) 바꿀 수 있어요. 같은 디렉터리 버킷 안에서 기존 객체의 이름을 소스(source)로, 새 이름을 대상(destination)으로 지정해 객체 이름을 바꿔요. RenameObject API 작업은 슬래시(/) 구분 문자로 끝나는 객체에는 성공하지 않아요. 자세한 내용은 Amazon S3 객체 이름 짓기 를 참고하세요.

출처: 문서

본문

RenameObject 작업은 객체 크기와 관계없이 보통 밀리초 단위로 완료돼요. 이 기능은 로그 파일 관리, 미디어 처리, 데이터 분석 같은 애플리케이션의 속도를 높여줘요. 또한 RenameObject는 스토리지 클래스, 암호화 유형, 생성 일자, 마지막 수정 일자, 체크섬 속성 등 모든 객체 메타데이터 속성을 보존해요.

참고

RenameObject는 S3 Express One Zone 스토리지 클래스에 저장된 객체에만 지원돼요.

RenameObject 작업에 대한 접근 권한을 부여하려면 CreateSession 작업을 사용한 세션 기반 권한 부여를 권장해요. 구체적으로는 버킷 정책이나 ID 기반 정책에서 디렉터리 버킷에 s3express:CreateSession 권한을 부여해요. 그런 다음 디렉터리 버킷에서 CreateSession API를 호출해 세션 토큰을 얻어요. 요청 헤더에 세션 토큰을 넣으면 이 작업에 API 요청을 보낼 수 있어요. 세션 토큰이 만료된 뒤에는 다시 CreateSession API를 호출해 새 세션 토큰을 생성해 사용하면 돼요. AWS CLI와 AWS SDK는 세션을 만들고 관리하며, 세션이 만료될 때 서비스 중단을 막기 위해 세션 토큰도 자동으로 갱신해요. 권한 부여에 대한 자세한 내용은 Amazon S3 API Reference의 CreateSession 을 참고하고, Zonal 엔드포인트 API 작업은 CreateSession으로 Zonal 엔드포인트 API 작업 권한 부여 에서 알아보세요.

기존 객체를 덮어쓰고 싶지 않다면 RenameObject 요청에 값이 '*'인 If-None-Match 조건부 헤더를 추가할 수 있어요. 객체 이름이 이미 존재하면 Amazon S3는 412 Precondition Failed 오류를 반환해요. 자세한 내용은 Amazon S3 API Reference의 RenameObject 를 참고하세요.

RenameObject는 AWS CloudTrail에 기록되는 Zonal 엔드포인트 API 작업(객체 수준 또는 데이터 플레인 작업)이에요. CloudTrail을 사용해 디렉터리 버킷의 객체에서 수행된 RenameObject 작업에 대한 정보를 수집할 수 있어요. 자세한 내용은 디렉터리 버킷용 AWS CloudTrail 로깅 과 디렉터리 버킷용 CloudTrail 로그 파일 예제 를 참고하세요.

S3 Express One Zone은 RenameObject를 지원하는 유일한 스토리지 클래스이며, S3 Express One Zone에서 PUT, COPY, POST, LIST 요청과 동일한 요금(1,000건당)으로 과금돼요. 자세한 내용은 Amazon S3 요금 을 참고하세요.

객체 이름 바꾸기

디렉터리 버킷의 객체 이름을 바꾸려면 Amazon S3 콘솔, AWS CLI, AWS SDK, REST API, 또는 Mountpoint for Amazon S3(버전 1.19.0 이상)를 사용할 수 있어요.

디렉터리 버킷의 객체 이름 바꾸기

AWS Management Console에 로그인하고 https://console.aws.amazon.com/s3/ 에서 Amazon S3 콘솔을 엽니다.
탐색 창에서 Buckets(버킷)을 선택한 뒤 Directory buckets 탭을 선택합니다. 이름을 바꿀 객체가 들어 있는 Amazon S3 디렉터리 버킷으로 이동합니다.
이름을 바꿀 객체의 체크박스를 선택합니다.
Actions(작업) 메뉴에서 Rename object(객체 이름 바꾸기)를 선택합니다.
New object name(새 객체 이름) 상자에 객체의 새 이름을 입력합니다. 기존 객체와 같은 이름을 지정하면 작업이 실패하고 Amazon S3는 412 Precondition Failed 오류를 반환해요. 객체 키 이름의 길이는 1,024바이트를 초과할 수 없어요. 객체 이름에 포함된 접두사도 총 길이에 포함돼요.
Rename object를 선택합니다. Amazon S3가 객체 이름을 바꿔요.

AWS CLI 예제

rename-object 예제들은 AWS CLI로 객체 이름을 바꾸는 방법을 보여줘요. 실행 시 사용자 입력 자리표시자는 직접 채워 넣어야 합니다.

다음 예제는 소스 객체의 ETag에 대한 조건부 검사로 객체 이름을 바꾸는 방법을 보여줘요.

aws s3api rename-object \                                    
    --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 \
    --key new-file.txt \
    --rename-source original-file.txt \
    --source-if-match "\"a1b7c3d2e5f6\""

이 명령은 다음을 수행해요.

amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 original-file.txt를 new-file.txt로 이름을 바꿔요.
소스 객체의 ETag가 "a1b7c3d4e5f6"와 일치할 때만 이름을 바꿔요.

ETag가 일치하지 않으면 작업이 412 Precondition Failed 오류로 실패해요.

다음 예제는 새로 지정한 객체 이름에 대한 조건부 검사로 이름을 바꾸는 방법을 보여줘요.

aws s3api rename-object \
    --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 \
    --key new-file.txt \
    --rename-source amzn-s3-demo-bucket--usw2-az1--x-s3/original-file.txt \
    --destination-if-none-match "\"e5f3g7h8i9j0\""

이 명령은 다음을 수행해요.

amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 original-file.txt를 new-file.txt로 이름을 바꿔요.
객체가 존재하고 객체의 ETag가 "e5f3g7h8i9j0"와 일치하지 않을 때만 이름 바꾸기 작업을 수행해요.

새로 지정한 이름과 일치하는 ETag를 가진 객체가 이미 존재하면 작업이 412 Precondition Failed 오류로 실패해요.

Java 예제 (AWS SDK for Java)

AWS SDK for Java로 객체 이름을 바꿀 수 있어요. 실행 시 사용자 입력 자리표시자는 직접 채워 넣어야 합니다.

다음 예제는 AWS SDK for Java로 RenameObjectRequest를 만드는 방법을 보여줘요.

String key = "key";
String newKey = "new-key";
String expectedETag = "e5f3g7h8i9j0";
RenameObjectRequest renameRequest = RenameObjectRequest.builder()
    .bucket(amzn-s3-demo-bucket--usw2-az1--x-s3)
    .key(newKey)
    .renameSource(key)
    .destinationIfMatch(e5f3g7h8i9j0)
    .build();

이 코드는 다음을 수행해요.

amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 "key"를 "new-key"로 이름을 바꾸는 요청을 만들어요.
객체의 ETag가 "e5f3g7h8i9j0"와 일치할 때만 이름을 바꾸는 조건을 포함해요.
ETag가 일치하지 않거나 객체가 존재하지 않으면 작업이 실패해요.

다음 예제는 none-match 조건으로 RenameObjectRequest를 만드는 방법을 보여줘요.

String key = "key";
String newKey = "new-key";
String noneMatchETag = "e5f3g7h8i9j0";
RenameObjectRequest renameRequest = RenameObjectRequest.builder()
    .bucket(amzn-s3-demo-bucket--usw2-az1--x-s3)
    .key(newKey)
    .renameSource(key)
    .destinationIfNoneMatch(noneMatchETag)
    .build();

이 코드는 다음을 수행해요.

amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 "key"를 "new-key"로 이름을 바꾸는 요청을 만들어요.
.destinationIfNoneMatch(noneMatchETag)를 사용해 대상 객체의 ETag가 "e5f3g7h8i9j0"와 일치하지 않을 때만 이름을 바꾸는 조건을 포함해요.

새로 지정한 이름이면서 지정한 ETag를 가진 객체가 존재하면 작업은 412 Precondition Failed 오류로 실패해요.

Python 예제 (Boto3)

AWS SDK for Python(Boto3)으로 객체 이름을 바꿀 수 있어요. 실행 시 사용자 입력 자리표시자는 직접 채워 넣어야 합니다.

다음 예제는 AWS SDK for Python(Boto3)으로 객체 이름을 바꾸는 방법을 보여줘요.

def basic_rename(bucket, source_key, destination_key):
    try:
        s3.rename_object(
            Bucket=amzn-s3-demo-bucket--usw2-az1--x-s3,
            Key=destination_key,
            RenameSource=f"{source_key}"
        )
        print(f"Successfully renamed {source_key} to {destination_key}")
    except ClientError as e:
        print(f"Error renaming object: {e}")

이 코드는 다음을 수행해요.

amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 source_key를 destination_key로 이름을 바꿔요.
객체 이름 바꾸기가 성공하면 성공 메시지를, 실패하면 오류 메시지를 출력해요.

다음 예제는 SourceIfMatch와 DestinationIfNoneMatch 조건으로 객체 이름을 바꾸는 방법을 보여줘요.

def rename_with_conditions(bucket, source_key, destination_key, source_etag, dest_etag):
    try:
        s3.rename_object(
            Bucket=amzn-s3-demo-bucket--usw2-az1--x-s3,
            Key=destination_key,
            RenameSource=f"{amzn-s3-demo-bucket--usw2-az1--x-s3}/{source_key}",
            SourceIfMatch=source_ETag,
            DestinationIfNoneMatch=dest_ETag
        )
        print(f"Successfully renamed {source_key} to {destination_key} with conditions")
    except ClientError as e:
        print(f"Error renaming object: {e}")

이 코드는 다음을 수행해요.

조건부 이름 바꾸기 작업을 수행하고 SourceIfMatch와 DestinationIfNoneMatch 두 조건을 적용해요. 이 두 조건을 조합하면 객체가 수정되지 않았고 새로 지정한 이름의 객체가 아직 존재하지 않는다는 것을 보장해요.
amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 source_key를 destination_key로 이름을 바꿔요.
이름 바꾸기가 성공하면 성공 메시지를, 실패하거나 조건이 충족되지 않으면 오류 메시지를 출력해요.

Rust 예제 (SDK for Rust)

SDK for Rust로 객체 이름을 바꿀 수 있어요. 실행 시 사용자 입력 자리표시자는 직접 채워 넣어야 합니다.

다음 예제는 SDK for Rust로 amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 객체 이름을 바꾸는 방법을 보여줘요.

async fn basic_rename_example(client: &Client) -> Result> {
    let response = client
        .rename_object()
        .bucket(" amzn-s3-demo-bucket--usw2-az1--x-s3")
        .key("new-name.txt")  // New name/path for the object
        .rename_source("old-name.txt")  // Original object name/path
        .send()
        .await?;
    Ok(())
}

이 코드는 다음을 수행해요.

amzn-s3-demo-bucket--usw2-az1--x-s3 디렉터리 버킷에서 "old-name.txt"를 "new-name.txt"로 이름을 바꾸는 요청을 만들어요.
잠재적인 오류를 처리하기 위해 Result 타입을 반환해요.

REST API

REST 요청을 보내 객체 이름을 바꿀 수도 있어요. 자세한 내용은 Amazon S3 API Reference의 RenameObject 를 참고하세요.

Mountpoint for Amazon S3(버전 1.19.0 이상)는 S3 Express One Zone에서 객체 이름 바꾸기를 지원해요. Mountpoint에 대한 자세한 내용은 Mountpoint 사용하기 를 참고하세요.

디렉터리 버킷의 객체 이름 바꾸기

디렉터리 버킷의 객체 이름 바꾸기 (Renaming objects in directory buckets)

본문

객체 이름 바꾸기

더 알아보기 (Learn more)