本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 重新命名目錄儲存貯體中的物件
您可以使用 `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` 操作進行工作階段型授權。具體而言，您會將 `s3express:CreateSession` 許可權授予儲存貯體政策或身分型政策中的目錄儲存貯體。然後在目錄儲存貯體上進行 `CreateSession` API 呼叫，以取得工作階段字符。若使用您的請求標頭中的工作階段字符，您就可以對此操作提出 API 請求。工作階段字符過期後，您會進行另一個 `CreateSession` API 呼叫來產生新的工作階段字符以供使用。CLI 和 AWS SDKs AWS 將建立和管理工作階段，包括自動重新整理工作階段權杖，以避免工作階段過期時服務中斷。如需有關授權的詳細資訊，請參閱《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` 是一種區域端點 API 操作 (物件層級或資料平面操作)，會記錄到 AWS CloudTrail。您可以使用 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 個請求) 相同。如需詳細資訊，請參閱 [Simple Storage Service (Amazon S3) 定價](https://aws.amazon.com/s3/pricing/)。
## 重新命名物件
若要重新命名目錄儲存貯體中的物件，您可以使用 Amazon S3 主控台、 AWS CLI、 AWS SDKs、REST API 或 Amazon S3 掛載點 (1.19.0 版或更新版本）。
### 使用 S3 主控台
**重新命名目錄儲存貯體中的物件**
1. 登入 AWS 管理主控台 並開啟位於 https：//[https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/) 的 Amazon 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 SDKs
------
#### [ SDK for Java ]
您可以使用 適用於 Java 的 AWS SDK 來重新命名物件。若要使用這些範例，請以您自己的資訊取代{{使用者輸入預留位置}}。
下列範例示範如何使用適用於 Java `RenameObjectRequest`的 AWS 開發套件建立
```
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 不相符或物件不存在，操作將會失敗。
下列範例示範如何使用適用於 Java 的 AWS SDK 建立`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` 錯誤。
------
#### [ SDK for Python ]
您可以使用適用於 Python 的 SDK 來重新命名物件。若要使用這些範例，請以您自己的資訊取代{{使用者輸入預留位置}}。
下列範例示範如何使用適用於 Python 的 AWS SDK (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}}。
+ 如果物件的重新命名成功，則列印成功訊息；如果失敗，則列印錯誤訊息。
下列範例示範如何使用適用於 Python 的 AWS SDK (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\_key}} 重新命名為 {{destination\_key}}。
+ 如果物件的重新命名成功，則列印成功訊息；如果失敗或不符合條件，則列印錯誤訊息。
------
#### [ 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)。
### 使用適用於 Amazon S3 的掛載點
從 1.19.0 版或更新版本開始，適用於 Amazon S3 的掛載點支援在 S3 Express One Zone 中重新命名物件。如需掛載點的詳細資訊，請參閱[使用掛載點](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mountpoint.html)。