Cambio del nombre de objetos en buckets de directorio - Amazon Simple Storage Service
Cambio de nombre de un objeto en un bucket de directorio

Cambio del nombre de objetos en buckets de directorio

Con la operación RenameObject, puede cambiar el nombre de forma atómica de un objeto existente en un bucket de directorio que utilice la clase de almacenamiento S3 Express One Zone, sin ningún movimiento de datos. Puede cambiar el nombre de un objeto especificando el nombre del objeto existente como origen y el nuevo nombre del objeto como destino dentro del mismo bucket de directorio. La operación de la API RenameObject no se realizará correctamente en los objetos que terminen con el carácter delimitador de barra diagonal (/). Para obtener más información, consulte Nomenclatura de objetos de Amazon S3.

La operación RenameObject normalmente se completa en milisegundos, independientemente del tamaño del objeto. Esta capacidad acelera aplicaciones como la administración de archivos de registro, el procesamiento multimedia y el análisis de datos. Además, RenameObject conserva todas las propiedades de los metadatos de los objetos, incluida la clase de almacenamiento, el tipo de cifrado, la fecha de creación, la fecha de última modificación y las propiedades de suma de comprobación.

nota

RenameObject solo se admite para objetos almacenados en la clase de almacenamiento de S3 Express One Zone.

Para conceder acceso a la operación RenameObject, le recomendamos que utilice la operación CreateSession para la autorización basada en sesión. En concreto, se concede el permiso s3express:CreateSession al bucket de directorio en una política de bucket o en una política basada en identidad. A continuación, realice la llamada a la API CreateSession en el bucket del directorio para obtener un token de sesión. Con el token de sesión en el encabezado de la solicitud, puede realizar solicitudes de API para esta operación. Una vez que caduque el token de sesión, realice otra llamada a la API CreateSession para generar un nuevo token de sesión para su uso. La CLI de AWS y los SDK de AWS crearán y administrarán la sesión, incluida la actualización automática del token de sesión para evitar interrupciones del servicio cuando una sesión caduca. Para obtener más información sobre la autorización, consulte CreateSession en la Referencia de la API de Amazon S3. Para obtener más información sobre las operaciones de la API de punto de conexión zonal, consulte Autorización de las operaciones de la API de punto de conexión zonal con CreateSession.

Si no quiere sobrescribir un objeto existente, puede agregar el encabezado condicional If-None-Match con el valor ‘*’ en la solicitud RenameObject. Amazon S3 devuelve un error 412 Precondition Failed si el nombre del objeto ya existe. Para obtener más información, consulte RenameObject en la Referencia de la API de Amazon S3.

RenameObject es una operación de la API de punto de conexión zonal (operación en el nivel de objeto o de plano de datos) que se registra en AWS CloudTrail. Puede usar CloudTrail para recopilar información sobre la operación RenameObject realizada en los objetos de los buckets de directorio. Para obtener más información, consulte Registro con AWS CloudTrail para los buckets de directorio y Ejemplos de archivo de registro de CloudTrail para buckets de directorio.

S3 Express One Zone es la única clase de almacenamiento que admite RenameObject, que tiene el mismo precio que las solicitudes PUT, COPY, POST y LIST (por cada 1000 solicitudes) en S3 Express One Zone. Para obtener más información, consulte Precios de Amazon S3.

Cambio de nombre de un objeto

Para cambiar el nombre de un objeto en el bucket del directorio, puede utilizar la consola de Amazon S3, la CLI de AWS, los SDK de AWS, la API de REST o Mountpoint para Amazon S3 (versión 1.19.0 o superior).

Cambio del nombre de un objeto en un bucket de directorio

  1. Inicie sesión en la AWS Management Console y abra la consola de Amazon S3 en https://console.aws.amazon.com/s3/.

  2. En el panel de navegación, elija Buckets y, a continuación, la pestaña Buckets de directorio. Desplácese hasta el bucket de directorio de Amazon S3 que contiene el objeto al que desea cambiar el nombre.

  3. Seleccione la casilla de verificación del objeto cuyo nombre quiera cambiar.

  4. En el menú Acciones, seleccione Cambiar el nombre.

  5. En el cuadro Nombre del nuevo objeto, introduzca el nuevo nombre del objeto.

    nota

    Si especifica el mismo nombre de objeto que un objeto existente, la operación producirá un error y Amazon S3 devolverá un error 412 Precondition Failed. La longitud del nombre de clave del objeto no puede superar los 1024 bytes. Los prefijos incluidos en el nombre del objeto se tienen en cuenta para la longitud total.

  6. Elija Cambiar nombre del objeto. Amazon S3 cambia el nombre de su objeto.

Los ejemplos de rename-object muestran cómo puede utilizar la CLI de AWS para cambiar el nombre de un objeto. Para ejecutar estos comandos, sustituya los marcadores de posición de entrada del usuario por ‎su propia información

El siguiente ejemplo muestra cómo cambiar el nombre de un objeto con una comprobación condicional en la ETag del objeto de ‎origen. 

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 \
    --source-if-match "\"a1b7c3d2e5f6\""

Este comando hace lo siguiente:

  • Cambia el nombre de un objeto de original-file.txt a new-file.txt en el bucket del directorio amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Solo cambia el nombre si la ETag del objeto de origen coincide con "a1b7c3d4e5f6".

Si la ETag no coincide, se produce un error 412 Precondition Failed en la operación.

El siguiente ejemplo muestra cómo renombrar un objeto con una comprobación condicional del nuevo nombre 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\""

Este comando hace lo siguiente:

  • Cambia el nombre de un objeto de original-file.txt a new-file.txt en el bucket del directorio amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Solo realiza la operación de cambio de nombre si el objeto existe y la ETag del objeto no coincide con “e5f3g7h8i9j0”.

Si ya existe un objeto con el nuevo nombre especificado y la ETag coincidente, la operación producirá un error 412 Precondition Failed.

SDK for Java

Puede utilizar AWS SDK para Java para cambiar el nombre de los objetos. Para utilizar estos ejemplos, sustituya los marcadores de posición de entrada del usuario con su propia información

En el ejemplo siguiente se muestra cómo crear una RenameObjectRequest mediante 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();

Este código hace lo siguiente:

  • Cree una solicitud para cambiar el nombre de un objeto de “clave” a “new-key” en el bucket del directorio de amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Incluye una condición de que el cambio de nombre solo se producirá si la ETag del objeto coincide con “e5f3g7h8i9j0”.

  • Si la ETag no coincide o el objeto no existe, la operación producirá un error.

En el siguiente ejemplo se muestra cómo crear una RenameObjectRequest con una condición de no coincidencia utilizando el SDK de AWS 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();

Este código hace lo siguiente:

  • Cree una solicitud para cambiar el nombre de un objeto de “clave” a “new-key” en el bucket del directorio de amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Incluye una condición mediante .destinationIfNoneMatch(noneMatchETag) que garantiza que el cambio de nombre solo se producirá si la ETag del objeto de destino no coincide con "e5f3g7h8i9j0".

La operación producirá un error 412 Precondition Failed si existe un objeto con el nuevo nombre especificado y tiene la ETag especificada.

SDK for Python

Puede utilizar el SDK para Python para renombrar los objetos. Para utilizar estos ejemplos, sustituya los marcadores de posición de entrada del usuario con su propia información.

El siguiente ejemplo muestra cómo cambiar el nombre de un objeto utilizando el SDK de AWS 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"{amzn-s3-demo-bucket--usw2-az1--x-s3}/{source_key}"
        )
        print(f"Successfully renamed {source_key} to {destination_key}")
    except ClientError as e:
        print(f"Error renaming object: {e}")

Este código hace lo siguiente:

  • Cambia el nombre de un objeto de source_key a destination_key en el bucket del directorio amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Imprime un mensaje de éxito si el cambio de nombre del objeto se realiza correctamente o imprime un mensaje de error si de produce un error.

El siguiente ejemplo muestra cómo cambiar el nombre de un objeto con las condiciones SourceIfMatch y DestinationIfNoneMatch mediante el SDK de AWS 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}")

Este código hace lo siguiente:

  • Realiza una operación de cambio de nombre condicional y aplica dos condiciones, SourceIfMatch y DestinationIfNoneMatch. La combinación de estas condiciones garantiza que el objeto no se haya modificado y que no exista ya un objeto con el nuevo nombre especificado.

  • Cambia el nombre de un objeto de source_key a destination_key en el bucket del directorio amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Imprime un mensaje de éxito si el cambio de nombre del objeto se ha realizado correctamente o imprime un mensaje de error si se produce un error o si no se cumplen las condiciones.

SDK for Rust

Puede utilizar el SDK para Rust para cambiar el nombre de los objetos. Para utilizar estos ejemplos, sustituya los marcadores de posición de entrada del usuario con su propia información.

En el siguiente ejemplo se muestra cómo cambiar el nombre de un objeto en el bucket del directorio amzn-s3-demo-bucket--usw2-az1--x-s3 mediante el SDK para Rust.

async fn basic_rename_example(client: &Client) -> Result<(), Box<dyn Error>> {
    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(())
}

Este código hace lo siguiente:

  • Crea una solicitud para cambiar el nombre de un objeto de “old-name.tx” a “new-name.txt” en el bucket del directorio amzn-s3-demo-bucket--usw2-az1--x-s3.

  • Devuelve un tipo de Result para gestionar posibles errores.

Puede enviar solicitudes REST para cambiar el nombre de un objeto. Para obtener más información, consulte RenameObject en la Referencia de la API de Amazon S3.

A partir de la versión 1.19.0 o superior, Mountpoint para Amazon S3 admite el cambio de nombre de objetos en S3 Express One Zone. Para obtener más información sobre Mountpoint, consulte Uso de Mountpoint.