CopyObject (API de SOAP)
nota
Las API de SOAP para Amazon S3 no están disponibles para nuevos clientes y se acercan al fin de la vida útil (EOL) el 31 de agosto de 2025. Le recomendamos que utilice la API de REST o los SDK de AWS.
Descripción
La operación CopyObject crea una copia de un objeto al especificar la clave y el bucket de un objeto de origen y la clave y el bucket de un destino.
Al copiar un objeto, puede conservar todos los metadatos (opción predeterminada) o especificar metadatos nuevos. Sin embargo, la ACL no se conserva y se establece en private para el usuario que realiza la solicitud. Para invalidar la configuración de ACL predeterminada, especifique una nueva ACL al generar una solicitud de copia. Para obtener más información, consulte Uso de ACL.
Todas las solicitudes de copia se deben autenticar. Además, debe tener acceso de lectura al objeto de origen y de escritura al bucket de destino. Para obtener más información, consulte Uso de la autenticación de acceso.
Para copiar un objeto solo en determinadas condiciones, por ejemplo, si la ETag coincide o si el objeto se modificó antes o después de una fecha específica, use los parámetros de solicitud CopySourceIfUnmodifiedSince, CopyIfUnmodifiedSince, CopySourceIfMatch o CopySourceIfNoneMatch.
nota
Puede que necesite configurar el tiempo de espera del socket de la pila de SOAP para copiar objetos grandes.
Sintaxis de la solicitud
<CopyObject xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01"> <SourceBucket>source_bucket</SourceBucket> <SourceObject>source_object</SourceObject> <DestinationBucket>destination_bucket</DestinationBucket> <DestinationObject>destination_object</DestinationObject> <MetadataDirective>{REPLACE | COPY}</MetadataDirective> <Metadata> <Name>metadata_name</Name> <Value>metadata_value</Value> </Metadata> ... <AccessControlList> <Grant> <Grantee xsi:type="user_type"> <ID>user_id</ID> <DisplayName>display_name</DisplayName> </Grantee> <Permission>permission</Permission> </Grant> ... </AccessControlList> <CopySourceIfMatch>etag</CopySourceIfMatch> <CopySourceIfNoneMatch>etag</CopySourceIfNoneMatch> <CopySourceIfModifiedSince>date_time</CopySourceIfModifiedSince> <CopySourceIfUnmodifiedSince>date_time</CopySourceIfUnmodifiedSince> <AWSAccessKeyId>AWSAccessKeyId</AWSAccessKeyId> <Timestamp>TimeStamp</Timestamp> <Signature>Signature</Signature> </CopyObject>
Parámetros de la solicitud
| Nombre | Descripción | Obligatorio |
|---|---|---|
SourceBucket
|
El nombre del bucket de origen. Tipo: cadena Valor predeterminado: None Restricciones: un bucket de origen válido. |
Sí |
SourceKey
|
El nombre de la clave del objeto de origen. Tipo: cadena Valor predeterminado: None Restricciones: la clave de un objeto de origen válido al que tiene acceso de READ. |
Sí |
DestinationBucket
|
El nombre del bucket de de destino. Tipo: cadena Valor predeterminado: None Restricciones: debe tener acceso de WRITE al bucket de destino. |
Sí |
DestinationKey
|
La clave del objeto de destino. Tipo: cadena Valor predeterminado: None Restricciones: debe tener acceso de WRITE al bucket de destino. |
Sí |
MetadataDirective
|
Especifica si los metadatos se copian del objeto de origen o se sustituyen por los metadatos proporcionados en la solicitud. Tipo: cadena Predeterminado: COPY Valores válidos: COPY | REPLACE Restricciones: los valores distintos de |
No |
Metadata
|
Especifica los pares nombre-valor de los metadatos que se van a establecer para el objeto. Si MetadataDirective se establece en Tipo: cadena Valor predeterminado: None Restricciones: ninguna. |
No |
AccessControlList
|
Concede acceso a los usuarios mediante direcciones de correo electrónico o un ID de usuario canónico. Tipo: cadena Valor predeterminado: None Restricciones: ninguna |
No |
CopySourceIfMatch
|
Copia el objeto si su etiqueta de entidad (ETag) coincide con la etiqueta especificada; de lo contrario, devuelve un PreconditionFailed. Tipo: cadena Valor predeterminado: None Restricciones: ninguna. Si la ETag no coincide, el objeto no se copia. |
No |
CopySourceIfNoneMatch
|
Copia el objeto si su etiqueta de entidad (ETag) es diferente de la ETag especificada; de lo contrario, devuelve un error. Tipo: cadena Valor predeterminado: None Restricciones: ninguna. |
No |
CopySourceIfUnmodifiedSince
|
Copia el objeto si no se ha modificado desde el momento especificado; de lo contrario, devuelve PreconditionFailed. Tipo: dateTime Valor predeterminado: none |
No |
CopySourceIfModifiedSince
|
Copia el objeto si se ha modificado desde el momento especificado; de lo contrario devuelve un error. Tipo: dateTime Valor predeterminado: none |
No |
Sintaxis de la respuesta
<CopyObjectResponse xmlns="http://bucket_name.s3.amazonaws.com/2006-03-01"> <CopyObjectResponse> <ETag>"etag"</ETag> <LastModified>timestamp</LastModified> </CopyObjectResponse> </CopyObjectResponse>
Elementos de respuesta
A continuación, se muestra una lista de elementos de respuesta.
nota
La API de SOAP no devuelve espacios en blanco adicionales. Los espacios en blanco adicionales solo los devuelve la API de REST.
| Nombre | Descripción |
|---|---|
Etag
|
Devuelve la etag del nuevo objeto. La ETag solo refleja los cambios en el contenido de un objeto, no en los metadatos. Tipo: cadena Antecesor: CopyObjectResult |
LastModified
|
Devuelve la fecha en la que se modificó el objeto por última vez. Tipo: cadena Antecesor: CopyObjectResult |
Para obtener información sobre los elementos de respuesta generales, consulte Uso de encabezados de respuesta a errores de REST.
Errores especiales
No hay errores especiales para esta operación. Para obtener información acerca de errores de Amazon S3 generales, consulte Lista de códigos de error.
Ejemplos
En este ejemplo se copia el objeto flotsam desde el bucket pacific al objeto jetsam del bucket atlantic, conservando sus metadatos.
Solicitud de muestra
<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <SourceBucket>pacific</SourceBucket> <SourceObject>flotsam</SourceObject> <DestinationBucket>atlantic</DestinationBucket> <DestinationObject>jetsam</DestinationObject> <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId> <Timestamp>2008-02-18T13:54:10.183Z</Timestamp> <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature> </CopyObject>
Respuesta de ejemplo
<CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <CopyObjectResponse> <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag> <LastModified>2008-02-18T13:54:10.183Z</LastModified> </CopyObjectResponse> </CopyObjectResponse>
En este ejemplo, se copia el objeto “tweedledee” del bucket de wonderland al objeto “tweedledum” del bucket de wonderland, lo que sustituye sus metadatos.
Solicitud de muestra
<CopyObject xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <SourceBucket>wonderland</SourceBucket> <SourceObject>tweedledee</SourceObject> <DestinationBucket>wonderland</DestinationBucket> <DestinationObject>tweedledum</DestinationObject> <MetadataDirective >REPLACE</MetadataDirective > <Metadata> <Name>Content-Type</Name> <Value>text/plain</Value> </Metadata> <Metadata> <Name>relationship</Name> <Value>twins</Value> </Metadata> <AWSAccessKeyId>AKIAIOSFODNN7EXAMPLE</AWSAccessKeyId> <Timestamp>2008-02-18T13:54:10.183Z</Timestamp> <Signature>Iuyz3d3P0aTou39dzbq7RrtSFmw=</Signature> </CopyObject>
Respuesta de ejemplo
<CopyObjectResponse xmlns="http://doc.s3.amazonaws.com/2006-03-01"> <CopyObjectResponse> <ETag>"828ef3fdfa96f00ad9f27c383fc9ac7f"</ETag> <LastModified>2008-02-18T13:54:10.183Z</LastModified> </CopyObjectResponse> </CopyObjectResponse>
Activos relacionados
