# Renomear objetos em buckets de diretório Usando a operação `RenameObject`, você pode renomear atomicamente um objeto existente em um bucket de diretório que usa a classe de armazenamento S3 Express One Zone, sem nenhuma movimentação de dados. Você pode renomear um objeto especificando o nome do objeto existente como origem e o novo nome como destino no mesmo bucket de diretório. A operação de API `RenameObject` não terá êxito em objetos que terminam com o caractere delimitador de barra (`/`). Para ter mais informações, consulte [Nomear objetos do Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-keys.html). A operação `RenameObject` geralmente é concluída em milissegundos, independentemente do tamanho do objeto. Esse recurso acelera determinadas aplicações, como gerenciamento de arquivos de log, processamento de mídia e data analytics. Além disso, `RenameObject` preserva todas as propriedades de metadados do objeto, como classe de armazenamento, tipo de criptografia, data de criação, data da última modificação e soma de verificação. **nota** Só é possível usar `RenameObject` com objetos armazenados na classe de armazenamento S3 Express One Zone. Para conceder acesso à operação `RenameObject`, recomendamos usar a operação `CreateSession` para autorização baseada em sessão. Mais especificamente, você concede a permissão `s3express:CreateSession` ao bucket de diretório em uma política de bucket ou em uma política baseada em identidade. Em seguida, você faz a chamada de API `CreateSession` no bucket do diretório para obter um token de sessão. Com o token de sessão no cabeçalho da solicitação, você pode fazer solicitações de API para essa operação. Depois que o token da sessão expirar, você faz outra chamada de API `CreateSession` para gerar um novo token de sessão e usá-lo. A AWS CLI e os SDKs da AWS vão criar e gerenciar sua sessão, até mesmo atualizar automaticamente o respectivo token para evitar interrupções no serviço quando uma sessão expira. Para ter mais informações sobre autorização, consulte [https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_CreateSession.html) na *Referência de API do Amazon S3*. Para saber mais sobre as operações de API de endpoint zonal, consulte [Autorizar operações de API de endpoint zonal com `CreateSession`](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-create-session.html). Se você não quiser substituir um objeto existente, adicione o cabeçalho condicional `If-None-Match` com o valor `‘*’` na solicitação `RenameObject`. O Amazon S3 retornará o erro `412 Precondition Failed` se o nome do objeto já existir. Para obter mais informações, consulte [https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html) na *Referência da API do Amazon S3*. `RenameObject` é uma operação de API de endpoint zonal (operação em nível de objeto ou de plano de dados) que é registrada em log no AWS CloudTrail. Você pode usar o CloudTrail para coletar informações sobre a operação `RenameObject` realizada em seus objetos em buckets de diretório. Para ter mais informações, consulte [Registro em log com o AWS CloudTrail para buckets de diretório](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone-logging.html) e [Exemplos de arquivos de log do CloudTrail para buckets de diretório](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-log-files.html). O S3 Express One Zone é a única classe de armazenamento que permite a operação `RenameObject`, que tem o mesmo preço das solicitações `PUT`, `COPY`, `POST` e `LIST` (por mil solicitações) no S3 Express One Zone. Para obter mais informações, consulte [Preço do Amazon S3](https://aws.amazon.com/s3/pricing/). ## Renomear um objeto Para renomear um objeto em um bucket de diretório, você pode usar o console do Amazon S3, a AWS CLI, SDKs da AWS, a API REST ou o Mountpoint para Amazon S3 (versão 1.19.0 ou posterior). ### Usar o console do S3 **Como renomear um objeto em um bucket de diretório** 1. Faça login no Console de gerenciamento da AWS e abra o console do Amazon S3 em [https://console.aws.amazon.com/s3/](https://console.aws.amazon.com/s3/). 1. No painel de navegação à esquerda, escolha **Buckets** e selecione a guia **Buckets de diretório**. Navegue até o bucket de diretório do Amazon S3 que contém o objeto que você deseja renomear. 1. Marque a caixa de seleção referente ao objeto que você quer renomear. 1. No menu **Ações**, selecione **Renomear objeto**. 1. Na caixa **Nome do novo objeto**, insira o novo nome do objeto. **nota** Se você especificar um nome de objeto que seja igual ao de um objeto existente, a operação não terá êxito e o Amazon S3 retornará o erro `412 Precondition Failed`. O comprimento do nome da chave do objeto não pode exceder 1.024 bytes. Os prefixos incluídos no nome do objeto entram na contagem do comprimento total. 1. Escolha **Renomear objeto**. O Amazon S3 renomeia o objeto. ### Usar a AWS CLI Os exemplos de `rename-object` mostram como você pode usar a AWS CLI para renomear um objeto. Para executar esse comando, substitua os {{espaços reservados para entrada do usuário}} por suas próprias informações. O exemplo a seguir mostra como renomear um objeto com uma verificação condicional na ETag do objeto de origem. ``` 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}}\"" ``` Esse comando faz o seguinte: + Muda o nome de um objeto de {{original-file.txt}} para {{new-file.txt}} no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Só renomeia se a ETag do objeto de origem corresponder a “{{a1b7c3d4e5f6}}”. Se a ETag não corresponder, a operação não terá êxito e exibirá um erro `412 Precondition Failed`. O exemplo a seguir mostra como renomear um objeto com uma verificação condicional no novo nome de objeto especificado. ``` 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}}\"" ``` Esse comando faz o seguinte: + Muda o nome de um objeto de {{original-file.txt}} para {{new-file.txt}} no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Só executa a operação de renomeação se o objeto existir e a respectiva ETag não corresponder a “{{e5f3g7h8i9j0}}”. Se já existir um objeto com o novo nome especificado e a ETag correspondente, a operação não terá êxito e exibirá o erro `412 Precondition Failed`. ### Usar SDKs da AWS ------ #### [ SDK for Java ] Você pode usar o AWS SDK para Java para renomear objetos. Para usar esses exemplos, substitua os {{espaços reservados para entrada do usuário}} por suas próprias informações. O exemplo a seguir demonstra como criar um `RenameObjectRequest` usando o AWS SDK para Java. ``` 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(); ``` Esse código faz o seguinte: + Cria uma solicitação para renomear um objeto de “{{key}}” para “{{new-key}}” no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Inclui a condição de que a renomeação só ocorrerá se a ETag do objeto corresponder a “{{e5f3g7h8i9j0}}”. + Se a ETag não corresponder ou o objeto não existir, a operação não terá êxito. O exemplo a seguir mostra como criar um `RenameObjectRequest` com uma condição de não correspondência usando o AWS SDK para Java. ``` 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(); ``` Esse código faz o seguinte: + Cria uma solicitação para renomear um objeto de “{{key}}” para “{{new-key}}” no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Inclui uma condição usando `.destinationIfNoneMatch(noneMatchETag)`, que garante que a renomeação só ocorrerá se a ETag do objeto de destino corresponder a “{{e5f3g7h8i9j0}}”. A operação não terá êxito e exibirá o erro `412 Precondition Failed` se um objeto com o novo nome especificado existir e tiver a ETag especificada. ------ #### [ SDK for Python ] Você pode usar o SDK para Python para renomear objetos. Para usar esses exemplos, substitua os {{espaços reservados para entrada do usuário}} por suas próprias informações. O exemplo a seguir demonstra como renomear um objeto usando o AWS SDK para 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}") ``` Esse código faz o seguinte: + Muda o nome de um objeto de {{source\_key}} para {{destination\_key}} no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Imprime uma mensagem de êxito se a renomeação do objeto for bem-sucedida ou uma mensagem de erro se ela não tiver êxito. O exemplo a seguir demonstra como renomear um objeto com as condições `SourceIfMatch` e `DestinationIfNoneMatch` usando o AWS SDK para Python (Boto3). ``` 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}") ``` Esse código faz o seguinte: + Executa uma operação de renomeação condicional e aplica duas condições, `SourceIfMatch` e `DestinationIfNoneMatch`. A combinação dessas condições garante que o objeto não foi modificado e que já não existe um objeto com o novo nome especificado. + Muda o nome de um objeto de {{source\_key}} para {{destination\_key}} no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Imprime uma mensagem de êxito se a renomeação do objeto for bem-sucedida ou uma mensagem de erro se as condições não forem atendidas. ------ #### [ SDK for Rust ] Você pode usar o SDK para Rust para renomear objetos. Para usar esses exemplos, substitua os {{espaços reservados para entrada do usuário}} por suas próprias informações. O exemplo a seguir demonstra como renomear um objeto no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}} usando o SDK para Rust. ``` 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(()) } ``` Esse código faz o seguinte: + Cria uma solicitação para mudar o nome de um objeto de “{{old-name.tx}}” para “{{new-name.txt}}” no bucket de diretório {{amzn-s3-demo-bucket--usw2-az1--x-s3}}. + Retorna um tipo `Result` para lidar com possíveis erros. ------ ### Uso da API REST Você pode enviar solicitações REST para renomear um objeto. Para obter mais informações, consulte [https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_RenameObject.html) na *Referência da API do Amazon S3*. ### Usar o Mountpoint para Amazon S3 A partir da versão 1.19.0 ou posterior, o Mountpoint para Amazon S3 permite a renomeação de objetos no S3 Express One Zone. Consulte mais informações sobre o Mountpoint em [Working with Mountpoint](https://docs.aws.amazon.com/AmazonS3/latest/userguide/mountpoint.html).