# 디렉터리 버킷의 객체 이름 바꾸기
`RenameObject` 작업을 사용하면 데이터 이동 없이 S3 Express One Zone 스토리지 클래스를 사용하는 디렉터리 버킷의 기존 객체 이름을 원자적으로 바꿀 수 있습니다. 기존 객체의 이름을 소스로 지정하고 객체의 새 이름을 동일한 디렉터리 버킷 내의 대상으로 지정하여 객체의 이름을 바꿀 수 있습니다. 슬래시(`/`) 구분 기호 문자로 끝나는 객체에서는 `RenameObject` API 작업이 성공하지 못합니다. 자세한 내용은 [Amazon S3 객체 이름 지정](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html)을 참조하세요.
`RenameObject` 작업은 일반적으로 객체 크기와 관계없이 몇 밀리초 내에 완료됩니다. 이 기능은 로그 파일 관리, 미디어 처리 및 데이터 분석과 같은 애플리케이션을 가속화합니다. 또한 `RenameObject`는 스토리지 클래스, 암호화 유형, 생성 날짜, 마지막 수정 날짜 및 체크섬 속성을 포함한 모든 객체 메타데이터 속성을 보존합니다.
**참고**
`RenameObject`는 S3 Express One Zone 스토리지 클래스에 저장된 객체에 대해서만 지원됩니다.
`RenameObject` 작업에 대한 액세스 권한을 부여하려면 세션 기반 권한 부여를 위해 `CreateSession` 작업을 사용하는 것이 좋습니다. 특히 버킷 정책 또는 ID 기반 정책에서 디렉터리 버킷에 `s3express:CreateSession` 권한을 부여합니다. 그런 다음, 디렉터리 버킷에서 `CreateSession` API 직접 호출을 수행하여 세션 토큰을 가져옵니다. 요청 헤더에 세션 토큰을 포함하여 이 작업에 API 요청을 할 수 있습니다. 세션 토큰이 만료되면 다른 `CreateSession` API 직접 호출을 수행하여 사용할 새 세션 토큰을 생성합니다. AWS CLI 및 AWS SDK는 세션이 만료될 때 서비스 중단을 방지하기 위해 세션 토큰을 자동으로 새로 고치는 등 세션을 생성하고 관리합니다. 권한 부여에 대한 자세한 내용은 *Amazon S3 API 참조*의 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html) 섹션을 참조하세요. 영역 엔드포인트 API 작업에 대한 자세한 내용은 [`CreateSession`을 사용하여 영역 엔드포인트 API 작업 권한 부여](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-create-session.html)를 참조하세요.
기존 객체를 덮어쓰지 않으려면 `RenameObject` 요청에 `‘*’` 값과 함께 `If-None-Match` 조건부 헤더를 추가하면 됩니다. 객체 이름이 이미 있는 경우 Amazon S3에서 `412 Precondition Failed` 오류를 반환합니다. 자세한 내용은 **Amazon S3 API 참조의 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html) 섹션을 참조하세요.
`RenameObject`는 AWS CloudTrail에 로깅되는 영역 엔드포인트 API 작업(객체 수준 또는 데이터 플레인 작업)입니다. CloudTrail을 사용하여 디렉터리 버킷의 객체에 대해 수행된 `RenameObject` 작업에 대한 정보를 수집할 수 있습니다. 자세한 내용은 [AWS CloudTrail로 디렉터리 버킷에 로그인](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone-logging.html) 및 [디렉터리 버킷에 대한 CloudTrail 로그 파일 예제](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-log-files.html)를 참조하세요.
S3 Express One Zone은 `RenameObject`를 지원하는 유일한 스토리지 클래스이며, S3 Express One Zone에서의 `PUT`, `COPY`, `POST` 및 `LIST` 요청과 가격이 동일합니다(요청 1,000개당). 자세한 내용은 [Amazon S3 요금](https://aws.amazon.com/s3/pricing/)을 참조하세요.
## 객체 이름 바꾸기
디렉터리 버킷의 객체 이름을 바꾸려면 Amazon S3 콘솔, AWS CLI, AWS SDK, REST API 또는 Mountpoint for Amazon S3(버전 1.19.0 이상)를 사용하면 됩니다.
### S3 콘솔 사용
**디렉터리 버킷의 객체 이름을 바꾸는 방법**
1. AWS Management Console에 로그인한 후 [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/)에서 S3 콘솔을 엽니다.
1. 탐색 창에서 **버킷**을 선택하고 **디렉터리 버킷** 탭을 선택합니다. 이름을 바꿀 객체가 포함된 Amazon S3 디렉터리 버킷으로 이동합니다.
1. 이름을 바꾸려는 객체의 확인란을 선택합니다.
1. **작업** 메뉴에서 **객체 이름 바꾸기**를 선택합니다.
1. **새 객체 이름** 상자에 객체의 새 이름을 입력합니다.
**참고**
기존 객체와 동일한 객체 이름을 지정하면 작업이 실패하고 Amazon S3가 `412 Precondition Failed` 오류를 반환합니다. 객체 키 이름 길이는 1,024바이트를 초과할 수 없습니다. 객체 이름에 포함된 접두사는 총 길이에 포함됩니다.
1. **객체 이름 바꾸기**를 선택합니다. 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` 오류와 함께 작업이 실패합니다.
### AWS SDK 사용
------
#### [ 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가 일치하지 않거나 객체가 존재하지 않으면 작업이 실패합니다.
다음 예시에서는 AWS SDK for Java를 사용하여 일치하지 않는 조건으로 `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*'로 바꾸는 요청을 생성합니다.
+ 대상 객체의 ETag가 '*e5f3g7h8i9j0*'과 일치하지 않는 경우에만 이름 바꾸기가 발생하도록 하는 `.destinationIfNoneMatch(noneMatchETag)`를 사용하는 조건을 포함합니다.
새 이름이 지정되어 있고 ETag가 지정된 객체가 이미 있는 경우 `412 Precondition Failed` 오류와 함께 작업이 실패합니다.
------
#### [ SDK for Python ]
SDK for Python을 사용하여 객체의 이름을 바꿀 수 있습니다. 이러한 예시를 사용하려면 *사용자 입력 자리 표시자*를 실제 정보로 대체하세요.
다음 예시에서는 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\$1key*에서 *destination\$1key*로 바꿉니다.
+ 객체 이름 바꾸기에 성공하면 성공 메시지를 인쇄하고 실패하면 오류 메시지를 인쇄합니다.
다음 예시에서는 AWS SDK for Python(Boto3)을 사용하여 `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\$1key*에서 *destination\$1key*로 바꿉니다.
+ 객체 이름 바꾸기에 성공하면 성공 메시지를 인쇄하고 실패하거나 조건이 충족되지 않으면 오류 메시지를 인쇄합니다.
------
#### [ 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<(), Box> {
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.tx*'에서 '*new-name.txt*'로 바꾸는 요청을 생성합니다.
+ 잠재적 오류를 처리할 `Result` 유형을 반환합니다.
------
### REST API 사용
객체 이름을 바꾸기 위해 REST 요청을 보낼 수 있습니다. 자세한 내용은 **Amazon S3 API 참조의 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html) 섹션을 참조하세요.
### Mountpoint for Amazon S3 사용
1.19.0 버전부터 Mountpoint for Amazon S3는 S3 Express One Zone에서 객체 이름 바꾸기를 지원합니다. Mountpoint에 대한 자세한 내용은 [Mountpoint 작업](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mountpoint.html)을 참조하세요.